On 12/7/2012 6:49 AM, John Thornton wrote: > In any case I doubt a newbee can find a man page with both hands... much > less know to look for a man page.
Now THAT'S dismissive :-) 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. 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 remember looking at the man-page generation process long ago when I was trying to help with the transition to asciidoc for 2.5 but I'm too fuzzy-headed this morning to remember if I took good notes :-( Regards, Kent ------------------------------------------------------------------------------ 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
