lkml.org 
[lkml]   [1999]   [Aug]   [7]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: 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/

\
 
 \ /
  Last update: 2005-03-22 13:53    [W:0.307 / U:0.672 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site