documents hyperlinks

More
03 Apr 2021 19:03 #204648 by robertspark
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

Please Log in or Create an account to join the conversation.

More
03 Apr 2021 20:41 #204664 by BigJohnT
Replied by BigJohnT on topic documents hyperlinks
IIRC in the past we could not link to the man pages from the main documents. Perhaps it's possible now.

linuxcnc.org/docs/2.8/html/code/contributing-to-linuxcnc.html

I'm not sure how the process of doing a pull request works as I've always had push rights.

After you clone with git the documents are in of all places /docs. Read the readme file for instructions on how to work on the docs.

Make sure the docs build without errors after making a change. The readme fails to tell you that make docs will only build docs.
To Build
cd emc/src
./autogen.sh
./configure --enable-build-documentation > /home/john/Desktop/configure.txt 2>&1
make clean > /home/john/Desktop/make_clean.txt 2>&1
make docs > /home/john/Desktop/make_docs.txt 2>&1

Change the directory name to your directory. The redirect sends the output to txt files so you can search for errors if you get them.

BTW, I started reworking the docs in the same ship as you... new not know how and confused by the docs 15 years ago.

JT
The following user(s) said Thank You: robertspark

Please Log in or Create an account to join the conversation.

More
03 Apr 2021 20:47 #204666 by robertspark
Replied by robertspark on topic documents hyperlinks
thanks John I'll go and have a look and learn with git

Please Log in or Create an account to join the conversation.

More
04 Apr 2021 05:29 #204714 by rodw
Replied by rodw on topic documents hyperlinks

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.

Please Log in or Create an account to join the conversation.

More
04 Apr 2021 09:06 - 04 Apr 2021 11:03 #204721 by robertspark
Replied by robertspark on topic documents hyperlinks
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
Last edit: 04 Apr 2021 11:03 by robertspark.

Please Log in or Create an account to join the conversation.

More
04 Apr 2021 11:34 - 04 Apr 2021 12:27 #204739 by hansu
Replied by hansu on topic documents hyperlinks
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.
Last edit: 04 Apr 2021 12:27 by hansu.
The following user(s) said Thank You: robertspark

Please Log in or Create an account to join the conversation.

More
04 Apr 2021 11:43 #204742 by hansu
Replied by hansu on topic documents hyperlinks
@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
The following user(s) said Thank You: BigJohnT, robertspark

Please Log in or Create an account to join the conversation.

More
04 Apr 2021 12:53 #204756 by BigJohnT
Replied by BigJohnT on topic documents hyperlinks

rodw wrote: [
Before you embark on the project, its important to understand that most of the Linuxcnc docs are generated from the source code.


Only a few of the man pages are build from the source code. The majority of the docs are done separately.

JT

Please Log in or Create an account to join the conversation.

More
04 Apr 2021 13:01 - 04 Apr 2021 13:04 #204757 by BigJohnT
Replied by BigJohnT on topic documents hyperlinks
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
Last edit: 04 Apr 2021 13:04 by BigJohnT.

Please Log in or Create an account to join the conversation.

More
04 Apr 2021 14:32 #204768 by hansu
Replied by hansu on topic documents hyperlinks

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 :whistle: . 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

Please Log in or Create an account to join the conversation.

Time to create page: 0.311 seconds
Powered by Kunena Forum