Gentle persons: This message covers editorial issues I found reviewing the HTML files on http://www.linuxcnc.org/docs/2.5/ concerning the (English) Integrator manual. I am picking up where I left off yesterday in Part A.
I read the parts on the morning (East Coast US morning, that is) of 2012/01/17. As an overall comment, some parts include the vendor's URL, some don't. It seems to be me the documentation ought to do so in every case. --- Parallel Port Driver (hal/parallel_port.html) In section 1. Parport is the hyperlinked sentence "Figure [fig:Parport-block-diag] shows two block diagrams...." Clicking on the hyperlink moves me down the page to section 1.2. Pins; the figure is outside the view. This is a good example of the problem I noted yesterday of link-targets not being placed correctly in the source. In section 1.1.1. Using the Port Index there is a synthetic sentence composed of a boxed hal command followed by "Will use the address Linux has detected for parport 0." The word "Will" should not be capitalized (my NIST editors would have forced me to rework the whole sentence, but I don't think that's necessary). In section 1.2. Pins several sentences have a spurious space before the closing full-stop (that's known as a period to us Yanks). In section 1.6. Using DoubleStep: I thought there used to be an explanation of the benefit of DoubleStep somewhere in the EMC2 documentation but I can't find it at the moment. Either directly in this section or by reference to another, we ought to give the user a little help. --- AX5214H Driver (drivers/AX5214H.html) No comments. --- GS2 Driver (drivers/GS2.html) A mea culpa...proofreading this section reminds me that I was off-base in a comment I made about section 1.3 in the Basic HAL part (V2.5 documentation - issues with HAL "Manual", 20120114). Of course the "-n" flag works in "loadusr" commands if the component being loaded recognizes it. I was working too late without caffeine. Sorry. This section lacks the colorized, italicized font formatting adopted in others to denote options, pins, etc. --- Mesa HostMot2 Driver (drivers/hostmot2.html) There is a difference in user skill implied by sections 3. and 8. In section 3., we give the user instruction on using Synaptic Package Manager. In section 8. we assume the user knows what a .deb file is and how it got there. I'd suggest simply dropping the word " .deb" from section 8. PIN Files. --- Motenc Driver (drivers/motenc.html) In section 2. Parameters why does the final sentence end with a question mark? --- Opto22 Driver (drivers/opto22.html) No comments. --- Pico PPMC Driver (drivers/pico_ppmc.html) It's a minor nit, I know, but it seems to me the different Pico-board designators PPMC, USC. and UPC should be mentioned in the introductory paragraph since those acronyms show up repeatedly in the technical description. At the same time, the title of this part now seems too restrictive since the part covers all three board types and not just the PPMC. --- Pluto P Driver (drivers/pluto_p.html) In section 1. General Info I would drop the parenthetical "($60)" for any number of reasons. It may or may not seem inexpensive, it is subject to change, it is presumably but not explicitly in USD, and we don't list prices of other vendor's boards. Section 1.5. Power speaks of "VCC" and "VCC pins" but there's no indication in section 1.3. Physical Pins of "VCC". Where are this VCC pins? In section 1.8. For more information the additional information is no longer on fpga4fun.com but at http://www.knjn.com/FPGA-Parallel.html. Also, the hyperlink "from the developer's blog" take's me to Jeff's blog where he talks about reverse engineering the board. I think the hyperlink would be better labelled "from a user's blog" unless of course Jeff is the pluto-p developer. In section 2.4. Compatible driver hardware is a broken link to L298H-bridge document that I noted previously. In section 3. Pluto Step in the first sentence "Pluto-step" should be "The pluto_step system" to be consistent both with the driver name and the previous description which begins "The Pluto_servo system...." NOTE: I peeked at the man pages and found that pluto_servo.9 and pluto_step.9 include "SEE ALSO" sections that read "The pluto_step (or _servo) section in the HAL User Manual...." Obviously the man pages should reference this consolidated Pluto P Driver material contained in whatever we end up calling the major divisions (if any) of the EMC2 documentation. --- Servo To Go Driver (drivers/servo_to_go.html) It's implied that the vendor name is "Servo to Go" . I think it ought to be explicit. This part is an example of my comment above that URLs would be a good idea. --- Kinematics (motion/kinematics.html) I'm thrilled to see how far this part has come in terms of its formatting...THANKS, John. Still, long-time colleagues know there's always room for a Kent-nit or two. In section 4. Implementation details there are several boxed C-code fragments that begin with a spurious space, e.g., " int" instead of "int". Also in section 4., there's several lines that say "Implements the xxx function as described in [the] HAL manual." What, exactly, is being communicated here and where in the HAL manual should one be looking? --- Stepper Tuning (motion/tweaking_steppers.html) There's some overlap between this part and "Stepper Quickstart" in Getting Started. Given that most of our front-end documentation appears aimed at a neophyte EMC2 user, I think we should be clearer about the EMC2 latency-test script versus the RTAI latency test. --- PID Tuning (motion/pid_theory.html) Classicladder Introduction (ladder/ladder_introduction.html) No comments. --- Classicladder Programming (ladder/classic_ladder.html) As an overall comment, I was going to save the topic of unidentified first persons for a separate message, but because of the work-in-progress style of this part, at least in the MODBUS section, it is particularly disconcerting to run across statements like "I have not tested this...." Who is the man behind the curtain, so to speak? Is this person still working the problem? Indeed, is it still a problem or is this just a historical note? Do others need to be contributing to solving the problem? What should we be telling the user? In section 2. Ladder Concepts the final paragraph says "Classic Ladder version 7.124 has been adapted for EMC 2.3. This document describes that version." Since we are now dealing with V2.5 documentation, perhaps this paragraph should say something like "Classic Ladder version 7.124, first adapted for EMC 2.3, is used in EMC 2.5. This document describes that version." As an aside, I think this adaptation was a brilliant stroke in EMC2 development. It's not the only one, but I thought I should say it while I'm thinking about it. In section 7.2. IEC Timers the first phrase should end in a full stop (.) not an exclamation point (!). In section 7.7. Variable Assignment there's something funky about Figure 8. The first image is centered over the caption, the second and third images fall under the caption and are left-justified. There's a stray left square bracket at the lower left of the second image. In section 9. GRAFCET Programming the last sentence ends with the parenthetical "(only to the beginning step?)" Besides needing a full stop after the right paren, does the question mark still apply? Don't we know by now? In section 10. Modbus I would have expected the paragraph beginning "To get MODBUS to initialize..." to break out the halcmd entry into our stylized box, e.g., "loadusr -w classicladder ...." In section 10.2 MODBUS Info I noted previously the broken link "http://www.modicon.com/techpubs/toc7.html";. Today I am also unable to reach "http://www.ipac.ws";. --- Classicladder Examples (ladder/ladder_examples.html) In keeping with the work-in-progress feel of the Classicladder Programming part, sections 5 and 6 of this part represent promissory notes. Are the Tool Turret and Sequential examples going to be completed? --- PCI Parallel Port (examples/pci_parallel_port.html) Spindle Control (examples/spindle.html) MPG Example (examples/mpg.html) GS2 Example (examples/gs2_example.html) No comments. --- Here endeth my comments on the HTML rendition of the V2.5 Integrator Manual. Regards, Kent ------------------------------------------------------------------------------ Keep Your Developer Skills Current with LearnDevNow! The most comprehensive online learning library for Microsoft developers is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3, Metro Style Apps, more. Free future releases when you subscribe now! http://p.sf.net/sfu/learndevnow-d2d _______________________________________________ Emc-developers mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/emc-developers
