Re: info format (was Re: Linux 2.2.11pre4)

Alan Curry (pacman-kernel@cqc.com)
Fri, 6 Aug 1999 16:03:08 -0500 (EST)

Robert G. Brown writes the following:
>
>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.

What we need is a group of people - not many, just 10 or so - who are willing
to write the man pages for things that obviously _should_ have man pages but
don't. Like libc6. Let's ask the Linux man-pages maintainer... [added to Cc:
line]... Andries, what's your feeling on the direction of section 3 man
pages? They currently mostly document libc5, but they are being distributed
with systems that use libc6. IMNSHO, distributors who are shipping libc6
should be shipping man pages that document libc6. Is there any major effort
underway to make a set of man pages that would actually be accurate and
complete on a modern Linux system? All the stuff that's in libc.info should
be made available in /usr/man/man3 dammit. I know that if this is done, man3
will be inherently always a little bit behind, but right now it is WAY behind
and it's starting to smell bad.

Aside from libc.info, there are also the other info pages - like GNU make,
which started this thread, and groff, which is shockingly underdocumented
("This man page only describes the differences between UNIX roff and GNU
roff"), and then there's the RedHat Syndrome, in which things like GNOME and
utempter appear with no documentation at all...

Those of us who want man pages to survive need to organize and start writing
them. If such organization has already happened, someone point me to their
TODO list so I can get started. If not, let's get going, before it's too late.

-
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/