lkml.org 
[lkml]   [1999]   [Aug]   [7]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    From
    SubjectRe: info format (was Re: Linux 2.2.11pre4)
    Date
    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/

    \
     
     \ /
      Last update: 2005-03-22 13:53    [W:0.022 / U:1.000 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site