documents hyperlinks

I was wondering why few hyperlinks are provided in the documentation between the hal components and their manuals

is there anyway a noob like me could assist with documentation to make it a little easier to read the general description of the hal components and link to the component manuals..... and maybe add a few examples or some expanded descriptions.

as a noob I'm obviously spending a lot of time in the documentation (master branch) via html

linuxcnc.org/docs/devel/html/hal/components.html

linuxcnc.org/docs/html/man/man9/toggle2nist.9.html

thanks John I'll go and have a look and learn with git

robertspark wrote:

I was wondering why few hyperlinks are provided in the documentation between the hal components and their manuals

is there anyway a noob like me could assist with documentation to make it a little easier to read the general description of the hal components and link to the component manuals..... and maybe add a few examples or some expanded descriptions.

as a noob I'm obviously spending a lot of time in the documentation (master branch) via html

linuxcnc.org/docs/devel/html/hal/components.html

I've always wondered why that page exists because its hopelessly outdated and there are many components that it does not mention.
I've been playing with Linuxcnc for 5 years and still spend a lot of time in the docs.
Before you embark on the project, its important to understand that most of the Linuxcnc docs are generated from the source code.
I tried to update some docs recently with the intention of creating a pull request but got caught out with the spanish translation so take care.

thanks Rod, all part of the learning curve.

couple of noob questions (I've used git to clone repositories, download and update them, never done a pull request.... still reading up on git as I used it to clone libraries for Arduino bits so that I always have a copy in case the master repository disappeared).

the questions are

1) what language / tool is the documentation written in (syntax?)

2) how does everyone edit the documentation? do you just use a text editor or an ide or some programs?

I am just looking at that one page, in an effort to make it a bit better for referencing / linking not reinventing the wheel....

github.com/LinuxCNC/linuxcnc/blob/master...c/hal/components.txt

I can see + understand the structure and syntax of the page for hyperlinks and can edit it with a text file editor, but just wondered if I should be using something specific.

final thing...

I noticed there are three components files, English, French and Spanish. they all have different revision dates so are probably out of sync....
does everyone just use Google translate for the other languages? (not sure how accurate Google translate really is.... I speak about 4 languages (can get by in) but I only read and write in 1 so have no idea if the Google translate output is a bit like a Chinese hardware technical manual when translated from English to something else or if it's fairly good?)

github.com/LinuxCNC/linuxcnc/tree/master/docs/src/hal
last updated
English 2 months ago
Spanish 8 months ago
French 5 years ago!

thanks in advance for guidance or comments

>> RTM>>> working my way thorough linuxcnc.org/docs/devel/html/code/contributing-to-linuxcnc.html

I started to clean up and order a little bit the docs to have the main documentation in the man pages and not on multiple locations.
I found a nice way to create timing diagrams like in toggle2nist and embed is as image that is shown in PDF and HTML See github.com/LinuxCNC/linuxcnc/blob/master...mages/Images_info.md

rodw wrote:

I've always wondered why that page exists because its hopelessly outdated and there are many components that it does not mention.

robertspark wrote:

I was wondering why few hyperlinks are provided in the documentation between the hal components and their manuals

I only made some links in linuxcnc.org/docs/devel/html/hal/components.html as example because it would be better to generate that list/links automatically by the build process to not have a incomplete list like it is now.
J. Thornton want to dig into this if the has time, see github.com/LinuxCNC/linuxcnc/issues/996#issuecomment-757543905

@robertspark see also the whole Issue for additional information.

@ropertspark:

Regarding your questions:

1) The HTML documentation is written in ASCIIDOC. But the man pages are written in Troff/Groff. Either directly in a *.1, *.3 or *.9-file like github.com/LinuxCNC/linuxcnc/blob/master...s/man/man9/counter.9. Or the Groff syntax in embedded in the hal-components in the section "description" like github.com/LinuxCNC/linuxcnc/blob/master...nts/toggle2nist.comp
The man pages then can be acessed as man pages in the bash, are converted to a HTML representation and also are packed into the PDF documentation.

2) Just a simple text editor and the docs for Groff. Something like that:
man7.org/linux/man-pages/man7/groff.7.html
man7.org/linux/man-pages/man7/groff_man.7.html
man7.org/linux/man-pages/man7/groff_www.7.html

if you need further help, feel free to ask.
It would be nice if you can continue improving the man pages docs. But pay attention because they are used in three different ways.

Hans

BigJohnT wrote:

Looks like someone has cracked the code in 2.8 and master to link to the man page at least in the html that works, unsure of what happens in the PDF documents.

not:: (((not)))Inverter. link:../man/man9/not.9.html[Details]

JT

Yes, you are right the links doesn't work in the PDF version. Shame on me . But the PDF version targets to be a offline version, so the links to the website are not so important I think. As the PDF man pages are described in a separate document even linking to this would not be difficult. The best would be to leave it out at this location.

Hans