Restructure documentation of HAL components

[hansu]

Hi,

I would like to restructure the documentation of the HAL components a little bit. I think a central overview would be nice.

Now some components are described in Basic HAL Reference and some in HAL Components. But a complete overview one get only on the man page.

And some entries in the table of contents are a little bit mixed up with the titles of the corresponding pages.

My idea is basically:

1. Move the sections 5. Logic Components and 6. Conversion Components from Basic HAL Reference to HAL Components
2. Add the remaining components from the man page
3. Display the components in groups

What do you think about that?

@andypugh by the way: Have a look at http://linuxcnc.org/docs/2.8/html/man/man9/demux.9.html - there is a part of the NAME section in the SYNOPSIS section instead of the synopsis

[andypugh]

I agree that the HAL components document should list every component in a structured way. It would be even better if some way could be found to display the manpage information from the master doc. The obvious way would be to link to the online manpage. (But that doesn't work offline)

The manpages are auto-generated by halcompile, which is why they are simply grouped together alphabetically. It is difficult to do it any other way.

With special regard to demux, it seems that, for some reason the triple-quoted two-line description gets split into the synopsis: https://github.com/LinuxCNC/linuxcnc/blob/2.8/src/hal/components/demux.comp Which is probably an easy fix, but also means that there is a way around the untidy double-synopsis in http://linuxcnc.org/docs/2.8/html/man/man9/bldc.9.html

[hansu]

Maybe it is possible to generate or extend the html from the manpages? Then it would be availabe offline But first, can you please explain how the html code of the is generated?

[andypugh]

At the moment we do not distribute offline html docs. The docs packages contain only PDF. However, I think that offline html is being looked at. (I have heard "Sphinx" mentioned, but all I can find is https://forum.linuxcnc.org/32-documents/38889-survey-the-state-of-the-documentations-and-ways-to-improve-it#164933 so possibly I saw it in passing on the IRC)

The docs generation process it almost indistinguishable from magic :-)

Most of the work is done by the docs submakefile It uses docbook and A2X in ways that I don't really follow. Google finds lots of ways to make manpages from Asciidoc, but rather few on the reverse process, which is what LinuxCNC does in places. I think that there is an XML layer, for fun, too.

[hansu]

Maybe we can add a category to every hal component. Then we can display the hal component list in these categories. Could that work? If there is a separate page for detailed information we can add a link to this page in the description column. So there would be always a complete list of all available components. If a component doesn't have a category, it is shown below 'Other'. It could look like this:

[silopolis]

Le ven. 11 déc. 2020 à 12:28, Hans470 notifications@github.com a écrit :

Maybe we can add a category to every hal component. Then we can display the hal component list in these categories. Could that work?

Like the idea

If there is a separate page for detailed information we can add a link to this page in the description column.

I'm lost in pages 😅

So there would be always a complete list of all available components. If a component doesn't have a category, it is shown below 'Other'. It could look like this:

Looks nice to me 👍

[andypugh]

A one-line description, from the "component" line should be a relatively easy change, as the info exists in the man page. Adding an extra tag to the comps (and hand-written manpages) would be a little more work, but doesn't seem impossible.

[hansu]

And a question would be where to put the list. Let it in the Man Page section, ore move to the HAL section. And we could highlight the components that are new in this version :star_struck:

[hansu]

Is it possible to create a branch on which I have rights to push? If yes I would appreciate that to be able to see the changes before I create a pull request.

Edit: But the doc is not accessible on the web server on every branch isn't it, or?

[andypugh]

Is it possible to create a branch on which I have rights to push?

The way to do that is to create a "fork" of LinuxCNC (a copy of LinuxCNC in your own Github repository) then clone that to your PC in a different directory to the linuxcnc-dev one. You can then make a "pull request" from your forked repository back to LinuxCNC when you are happy with the changes. (And, as it is your own repository, you can make as many mistakes as you want and nobody knows)

There is a bit of housekeeping, you need to keep your fork up to date with LinuxCNC, which isn't automatic and you probably want to "squash" all your commits into one (or a small number) to keep the history simple.

[hansu]

Yes I did that as you know because you merged my pull request ;-) But how to access the webserver with these changes? For example: #993 How to see this version on the webserver? http://linuxcnc.org/docs/<branch?> does only work for the main branches I guess...

[andypugh]

Sorry to take so long to respond, I missed the question part.

To see the new version of the docs you would need to compile them on your PC and view that local version.

cd linuxcnc-dev/src ./autogen.sh ./configure --enable-build-documentation=pdf,html make

Will build both sets of docs (there are quite a few dependencies for building docs, be prepared to install a few packages such as asciidoc)

