WIP: Added first skeleton of a coding style for asciidoc #1530
Conversation
|
A pointer to the cheat-sheet on https://powerman.name/doc/asciidoc should be added. Tables should likely get something alike |
|
section title links are wanted? https://docs.asciidoctor.org/asciidoc/latest/sections/title-links/ autogenerated sectionids not to be consistent across languages? https://docs.asciidoctor.org/asciidoc/latest/sections/auto-ids/ Custom IDs should be above the section ID according to https://docs.asciidoctor.org/asciidoc/latest/sections/custom-ids/ (and it makes sence) - this I have messed up in my po4a-related changes. |
|
The cross-references style should be decided. My po4a changes ruined quite some image captions. I should instead have removed the alt text when this was identical to the caption and po4a was complaining. Anyway - the documentation style guide should explain about how much text it expects below an image. The captions today are basically just titles of an image, no description of what is seen in the image. |
docs/src/code/style-guide.adoc
Outdated
| Documentation is written in asciidoc, which includes parts of the | ||
| UNIX man pages. |
There was a problem hiding this comment.
I don't understand the "includes parts of of the UNIX man pages" !? Do you mean that parts of the documentation are in form of man pages ?
There was a problem hiding this comment.
Yes. For most of the small Hal components there is only documentation available as man page.
There was a problem hiding this comment.
po4a could not handle the alt image descriptions
I have circumvented much of the "alt=" instances in the docs, but thinking about it and having read a bit more about it in the asciidoc documentation, this likely is more of a po4a bug.
docs/src/code/style-guide.adoc
Outdated
| languages. And executables implemented in any of these languages | ||
| may be called from anywhere, mostly from the scripting languages. | ||
|
|
||
| Every computer language is its very own syntax and customs to be structured, |
docs/src/code/style-guide.adoc
Outdated
|
|
||
| In the code portion of a .comp file, follow normal C coding style. | ||
|
|
||
| == Code describing the functionality for the human |
There was a problem hiding this comment.
I'd add ", i.e. Documentation" at the end
docs/src/code/style-guide.adoc
Outdated
|
|
||
| == Code describing the functionality for the human | ||
|
|
||
| This is a very recent (1/2022) part of this document. Please help shaping it if you are familiar with asciidoc. |
There was a problem hiding this comment.
If we stick to fixed line width, A CR should be inserted at the end of the first sentence.
docs/src/code/style-guide.adoc
Outdated
| There are two basic documents, i.e. the | ||
| * Users' Guide and the | ||
| * Developers' Guide |
There was a problem hiding this comment.
What about Integrator's ?
docs/src/code/style-guide.adoc
Outdated
| Every file should start with a header. This is typically | ||
| ---- | ||
| :lang: en | ||
| ---- |
There was a problem hiding this comment.
Shouldn't code blocks be surrounded by blanck lines ?
There was a problem hiding this comment.
Let's decide: Yes. :)
docs/src/code/style-guide.adoc
Outdated
| and longer documents may also chose to set | ||
| ---- | ||
| :toc: | ||
| ---- |
There was a problem hiding this comment.
I personnaly find that any document benefits from being introduced by an outline of its structure.
There was a problem hiding this comment.
Well, when these are on their own, yes. But our documents are typically included as part of another envelope document which provides an index. Some texts are so long that these should have a toc on their own, others maybe not.
docs/src/code/style-guide.adoc
Outdated
| If a chapter/section header shall be granted the option to be | ||
| referenced from another part of the documentation then it needs an achor. | ||
| The anchor shall be a combination of an indicator of the kind | ||
| of block that is referenced (cha,sec,fig,tab,...) together with a | ||
| short name identifying the object. |
There was a problem hiding this comment.
I'd be in favor of anchoring every chapter/section header, as well as every special/rich content blocks like tables, figures,...
Past these, subs of special interest should also be anchored.
There was a problem hiding this comment.
With weblate activated, only the English texts will be edited. It may be preferable to only have anchors when they are indeed needed since this would possibly also incentivize a grep for other occurences when some extra info is added.
docs/src/code/style-guide.adoc
Outdated
| * index entries for titles and other blocks | ||
|
|
||
| ? |
There was a problem hiding this comment.
I'd be in favor of indexing every chapter/section header, as well as every special/rich content blocks like tables, figures,...
Past these, subs of special interest should also be indexed.
Using sub entries, a nicely structured extensive index could be built.
There was a problem hiding this comment.
This refers to https://docs.asciidoctor.org/asciidoc/latest/sections/user-index/ and the (((names))) specified throughout the texts.
How do we deal with translations? Leave the English and have translations as secondary indices? Vice versa? Only the Translation?
There was a problem hiding this comment.
Yes it does.
For the most part, I think we should have only translations. For specific and/or hardly translatable entries, a proper use of "see also".
Found https://web.archive.org/web/20180115025406/http://chimera.labs.oreilly.com:80/books/1234000001578/ch02.html#expand a good reference.
There was a problem hiding this comment.
Thinking about it, we may not have an opportunity to decide about translations - weblate either picks it up or it doesn't.
There was a problem hiding this comment.
You're right indeed... On second thought, it's more probably a po4a thing, Weblate only seeing what the first has decided to put in po files.
docs/src/code/style-guide.adoc
Outdated
| ---- | ||
|
|
||
| - reference | ||
|
|
There was a problem hiding this comment.
An entry about code blocks is also needed.
Found this https://blog.mrhaki.com/2019/12/awesome-asciidoctor-auto-number-callouts.html?m=1 very good for callouts in code blocks.
|
|
About directories and files organization, as I find it perfectly clean and easy to understand, as well as I think Antora could/should be part of LinuxCNC future, I hope we can adopt the tree structure described here in the official documentation. Edit: If you're not convinced, I invite you to have a look at the beautiful documentation source trees of https://docs.asciidoctor.org like the one for Asciidoc language and the master playbook Edit2: For a quick intro to Antora https://github.com/owncloud/docs/blob/master/docs/what-is-antora.md |
|
I like it. |
|
Finally, for today ;), ownCloud documentation guidelines etc are a veeery interesting source of inspiration ! |
|
Also we have this file https://github.com/LinuxCNC/linuxcnc/blob/master/docs/help/asciidoc-markup.adoc, which is actually in spanish that we should translate and merge or simply drop once we're done here. |
|
The conflict is just a heading level. Which I feel underqualified to fix. |
smoe
changed the title
|
I should sync with @silopolis a bit more before merging. |
|
I think I create a feature branch locally for that, still have to push to GH. |
|
I discovered several .adoc files referred to other parts of the documentation three using direct links to linuxcnc.org. This make it harder to navigate the generated HTML text than necessary, and might lead the user into the wrong version of the document. The style guide should mention that internal links should use link:../path/to/sibling.html when pointing to sibling documents. |
|
And also these links are not included in the link checking, right? |
|
[Hans]
And also these links are not included in the link checking, right?
I believe they are. At least
#1827 failed in the link
check. Trying to figure out how to solve it. Seem like the man page
HTML files are generated at the wrong time for checkrefs_en to find
them.
…--
Happy hacking
Petter Reinholdtsen
|
Interesting. Furthermore comes into my mind, that we should change the links to the current version instead of the general link where its not possible to use relative links like in man pages. So http://linuxcnc.org/docs/html/ should be changed to http://linuxcnc.org/docs/html/ so that the links still point to the correct version when there is a new release. |
|
[Hans]
And also these links are not included in the link checking, right?
[Petter Reinholdtsen]
I believe they are.
[Hans]
Interesting.
Hm, are we talking past each other. I took 'these links' to mean the
local links, not the remote ones. Are you talking about the remote
links? Remote links are not checked. In fact, the problem I ran into
with checkref_en is that the links that should have been internal, but
instead were remote, are in fact also broken. Thus the check will
report a broken link when I make them internal.
Furthermore comes into my mind, that we should change the links to the
current version instead of the general link where its not possible to
use relative links like in man pages. So
http://linuxcnc.org/docs/html/<page> should be changed to
http://linuxcnc.org/docs/<version>html/<page> so that the links still
point to the correct version when there is a new release.
I believe we should do our best to avoid remote links like that
completely instead.
…--
Happy hacking
Petter Reinholdtsen
|
I had these cases in mind where you refer to further documentation like the docs page from a man page. |
|
@smoe Do you have time to brush up this proposal? We should try to get it into master to be able to point people to it. Perhaps the style guide content can be a topic for the next meeting? |
Invitation sent. |
|
Concerning the coding style document I am not as happy as I want to be. It was not fun to read. And I do not have any immediate idea how to change that. Most parts are copied from somewhere else, from what I have understood. Rather than copying that, I think we should just have something like "we do it like they do, please read ... if this guide does not help you" and not copy from there. What then remains are a set of questions we should decide for ourselves:
What compromises are we doing today because asciidoc is limited compared with LaTeX
So, executive summary, I hope to shorten this all - dramatically - and have only the LinuxCNC-relevant parts left. Best, |
:(
You mean like they did?: https://docs.zephyrproject.org/2.2.0/contribute/index.html#coding-style
That we can take from #2062 |
|
Le mar. 27 sept. 2022 à 13:54, Steffen Möller ***@***.***> a
écrit :
You can work on this if Steffen adds you as a maintainer to his fork
Invite sent.
Received and sent mine in return, thanks :)
I jumping on it...
|
Sorry.
That seems fine to me.
Should we integrate the glossary of weblate into what may serve as a reference for spelling? |
|
Le mar. 27 sept. 2022 à 14:02, Steffen Möller ***@***.***> a
écrit :
Concerning the coding style document I am not as happy as I want to be. It
was not fun to read. And I do not have any immediate idea how to change
that.
😬😢
Most parts are copied from somewhere else, from what I have understood.
#2062 is at very early drafting stage. To begin with, and because I believe
and more extended "Documentarian guide" than a bare AsciiDoc reference, I
started with the GitLab style guide and made a first pass at adapting it
for us and immediately pushed it so that I get this kind of feedback.
As you may know me and my taste for long documents, the plan is clearly to
split it somehow into biteable chunks... Beginning with pulling out the
AsciiDoc reference part of it and of the guide here and merging them.
Depending on how it turns, I also try a table format like the Red Hat's one:
https://redhat-documentation.github.io/asciidoc-markup-conventions/
Rather than copying that, I think we should just have something like "we do
it like they do, please read ... if this guide does not help you" and not
copy from there.
Pondered the idea several times, but I believe it is an interesting and
valuable work for the project to assemble and devise it's own. I believe
our project is specific enough to hardly fit into another one's shoe. Good
news is I think that combining, stripping and adapting the following ones,
we can make ourselves a nicely suited comprehensive reference guide for all
our content creators.
https://docs.gitlab.com/ee/development/documentation/
https://redhat-documentation.github.io/
https://github.com/nofluffjuststuff/nfjsmag-docs/blob/master/author-writing-style-and-syntax-guide.adoc
https://www.writethedocs.org/guide/
What then remains are a set of questions we should decide for ourselves:
- how do we write pin/functions/other LinuxCNC bits
- how do we format tables
- how do we spell various components of LinuxCNC
- ...
This is coming...
What compromises are we doing today because asciidoc is limited compared
with LaTeX
- captions
- references
Can you elaborate please ?
So, executive summary, I hope to shorten this all - dramatically - and
have only the LinuxCNC-relevant parts left.
I believe the frameworks and content of the guides above can be made
relevant and beneficial to the LinuxCNC project.
|
|
Le mar. 27 sept. 2022 à 16:13, Steffen Möller ***@***.***> a
écrit :
What then remains are a set of questions we should decide for ourselves:
how do we write pin/functions/other LinuxCNC bits
how do we format tables
how do we spell various components of LinuxCNC
...
That we can take from #2062
<#2062>
Should we integrate the glossary of weblate into what may serve as a
reference for spelling?
Always hoped we could use/integrate Weblate glossary into our
documentation, but how to do it remains to be found...
Spelling ref, or word list looks like another kind of document and merging
them may annoy users, but Red Hat doesn't do a bad job at making it nice
and maybe clear enough
https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/documentation/styleguide/word_list.md?plain=1
https://redhat-documentation.github.io/supplementary-style-guide/#glossary-terms-conventions
|
|
The most important bit I think is that the project accepts those style guide rules as their own, and not as something that was imposed on them. Otherwise, following rules is not fun. That could likely be reached as
and all should be as short as possible. Concerning differences to LaTeX, I see
|
silopolis
force-pushed
the
motivate_asciddoc_coding_style_instructions
branch
from
e93bbbd to
58f38f3
Compare
|
OK teammates, first two preliminary commits to put a little bit more structure here. I know some files are "light", but they'll expand. Split out translation as it didn't fit in style guide and plan to pull relevent sections from docs/README to complete it. I will now concentrate on the style-asciidoc.adoc trying to keep it as close to an special AsciiDoc ref guide as possible. I'll propose more content targeted at documentation management later... |
silopolis
force-pushed
the
motivate_asciddoc_coding_style_instructions
branch
from
58f38f3 to
0786fc0
Compare
|
Le lun. 26 sept. 2022 à 16:44, Hans Unzner ***@***.***> a
écrit :
How do you push commits to a branch that's not yours ? 🤔 How can I work
on this too ?
Because I'm a maintainer and the author of this PR didn't prohibit it ;-)
[image: image]
<https://user-images.githubusercontent.com/67957916/192302104-9c2efc30-fdfd-4992-b47c-28ca4f23a74b.png>
You can work on this if Steffen adds you as a maintainer to his fork.
With the pair of reviews I did today, I just hope he won't shoot me in the
knee... Dear @smoe, would you please allow me to work on this too ?
What I don't like here is that we again have one file for everything. I'd
rather have one per language and have them gathered somehow in adequate
ways for online and print, like a navigation menu and/or a parent document.
Maybe one for "real source code" and one for the formatting language(s).
Otherwise the file for the Python style would be a very small one for
example :D
I have wet dreams of a code/API documentation effort sometime in the future
as a LCNC programmer wannabe exercise, so this may change someday ;)
But let's discuss that in a small video chat when I got rid of the cold.
oh sh*ù, hope you'll recover quickly...
|
|
@silopolis - you have all permissions, I think/hope, but feel free to just take it and push it to some branch of yours. I have long forgotten this PR was out. |
|
Le mar. 11 oct. 2022 à 18:47, Steffen Möller ***@***.***> a
écrit :
@silopolis <https://github.com/silopolis> - you have all permissions, I
think/hope, but feel free to just take it and push it to some branch of
yours. I have long forgotten this PR was out.
I do and already started pushing into it, thanks 👍🙏
I keep hope to push more this week, but beginnings with Mastercam have been
rougher than expected. Looks like they designed the UI to make you buy
training ! :/
|
|
the Norwegian linuxcnc meeting approves this change. |
|
I just stubled into this again and fixed the conflict with the current master. If all goes well then I give this a spin next week again. @BsAtHome, somehow I feel you are the kind of individual who may also want to influence this all a bit. After all, some yamllint, shellcheck, cppcheck hygiene should be part of the coding practices but had not found entry to the project when these lines were drafted. |
@smoe, there is also a lot of clutter in docs that could use a broom to cleanup and reorganize ;-) Actually, the build failed when I recently tried to build the docs. The makefile ended in an infinite loop. Maybe because it could not build in parallel, or something else. I don't know (yet). But, when I investigated a bit, my immediate conclusion was that the whole doc building process should be considered fragile. For example, I think there needs to be a clear separation between conceptual documentation, as in read-the-docs style information and man-page stuff. The build-process should be re-thought. Also, the halcompile man-pages should all be generated in asciidoc format to make it consistent. ... and this is just the start of my thoughts ... |
;) Thank you for your stimulating reply. Many "yes"es from my side. The problem is that this all takes an enormous amount of time to address. And some folks take considerable pride in their documentation and do not want to see it touched, even though I consider it barely readable. And we have to accept that we all read documentation differently. My not so secret plan is/was that we make everything a bit nicer first - just for the immediate impression of the eye while skimming through the documentation or for the ones performing a code review. And when everyone has understood that the folks stay around and mean well, then I hope that we can also have a bit more like structural changes. Typically having pictures is well received, so let's have more of them with high-quality captions. The shellcheck and cppcheck bits I consider as something like "functional cosmetics". It looks good. The documentation is a never-ending story, takes enormous time. While translating to German I have fixed many typos etc in the original. But those many smallish bits are also demanding for the reviewers, especially when the highlighting of asciidoc in your editor and the LinuxCNC differs in its interpretation and I keep making the same mistakes :-/ . Everything takes time And since we have the translations, every change drags in extra changes from translators. So I hope for finding ways to mostly rearrange paragraphs (that should not affect the translations) and not needing too many smallish changes within. My suggestion is to prioritize it all a bit for what it read by whom the most often. IMHO we should have everything guiding newbies to their first chips in a way that is mostly flawless and as well-done as possible. And then we should have something like bridges that guide towards tinkering that should be somehow easy and inviting to follow, also fun, preferably. And then we have the reference documentation and finally we have the source code. Completely weird is the lack of a reference to QtPyVCP in the documentation. Yes, it is not part of the project, but so what. Everything about it is nice. Many folks installing LinuxCNC do not look at anything else. I want more like it. And the LinuxCNC core folks should visibly embrace them. Same for those emerging Rust rewrites. We need some "incubator-spirits". A transition from libnml to ZeroMQ would modernize the LinuxCNC source tree and look good. And give us some extra freedom. So this would also be on my list of beautifications I would like to see. |
|
Yes,... I just looked at LinuxCNC_Documentation.pdf... It is a 1335 page monster. Its contents is 55 pages. How is anyone supposed to find anything? At least there is an index. Most of the documentation is IMNSHO not written with a user's perspective in mind. It has been written from the developer's perspective. I do not blame anybody for the format. It is a very common problem in many other open projects. Even I have been guilty of using the developer's perspective in some of my writings. Documentation is hard to write and hard to keep up-to-date. Developers are generally lousy documentation writers. No offense, just a fact of life. But that does not mean we can't do better. The whole docs system needs an overhaul with focus on what needs to be conveyed to whom. |
7 participants
First shot to address #1529
I did not want to separate it from the coding instructions since we regular code and documentation share weblate, some common features like tabs/indenting and the documentation is also a regular part of the source tree.
I forgot about @silopolis' very valid points on the integration of the glossary.