Gentle persons:
This message covers editorial issues I found reviewing the HTML files on
http://www.linuxcnc.org/docs/2.5/ concerning the (English) HAL manual.
In this email I shall call them parts. I have titled my comments on each
part according to the link title in index.html and given the linked-to
HTML file name in parentheses.
an overview issue - what is the difference between a "HAL component"
which is defined in the docs and a "HAL module" which is not? The former
term is used more frequently but the latter shows up in many places.
Interestingly, in the part Creating HAL Components with comp
(hal/comp.html), section 2. Definitions declares that a component is a
single, real-time module. Thanks for clearing that up!
---
HAL Introduction (hal/intro.html)
The HAL manual uses "NML" without definition, starting with section 3.1
External Programs with HAL hooks which says of motion "A realtime module
that accepts NML motion commands...."
I think NML ought to be defined in section 2. HAL Concepts (and in the
EMC2 Glossary as well).
---
Basic HAL Info (hal/basic_hal.html)
In later parts of the manual, HAL commands are written in typewriter
font. In this part, they are written in the running-text font, set off
in double quotes, e.g., "loadusr".
In section 1.3. loadusr, the example shows a flag ("-n name") that is
not listed in the preceding command description. I'm away from a working
EMC2. Does this flag work? If so, then other documentation has to be
fixed to match (man page, help loadusr...) and it seems redundant in
function to the -Wn flag.
In section 1.4. net, I would modify the fourth sentence to say "The
optional direction indicators...." to clarify what is meant by "and are
not used by the net command."
In the same section, the second example under Figure 2 seems
inappropriate. Should it not read "net xStep => parport.0.pin-02-out" in
order to illustrate the preceding text?
At the end of the same section is a line that drives me nuts. "The so
called I/O pins like index-enable do not follow this rule." Firstly,
"this rule" refers to much earlier in the section. Secondly, there
aren't many places in all the EMC2 documentation that mention the I/O
pins and the I/O-pin connection rules remain mysterious.
In section 1.7 Obsolete Commands, I believe it would be helpful to
newbies to explain that these commands are deprecated at the moment (so
existing config files continue to work) but should be avoided in new
work because they may be removed in some future version.
In sections 5.1. through 5.4, I believe the syntax examples are made
confusing by using the word "or" instead of the operator "|" (which is
what is used in the corresponding man pages).
In section 6.1. weighted_sum, I think a new third sentence should be
inserted that defines "weight", perhaps merely stating the default
weight of the m-th bit is 2^m.
---
HAL Advanced Tutorial (hal/tutorial.html)
[editor's aside: I really like this tutorial and can appreciate how much
effort it required to compose and illustrate. Nicely done y'all!]
In section 2.1. Loading a realtime component, the user shell prompt is
missing, sort of. I would expect the first two commands to be something
like "~$ cd emc2" and "~/emc2$ halrun" assuming the user is in his/her
home directory and the shell prompt has not been redefined.
In section 2.2 Examining the HAL, only 8 pins are shown for siggen but
the man page says siggen has 9. Missing here and in following sections
is the pin "siggen.0.clock".
In section 3.1. Starting halmeter, the third sentence "Since halmeter is
a GUI app, X must be running" is a bit abrupt for a HAL tutorial.
Perhaps a better approach is to say what you get if X (meaning an X11
server) isn't running. Since the same situation arises with halscope,
perhaps the statement about X11 should precede them both.
In section 5.1. Starting Halscope, I seem to recall that the first
invocation of "loadusr halscope" in a fresh working directory throws a
warning that the file "autosave.halscope" could not be opened (which is
correct, of course, since it doesn't exist until halscope has written it
for the first time). It might be worthwhile warning the newbie that this
is a benign message.
In section 5.4 Vertical Adjustments, the parenthetical "see the
halscope reference in section [sec:Halscope] for details)" is
frustrating since the referenced section doesn't say anything useful.
---
Canonical Devices (hal/canonical-devices.html)
The link to this section cries out to be retitled "Canonical Device
Interfaces" since that is what it is about and that is what the part
itself is titlted.
In section 4.2. Parameters, is the definition of the "scale" parameter
complete and correct? It seems truncated. Does this mean, by the way,
that "offset" is in volts?
---
General Reference (hal/general_ref.html)
In section 1.2. Names, what is meant by "...preceded by their type in
(small caps)..."? The examples don't use "small caps". (aside:
"preceeded' is misspelled.)
It is rather disconcerting that the subsubsection headings (like 3.1.1.
Examples) have an underscore that spans the width of the page. This is a
visual "stop" that seems inappropriate for such subsumed content.
Footnote 2 seems quite stale. This is now version 2.5. Are the
conventions followed now or not. How about a note similar to the one in
the Canonical Devices part (which says "By version 2.1, the HAL drivers
should have all been updated to match these specs. Send an email if you
spot any problems.")
Is footnote 3 still necessary? Was the bug fixed in Version 2.1 as it
promises it will be?
---
HAL Tools (hal/tools.html)
As mentioned previously, section 3. Halscope doesn't say anything useful
(yet).
---
HAL Components (hal/components.html)
It's getting late and I didn't check that all the command, component,
and call entries are correct. I know it's wrong but I'm weak.
---
Realtime Components (hal/rtcomps.html)
In section 1. Stepgen, figures 1 and 2 are missing (the page says it was
last updated 2011-12-28 10:36:09 CDT). The description of the figures in
the preceding text and the figure captions don't seem to be consistent.
The text talks of *three* diagrams---two showing position mode control
and the third velocity mode. The *two* figure captions say "(position
mode)" and "(velocity mode)" respectively. IIRC, the (missing) figures
themselves each contain three diagrams.
In section 1.4. Parameters, I'd suggest modifying the last sentence of
the first full paragraph to read "For more details, including the
contents of the control equation box, consult the stepgen source-code"
to make clear what code is to be consulted.
In section 2.2. Removing, what does "*halcmd" mean? Isn't the asterisk a
typo?
In section 3.4. Parameters, there is no explanation of the four
parameters. Further, isn't there a change in style here, with regard to
trailing parentheticals like "(s32, RW)" ?
---
Hal Examples (hal/hal0examples.html)
No problem that I see and again, nicely done.
---
Creating HAL components with Comp (hal/comp.html)
Creating Userspace Python Components (hal/halmodule.html)
These parts look good in a quick once-over but I didn't check the details.
---
And that's all I have for the HAL manual parts. Nothing profound. Just
the usual Kent-nits.
Regards,
Kent
------------------------------------------------------------------------------
RSA(R) Conference 2012
Mar 27 - Feb 2
Save $400 by Jan. 27
Register now!
http://p.sf.net/sfu/rsa-sfdev2dev2
_______________________________________________
Emc-developers mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/emc-developers