The generated docs will end up in the top level of linuxcnc-dev/docs

[hansu]

Thanks, I will try that when I have set up by build system.

[hansu]

I got it working, thanks! And a new idea came into my mind. What about prettifying the html representation the man pages? I added the doc stylesheet to the man page generation and figured out how to add pictures to the man pages which are used only for html generation. The advantage in comparison to a separate doc page is that you have all information bundled at one point. But it is not so comfortable and you have not so much possibilities to format the doc page in groff. So if there is a complex hal component that needs more documentation, a link to a separate page can be added in the man page or in the overview page.

Here you can see how the man pages would look with the stylesheet and I added a picture to the toggle2nist component for example: https://github.com/LinuxCNC/linuxcnc/compare/master...Hans470:2.8-restructure-hal-doc For a quick look without compiling see here: example.zip

So if you agree with that, only the task of categorisation is left. What about having an assignment table which defines the component's category. So there would be no need for adding an extra parameter to the hal comps. If there is no category defined, for e.g. a new component it would be displayed below uncategorised/other.

[andypugh]

Yes, the styled html is certainly better.

I still can't decide if the category should be stored in the manpage (by hand, or from a tag in the .comp) or whether a separate table is best. The table might as well be hard-coded statements in the submakefile, I think. There is probably no point parsing a table in the makefile when it could just be directly coded. It would be the same people editing the content.

[hansu]

Hmm I would suggest to complete the list in http://linuxcnc.org/docs/2.8/html/hal/components.html and add links to the man pages as I am not so experienced with makefiles. Like this way:

[andypugh]

@jethornton Do you have any thoughts on this?

[jethornton]

Reading all the posts now.

JT

On 1/8/2021 3:23 PM, andypugh wrote:

@jethornton https://github.com/jethornton Do you have any thoughts on this?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/LinuxCNC/linuxcnc/issues/996#issuecomment-757004634, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABJTFPDJL7PI7DSY4LACHKLSY5ZUZANCNFSM4UOM36HQ.

[jethornton]

I like this idea, I'd have to look and see if links to the man pages is possible with our current system.

Regarding Sphinx I use it for all my projects and it would require a complete make over for our current docs.

JT

On 1/8/2021 12:21 PM, Hans470 wrote:

Hmm I would suggest to complete the list in http://linuxcnc.org/docs/2.8/html/hal/components.html http://linuxcnc.org/docs/2.8/html/hal/components.html and add links to the man pages as I am not so experienced with makefiles. Like this way: image https://user-images.githubusercontent.com/67957916/104050100-5aa4a680-51e6-11eb-9333-03c53a29149c.png

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/LinuxCNC/linuxcnc/issues/996#issuecomment-756920062, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABJTFPCL2UCHE2YYFRE2SGDSY5EKHANCNFSM4UOM36HQ.

[hansu]

As here is nothing to do for me at the moment I pushed my changes so far: https://github.com/LinuxCNC/linuxcnc/pull/1052

[hansu]

Time to continue on this topic :)

I would like to generate a list of all HAL components (based on all files in man9 folder) in the HAL section of the docs (http://linuxcnc.org/docs/devel/html/hal/components.html).

So that it looks like this for example:

And for the categories I could imagine to add a heading named 'CATEGORY' to each man page. That category will be used for grouping above-mentioned. This will also be displayed in the man pages, but I think that doesn't annoy: (If someone feels annoyed by that, I think we'll find an invisible solution)

But that brings a problem for the PDF docs: Because the man pages are an extra document, the links in the HAL section will not work in the PDF. Solution for that could be:

• Adding the HAL-pdf to the main-doc-pdf
• Move the categorized HAl-list to the man page section and the man-pdf

What are your opinions about that?

Additionally - what about providing a complete zipped HTML-doc as a download?

[andypugh]

I think that a categorised list of HAL components would have to be done by hand (just to get the categories right). I am probably one of the logical choices to compile this, as I know HAL better than most.

A downloadable HTML doc might be a good idea. I tend to forget that some people might not be permanently online.

[hansu]

Yes of course the categories have to be chosen by hand. But we have three options generally:

• complete the current static categorized list
• generate a list based on a category entry in the man page
• generate a list with having a data dictionary that specifies which component belongs to which category

(1) would be ok by now, but if new components are added, they might be forgotten to be added to the list. So that's the idea of the generated list that looks into the directory. And all new components could be shown under "other" or "uncategorized". But that didn't solve the PDF issue.

A downloadable HTML doc might be a good idea. I tend to forget that some people might not be permanently online.

I think that's why we have the PDF version ;-)