LinuxCNC is Poorly Documented

06 Jul 2018 20:45 #113605 by tommylight
All Linuxcnc installs ( except the complicated compile one, and even that does create debs with docs in 3 languages, just in case ) come with exceptionally detailed documentation and in several languages.
I for one went through them more than once, and still use them as the starting point for everything Linuxcnc related.
Menu>Linuxcnc>documentation---738 pages of heart warming informations served mildly warm and with a side of fries.
Menu>Linuxcnc>Getting started guide---35 pages of scorching hot informations served with just the right ammount of ice cream.
Menu>Linuxcnc>G-code quick reference---- a single page of cold info served as is, oven mitts not included.

Also just in case someone missed this:
google , in the search bar type exactly this:
"created by tommylight"
that will return only results of posts created by me on the linuxcnc forum

oh well............
The following user(s) said Thank You: BigJohnT, InMyDarkestHour, BrendaEM, snoozer77

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

06 Jul 2018 21:53 - 06 Jul 2018 22:07 #113608 by InMyDarkestHour
Am I wrong in not having had a issue with the html documentation ?

Hell I even keep a copy on the weberver at home.

One thing I think that will need protection is the GNU help......I'd hate to see what would happen, well you know.

One does wonder what would happen if a manpage was seen by our friendly topic author.

Yes I am at a complete loss as to why & how someone would get so lost. I think I'll have some Special K and watch some Saturday Morning cartoons.

I'm actually starting to wonder about motives. There are very few threads that the author seems to participate in that aren't their own, even when invited to join in with a discussion\thread, one which would have addressed an issue raised by the author previously, there has so far been no participation. I find this a bit worrying, not just the lack of invited participation but elsewhere, even just to ask a question.
The idea of community participation is joining in other discussions, threads & other areas and sharing ideas in those, not just your own threads. Step outside and join the rest of us, ideas will be discussed, rejected, reassessed.
Last edit: 06 Jul 2018 22:07 by InMyDarkestHour.

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

07 Jul 2018 00:47 - 07 Jul 2018 00:47 #113620 by curtisa

cmorley wrote: Now that is tangible criticism. Giving a concrete example is much more helpful.
Pncconf will always be beta and buggy unfortunately. But the docs could be improved.
Can you be a bit more specific? is it the wording? The layout? the tone? The actual information? not enough pics? too many?

Chris M

I think the PncConfig documentation starts off well, but the flow and detail tapers off towards the middle. Section 8 - Parallel Port, for example just gets one line of text explaining what the tab in the Wizard is for. I realise that PncConfig is probably for more advanced users because it supports more advanced hardware than a parallel port. Maybe the expectation is that if you're at this point you don't need some things explained.

But even some more basic, holistic stuff could be tightened up. On the main page of the website, if I want to look at the Documentation I'll click on the heading marked 'Documentation'. I'm then taken to a page where I need to pick which version of documentation I want to look at (V2.0, V2.1, V2.2, V2.3, V2.4, V2.5, V2.6, V2.7 or bleeding edge V2.8), all of which are links alongside yet another link that takes me directly to the HTML version. If I click on the text that just says 'LinuxCNC 2.7' (and I've missed the fact that the text 'HTML' sitting next to it is actually a separate hyperlink to the other), I end up on another page that appears to be some backdoor area of the website offering me another set of links to the HTML and PDF versions (up till this point there's no obvious indication that the PDF versions exist or are obtainable via following the offical paths. But anyhoo...). I can finally click on the 'HTML' link and there's the documentation. If I chose the 'PDF' link instead I still end up in what appears to be a very dark area of the website - I can see the documentation, but I don't exactly feel like I'm in any longer within part of the website that the general public should be looking at.

Wouldn't it be better to just click on the word 'Documentaion' and be taken straight to the most current documentation to begin with? You can still provide links to the older versions (V2.0? Is that of any real use nowadays?), PDF versions or the pre-release versions after making that first click, but surely the actual bone fide documentaion should be just...well, there?
Last edit: 07 Jul 2018 00:47 by curtisa.

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

07 Jul 2018 02:21 - 07 Jul 2018 07:03 #113624 by InMyDarkestHour
Just messing around with the abs hal manpage, I added a simple "Go Back" button, just before the </body> tag, would this help navigation in this instance ?

Obviously it could be made prettier with CSS, but I'm no html guy.

  <input type="button" value="Go back" onclick="history.back()">

Complete code, cut and paste to try, back button wont do much in this example if there is
no previous history in the tab\window.
<!-- Creator     : groff version 1.21 -->
<!-- CreationDate: Wed Aug 16 12:32:08 2017 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
<meta name="generator" content="groff -Thtml, see">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
       p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
       pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
       table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
       h1      { text-align: center }


<h1 align="center">ABS</h1>

<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#FUNCTIONS">FUNCTIONS</a><br>
<a href="#PINS">PINS</a><br>
<a href="#LICENSE">LICENSE</a><br>


<a name="NAME"></a>

<p style="margin-left:11%; margin-top: 1em">abs &minus;
Compute the absolute value and sign of the input signal</p>

<a name="SYNOPSIS"></a>

<table width="100%" border="0" rules="none" frame="void"
       cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="66%">

<p style="margin-top: 1em"><b>loadrt abs
[count=</b><i>N</i><b>|names=</b><i>name1</i><b>[,</b><i>name2...</i><b>]]</b></p> </td>
<td width="23%">

<a name="FUNCTIONS"></a>

<p style="margin-left:11%; margin-top: 1em"><b>abs.</b><i>N</i>
(requires a floating-point thread)</p>

<a name="PINS"></a>

<p style="margin-left:11%; margin-top: 1em"><b>abs.</b><i>N</i><b>.in</b>
float in</p>

