Re: Various ... problems: A diatribe on man pages

[turnbull@example.com (Stephen J. Turnbull)]

Isn't anybody out there reading the man pages?  (Jim Schweiz of course
is caught in catch-22 since he couldn't read the man pages without
being able to even do "man man" to find out why "man man" wasn't
working ;-) I suppose it could be that a lot of people don't know
*how* to read the man pages.  Here are some hints (not exhaustive, but
I've found them useful).

0.  Use "man" (or "xman" if you have X).  In a pinch you can even use
    "zless" on the preformatted pages in /usr/man/preformat/cat*/.  I
    use both 'man' and 'xman'.  'xman' is convenient for simultaneous
    multiple pages (I have both kterm(x) and xterm(x) displayed right
    now because kterm.1x is not a full man page, but refers to
    xterm.1x).  'man' on the other hand pipes its output to a full-
    featured pager such as less, and the search features are very
    useful (especially in mega-pages like those of bash and perl).
    Recent versions of less even know how to deal with underlining and
    other confusing aspects of searching formatted man pages.

1.  Not all man pages are well-written.  If you've looked at the man
    page and still don't understand, I'm not going to be surprised.
    Go ahead and ask on the list or newsgroups.  But most problems can
    be solved pretty quickly by looking at the man pages.  Try the man
    or Info page first.

2.  Unix programs, despite the "Unix philosophy", tend to become full-
    (or over-) featured over time.  One feature that is necessary is
    user configuration, because of the wide variety of Unices (let
    alone the wide variety of users' environments and the fact that
    some programs are installed by people without root access).  A
    good man page for a program documents the user configuration
    features fully but tersely.  The structure of most man pages
    reflects this.  Each type of configuration feature usually
    receives its own section.

    Files are documented in the "Files" section.  There is a list of
    files that the program uses, including its configuration files.
    Often the paths are wrong because the program has been updated to
    fit the Linux File System Standard but the man page has not, or
    something like that.  However, the file names will be correct
    (there's no reason to change them) and you can find them using
    'find'.  A program with a complicated configuration file will
    often have documentation for that configuration file in  a
    separate man page in section 5.  In that case you may need to type
    "man 5 <program>" to see the man page for the file, but usually
    the file's name is <program>rc or <program>.conf, so there is no
    shadowing of its man page.  (Do a "man man" to see why shadowing
    might occur.)

    Environment variables are documented in the "Environment
    Variables" section.  Environment variables are used for
    user-by-user customization.  Individual users often use them for
    automatic customization according to terminal type.  Most
    environment variables have corresponding options.  A particularly
    important type of variable is the "PATH" variable (Emacs, for
    example, uses at least 4!)  If your program is not finding
    filesystem resources that you know are there, there is probably a
    problem with your path setting.  For bash users, paths tend to
    get set in /etc/profile, ~/.profile, and ~/.bashrc.

    Note that even a small typo can screw things up; if possible use
    the output of "set | fgrep 'PATH'" to describe your paths in
    questions to the mailing list.

    Command line options are in the "Options" section.  If you're
    using the same command line options on a regular basis, you should
    probably be setting an environment variable (or defining an alias).

3.  X Windows programs are even more heavily customizable than most
    programs.  An X program will not only have config files,
    environment variables, and options, it will also have "resources"
    and "toolkit options".  Resources are program variables that you
    can configure on the fly.  They can be set in the code, in an
    application default file, by the server, or from the command line.
    See X(1) for details.  The gist is that if you want to know what
    the program is doing by default, you need to look in the following
    places:
    a.  The man page (or maybe the source code) for hard-coded
        defaults.
    b.  The system application default file, which should be found in
        $XROOT/lib/X11/app-defaults.  'ls' that directory to get an
        idea of the naming conventions.  $XROOT is the root of the X
        Windows hierarchy, usually /usr/X11R6 on modern XFree86 systems.
    c.  A local application default file (rarely used nowadays).
    d.  The server's resource database.  Use "xrdb -query" to find out
        what the server thinks you are doing.  The resource database
        is loaded from several places; see $XROOT/bin/startx and
        ~/.xinitrc for details.  Or "find ~ $XROOT -name '.Xresources'".

    There is another set of resources that is not documented in your
    program's man page.  These are the toolkit resources.  For
    example, essentially all X Windows programs allow you to configure
    window geometry.  These resources are part of the Xt (X Toolkit)
    library, or possibly higher-level widget libraries such as Xaw or
    Motif.  For these options, see man pages or other documentation
    for the toolkit.  Xt resources are documented in X(1) in the
    "Options" section.

    Figuring out which widget and which resource controls the behavior
    you're interested in is something of an art.  But you can learn it
    pretty quickly.

4.  GNU programs often have out of date man pages as the GNU project
    has standardized on TexInfo as its documentation format.
    Unfortunately, at least in my old Slackware distribution combined
    with a recently rebuilt Mule the Info files are spread across
    several different locations.  You may need to twiddle PATHs for
    Emacs and the standalone Info reader to get them to read all your
    info files.

    Annoyingly enough, bash's man page is much more useful than the
    Info file in my experience.  However, Info gives excellent
    documentation for GCC and Emacs/Mule, and many other programs.

Obviously, I'm not really all that upset about people asking questions
that are well-documented in the man pages.  (Actually, people have
been pretty good about that, and surprisingly enough I don't think
I've seen the acronym RTFM on tlug.)  Really now---if I didn't want to
answer the questions, I would just ignore them.  But I think that it
would make life easier for everybody if they learn to use the man pages.

-- 
                           Stephen John Turnbull
University of Tsukuba                                        Yaseppochi-Gumi
Institute of Socio-Economic Planning       http://turnbull.sk.tsukuba.ac.jp/
Tennodai 1-1-1, Tsukuba, 305 JAPAN                 turnbull@example.com