On 12/7/12 09:00 , Kent A. Reed wrote: > Seriously, though, I have cognitive issues with our man page system. > Even seasoned users might miss that > > man abs - returns a description of the family of Linux functions which > compute the absolute value of an integer > man 9 abs - returns a description of the HAL abs component > > or > > man axis - returns a description of the LinuxCNC Axis GUI > man 9 axis - returns a description of the HAL motion component > > just to cite two examples I recently ran across. > > As well, do even seasoned users understand the annotation at the top of > the LinuxCNC man pages, such as ...(3rtapi) and ...(3hal)? These suggest > specific man-page directories but actually denote pages from LinuxCNC > projects that are placed in the general man3 directory. Yet this > convention wasn't applied to many (most?) of our man pages...AXIS(1), > for example.
The number in parentheses after the command name is the manpage section, see 'man man'. The words after the section number are ignored by the tools but suggest grouping to humans. The Axis gui is described by the axis(1) man page, since it's a user-accessible executable program. The axis(9) manpage describes the HAL interface of the motion controller, I guess it's arguable whether it belongs in section 9 (which is for kernel modules). I've lived with man pages for decades, and our man pages seem well organized to me. > Several times, I have thought we need a better documentation roadmap for > users, one that is accessible from the keyboard as well as the > HTML/PDF/Wiki pages, but I freely confess I haven't tried to make one. I think the current system of manpages on the CNC machine itself, plus webpages and PDFs anywhere, is pretty excellent. I'm happy with the state of our docs. (The translations are in shambles, except for the French thanks to Francis Tisserant, but that's a separate issue.) -- Sebastian Kuzminsky ------------------------------------------------------------------------------ LogMeIn Rescue: Anywhere, Anytime Remote support for IT. Free Trial Remotely access PCs and mobile devices and provide instant support Improve your efficiency, and focus on delivering more value-add services Discover what IT Professionals Know. Rescue delivers http://p.sf.net/sfu/logmein_12329d2d _______________________________________________ Emc-developers mailing list Emc-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/emc-developers
