LinuxCNC is Poorly Documented

More
28 Jun 2018 23:19 - 28 Jun 2018 23:19 #113039 by andypugh

BrendaEM wrote: Some years ago, LinuxCNC entered into the brainshare of the geekset. I downloaded a copy of the distro, just to try it out. It seemed pretty neat. I also checked out PyCAM, which I think also should be included with LinuxCNC's disk, ?


PyCAM seems to have been picked up by Seb Kuzminsky. He is one of the LinuxCNC developers (and, in fact, I think he was release manager for LinuxCNC 2.7.) So there is a fair chance that PyCAM might find its way on to the DVD.
Last edit: 28 Jun 2018 23:19 by andypugh.

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

More
28 Jun 2018 23:20 #113040 by BrendaEM
: )

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

More
28 Jun 2018 23:28 #113041 by BrendaEM
Chris M, I will write a page of documentation.

I discussed what little I know, of LinuxCNC from 36:00, for about 20 minutes. I want like to redo the video, but I have to get a widescreen monitor out there, and set up OBS for screen capture.

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

More
29 Jun 2018 11:00 #113078 by rodw
Replied by rodw on topic LinuxCNC is Poorly Documented
As a new user, I remember being gobsmacked when I looked at the PDF version of the docs, I thought the quality was outstanding.

But then I struggled to get PREMPT-RT working for my Mesa card (fortunately thats simpler today). That was more of a Linux problem.

As a new integrator, I remember thinking the homing sequence docs were simply outstanding!

As a C programmer, I was blown away about how easy it was to extend the system with halcompile

The biggest problem I have today is finding an online option of the man pages for HAL components. Generally, I just use Google but because some features have changed between 2.7 and 2.8, if I'm sharing a link, I want to make sure I have the right version.

We have links for:
Core HAL Components
HAL Component List
HAL Component Descriptions

but none of them take you to the man pages Why not? My biggest beef!

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

More
29 Jun 2018 12:32 #113088 by andypugh

rodw wrote: We have links for:
Core HAL Components
HAL Component List
HAL Component Descriptions

but none of them take you to the man pages


Yes they do...

linuxcnc.org/docs/2.7/html/

Scroll to the bottom, there is a "Man Pages" section
Under there is "Commands and userspace components" and in there is a link to the man page for every component.
Some sections might need to be expanded to see them all.

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

More
29 Jun 2018 12:54 #113091 by rodw
Replied by rodw on topic LinuxCNC is Poorly Documented
Still very confusing. Every time I find them, I forget where the next time. Shouldn't they be linked from this page?
linuxcnc.org/docs/2.7/html/hal/components.html
that would be much more logical.

Then the "HAL Component Descriptions" section has a very small subset of the available components so is way out of step with the page heading.

Its kinda like this area of the docs has grown higglety pigglety over the years and really needs to be revised.

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

More
29 Jun 2018 13:13 #113092 by andypugh

rodw wrote: Its kinda like this area of the docs has grown higglety pigglety over the years and really needs to be revised.


You are right there, I think.

When creating a new HAL component using "comp" / halcompile a new man-page is automatically crated by the build system. But it takes manual intervention to add the component to the other documentation pages.

I am at least partly responsible for this mess as 12 of the current Hal components were written by me and none have been added to the general docs. I think partly because those docs are not where I would go to find the info I need.

It would be really useful for someone to add all the current HAL components to a doc along with their one-line summary and a link to the man-page.

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

More
29 Jun 2018 16:24 #113102 by InMyDarkestHour
Whilst there are some issues, pointed out by some members, and the docs aren't as "example heavy" as one would find with the Windows DDK & API docs, I think "poorly documented" is unfair on one hand and combative on the other.

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

More
29 Jun 2018 18:05 - 29 Jun 2018 18:29 #113104 by BrendaEM
Ozzrob, you have been combative to me personally.That is why I reported you. You are entitled to your opinion, but I have no qualms about informing the people in the treads that I post on, that it appears that you have lost your objectivity.

Anyway...

I have stated in the first post, because the .hal in LinuxCNC has all the power of a programming language, there is a greater demand on the quality of its documentation.

Yes, there is information, but the context of the information is important. It would be cool if the two sources of docs were gone through.

Personally, I feel bad, because I had made a technical mistake in a youtube video I posted, even though I tried to keep the bar low for the information I tried to disseminate. I am still too green (which is funny because I have olive skin) to write much, at this point. Still, I tried.
Last edit: 29 Jun 2018 18:29 by BrendaEM.

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

More
29 Jun 2018 18:27 #113105 by andypugh

BrendaEM wrote: Ozzrob, you have been combative.That is why I reported you.


The phrase "Two countries separated by a common language" springs to mind.

I know a lot of Americans and Australians, and the same word can have rather different nuances in each vocabulary.

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

Time to create page: 0.112 seconds
Powered by Kunena Forum