<p style="margin-left:22%;">Analog input value</p>

<p style="margin-left:11%;"><b>abs.</b><i>N</i><b>.out</b>
float out</p>

<p style="margin-left:22%;">Analog output value, always

<p style="margin-left:11%;"><b>abs.</b><i>N</i><b>.sign</b>
bit out</p>

<p style="margin-left:22%;">Sign of input, false for
positive, true for negative</p>

<p style="margin-left:11%;"><b>abs.</b><i>N</i><b>.is-positive</b>
bit out</p>

<p style="margin-left:22%;">TRUE if input is positive,
FALSE if input is 0 or negative</p>

<p style="margin-left:11%;"><b>abs.</b><i>N</i><b>.is-negative</b>
bit out</p>

<p style="margin-left:22%;">TRUE if input is negative,
FALSE if input is 0 or positive</p>

<a name="LICENSE"></a>

<p style="margin-left:11%; margin-top: 1em">GPL</p>
  <input type="button" value="Go back" onclick="history.back()">
Last edit: 07 Jul 2018 07:03 by InMyDarkestHour. Reason: Stupid error

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

07 Jul 2018 05:12 - 07 Jul 2018 05:42 #113634 by BrendaEM
"Am I wrong in not having had a issue with the html documentation ?"
You are entitled to your opinion, but I vote that LinuxCNC continues growing and moving forward.

AnnoyingMutt, I have interacted on other threads, but having got my machine going, asked for the things I thought would bring more people to LinuxCNC, and the remainder of my time, I have been working on the interface, which at times, I have worked on for 8 hour stretches.

AnnoyingMutt, you have been openly hostile to me on this web forum, to the point where you needed to make a retraction. I strongly suspect that you will do anything you can to quarrel with me, regardless if the result I seek will benefits LinuxCNC.

Your suggestion that I must be a bad forum member because I appear not to use the web forum as you want, is harassment. I have again reported you.

As I stated, I likely will work on some documentation. Though, I have given my commitment to another project to try to return something to LinuxCNC, and that will remain my main focus.

As I have stated, perhaps I should have named this thread something more diplomatic, but no one asked me to change it. No one. I continue to stand by my opening statement.
Last edit: 07 Jul 2018 05:42 by BrendaEM.
The following user(s) said Thank You: InMyDarkestHour

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

07 Jul 2018 05:23 #113635 by curtisa
That actually sparks another minor thing that I noticed the other day.

If you do a Google search for some documentation, (say 'LinuxCNC GladeVCP') and you click on one of the manual pages offered in the search results, theres no way of ascending back up the manual pages from the outside looking in. The only way back up the documentation tree is to be the top of the tree structure to begin with, and retrace your steps using the browser 'back' button.

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

07 Jul 2018 10:51 #113656 by rodw
Replied by rodw on topic LinuxCNC is Poorly Documented
Here's a concrete example of a problem.

The documentation has been improved for the lowpass component in v 2.8.

But it remains incomplete becasue I can't calculate the gain required from the information given for a 70 Hz lowpass filter which I just happen to need at the moment. I'm not an electrical engineer but surely I should be given enough information to configure the component in the documentation.

If anybody can let me know the correct value, please let me know.

In my view, all of this technical stuff is far more important to get right than the stuff most people are complaining about on this thread. And I forgot again how to link to the man pages for components from the main menu..... Silly me, I always assume hal components would be documented in one of the hal chapters.

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

07 Jul 2018 11:18 #113657 by InMyDarkestHour
If my son wasn't out banging his head I'm pretty sure he'd be able to answer that. The little (well not so little) long haired smarty pants is doing a double degree at NSW Uni in science & mechatronics. Anything more than working out concrete volumes and roadbase tonnages is a little over my head.

Having the correct info is most important......If you can't work out where you are in some simple docs...........

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

07 Jul 2018 11:35 - 07 Jul 2018 12:01 #113658 by BrendaEM
I have counted perhaps two or three people, at most who have added that the documentation might need a little work. Though, could anyone say that this is a safe environment for making comments? This thread serves as a big ugly lesson to anyone who might want LinuxCNC to be improved in any aspect. As I stated, I could have titled this thread a little more diplomatically, though what I received in this thread was mostly hatred.

Anyway, that's a plotpoint, as I've only dealt with 2nd order Butterworth filters. I have never heard of a zero-order filter. I find it amazing that LinuxCNC has such facility.

Unity-gain usually means no-gain or 1:1

I would guess that "-a" is angle where the filtering fall-off/roll-off begins, because it's in radians/sec. It's interesting, like it's drawing the filter roll off, like if you put a pen in spirograph disk, and rolled it a certain speed along the timeline, to create a downward slope.

e is not specified. Could it be epsilon?

This does not seem described at all: count=N
The documentation states that it's single pole, so why does it say count? Could you add more than one instance/pole to the filter your are describing? Or is it for something different?

Could it documented further in the code comments?

This is some serious math, requiring people who live in this particular kind of math. It would be a serious loss to lose the technical aspects of the documentation.


Incidentally, I realize that it's just a working folder, but the reader could not place into context what part of LinuxCNC that document pertains to from:
Last edit: 07 Jul 2018 12:01 by BrendaEM.

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

07 Jul 2018 12:47 - 07 Jul 2018 12:49 #113664 by PCW
Replied by PCW on topic LinuxCNC is Poorly Documented


( 1-e^(-2*pi*70*.001) )

(assuming 1 KHz sampling)
Last edit: 07 Jul 2018 12:49 by PCW.
The following user(s) said Thank You: rodw

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

Time to create page: 0.117 seconds
Powered by Kunena Forum