Messages in this thread | | | Date | Fri, 6 Aug 1999 12:08:20 -0400 (EDT) | From | "Robert G. Brown" <> | Subject | Re: info format (was Re: Linux 2.2.11pre4) |
| |
On Thu, 5 Aug 1999, Tim Ricketts wrote:
> On Tue, 3 Aug 1999, Michal Jaegermann wrote: > > > torvalds> and if you actually want to be user-friendly you either > > torvalds> use "man" (because that's how everything else is documented and > > torvalds> then you could actually just tell people to use man everywhere) > > > > This is somewhat ridiculous for documents with sizes of a few hundreds > > pages (and your disk is likely full of such documents). This was tried > > with Perl4, for example, and results were not very friendly. > > But perl 5 has a perfectly good set of man pages.
To take the discussion one step further, one of my own personal pet peeves is out of date/incorrect/inconsistent/missing man pages. Lots of people (myself included) habitually rely on man pages as THE RTFM mechanism. It is infinitely annoying to read, e.g., the crypt() man page and to see no reference to the fact that crypt, via libc6/glibc and even some versions of libc5, now supports MD5 transparently or any instructions on how to make that happen. Sure, it is in info libc, three layers deep, as a crypt crossreference. info crypt, on the other hand, returns the (obviously now obsolete) man page. Even the info pages are therefore rife with obsolescence, errors and are incorrectly cross-referenced.
Having more than one documentation mechanism virtually ensures that one or the others (or all of them in random spots) will be out of date and inconsistent in LOTS of places, not just one or two, and that vital cross-references will be broken or missing. For example, I've noticed that more and more man pages that occur as cross-references on a man page are now missing. Entropy is creeping into "the manual" (whatever that might be now that there is documentation all over the place), and all that can come of this is chaos.
There are, as has been noted, many mechanisms for building documents or documentation mechanisms that can be moved from form to form -- texinfo, pod, sgml among them. Regardless of which one is used, the information recorded should be consistent and correct (within reason) across all means of accessing the documentation. I'd like to endorse the idea that the man pages should be preserved as "the" cross-referenced resource for Unix commands, file formats, and above all as "the" programmer's reference manual, regardless of how. I cannot begin to communicate how annoying it is to a programmer to use a subroutine call or systems call precisely as documented in the man pages only to find that the documentation is wrong and out of date and that one has to search several databases of other documentation to find the CORRECT description.
To summarize; it is a whole lot less important to me that a documentation mechanism be user-friendly or hypertext linked or fancy than it is that the documents therein be correct and that there be one correct and consistent way to access any piece of "manual" type information available on the system. The manual mechanism should also be at least moderately hashed and searchable, although the "apropos" mechanism in the man pages has proven to be entirely adequate for me over many years. The perl documentation is actually exemplary -- it shows how even a powerful and complex tool can be documented in a remarkably small set of man pages, not well enough to learn it perhaps but rather as a rigorous and exhaustive programmer's reference.
rgb
Robert G. Brown http://www.phy.duke.edu/~rgb/ Duke University Dept. of Physics, Box 90305 Durham, N.C. 27708-0305 Phone: 1-919-660-2567 Fax: 919-660-2525 email:rgb@phy.duke.edu
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/
| |