BURKS 2/BURKS_AUG97.ISO/BURKS/LINUX/HOWTO/mini/manpage.txt

Text File | 1997-07-07 | 32KB | 805 lines

                       THE LINUX MAN-PAGE-HOWTO

      Copyright 1995,96,97 by Jens Schweikhardt <[e-mail]>
            See further information on copying conditions below.

                         Last update: March 1997
                   Corrections and suggestions welcome!

   This HOWTO explains what you should bear in mind when you are going
   to write on-line documentation -- a so called man page -- that you
   want to make accessible via the man(1) command.

   Throughout this HOWTO, a manual entry is simply referred to as a
   man page, regardless of actual length and without sexist intention.

   Table of contents:
   ------------------

   0)  A few thoughts on documentation
   1)  How are man pages accessed?
   2)  How should a formatted man page look like?
   3)  How do I document several programs/functions in a single man page?
   4)  Which macro package should I use?
   5)  What preprocessors may I use?
   6)  Should I distribute source and/or already formatted documentation?
   7)  What are the font conventions?
   8)  How do I polish my man page?
   9)  How do I get a plain text man page without all that ^H^_ stuff?
  10)  How do I get a high quality PostScript man page?
  11)  How do I get apropos and whatis to work?

   A)  Copying conditions



 0)   A few thoughts on documentation
 ====================================

 Why do we write documentation? Silly question. Because we want others to
 be able to use our program, library function or whatever we have written
 and made available. But writing documentation is not all there is to it:

 + documentation must be accessible.
   If it's hidden in some non-standard place where the documentation
   related tools won't find it -- how can it serve its purpose?

 + documentation must be reliable and accurate.
   There's nothing more annoying than having program behaviour and
   documentation disagree. Users will curse you, send you hate mail and
   throw your work into the bit bucket, with the firm intent to never
   install anything written by that jerk again.

 The historical and well known way documentation is accessed on UNIX
 is via the man(1) command. This HOWTO describes what you have to do to
 write a man page that will be correctly processed by the documentation
 related tools. The most important of these tools are man(1), xman(1x),
 apropos(1), makewhatis(8) and catman(8).

 Reliability and accuracy of the information are, of course, up to you.
 But even in this respect you will find some ideas below that help you
 avoid some common glitches.

 1)   How are man pages accessed?
 ================================

 You need to know the precise mechanism how man pages are accessed
 in order to give your man page the right name and install it in the
 right place.  Any man page belongs to a specific section, which is
 denoted by a single character. The most common sections under Linux
 and their human readable names are

 Section   The human readable name

    1      User commands that may be started by everyone.
    2      System calls, that is, functions provided by the kernel.
    3      Subroutines, that is, library functions.
    4      Devices, that is, special files in the /dev directory.
    5      File format descriptions, e.g. /etc/passwd.
    6      Games, self-explanatory.
    7      Miscellaneous, e.g. macro packages, conventions.
    8      System administration tools that only root can execute.
    9      Another (Linux specific) place for kernel routine documentation.
    n      New documentation, that may be moved to a more appropriate section.
    o      Old documentation, that may be kept for a grace period.
    l      Local documentation referring to this particular system.

 The name of the source file for a man page (the input to the formatting
 system) is the name of the command, function or file name, followed by
 a dot, followed by the section. If you write the documentation on the
 format of the `passwd' file you have to name the source file `passwd.5'.
 Here we also have an example of a file name that is the same as a
 command name. There might be even a library subroutine named passwd.
 Sectioning is the usual way to resolve these ambiguities: The command
 description is found in the file `passwd.1' and the hypothetical
 library subroutine in `passwd.3'.

   Sometimes additional characters are appended and the file name looks
   for example like `xterm.1x' or `wish.1tk'. The intent is to indicate
   that this is documentation for an X Window program or a Tk application,
   respectively. Some manual browsers can make use of this additional
   information. For example xman will use `xterm(x)' and `wish(tk)' in
   the list of available documentation.

   Please don't use the n, o and l sections; according to the File System
   Standard these sections are deprecated. Stick to the numeric sections.

 Beware of name clashes with existing programs, functions or file names.
 It is certainly a bad idea to write yet another editor and call it
 ed, sed (for smart ed) or red (for Rocky's ed). By making sure your
 program's name is unique you avoid that someone executes your program
 and reads someone else's man page or vice versa. Checking out the lsm
 database on a program name is a place to start doing so.

 Now we know the name to give our file. The next decision is which
 directory it will finally get installed (say, when the user runs
 `make install' for your package.)  On Linux, all man pages are
 below directories mentioned in the environment variable MANPATH. The
 doc related tools use it quite similar like the shell uses PATH to
 locate executables. In fact, MANPATH has the same format as PATH.
 Both hold a colon separated list of directories (with the exception
 that MANPATH does not allow empty fields and relative pathnames but
 has absolute names only.) If MANPATH is not set or not exported, a
 default will be used that contains at least the /usr/man directory.
 To speed up the search and to keep directories small, the directories
 specified by MANPATH (the so called base directories) contain a bunch
 of subdirectories named `man<s>' where <s> stands for the one character
 section introduced in the table above. Not all of the sections may
 be represented by a subdirectory because there simply is no reason to
 keep an empty `mano' subdirectory. However, there may be directories
 named `cat<s>', `dvi<s>' and `ps<s>' which hold documentation that is
 ready to display or print. More on this later.  The only other file
 in any base directory should be a file named `whatis'. The purpose
 and creation of this file will also be described under paragraph 11).
 The safest way to have a man page for section <s> installed in
 the right place is to put it in the directory /usr/man/man<s>. A good
 Makefile, however, will allow the user to chose a base directory, by
 means of a make variable, MANDIR, say. Most of the GNU packages can be
 configured with the --prefix=/what/ever option. The manuals will then
 be installed under the base directory /what/ever/man. I suggest you
 also provide a way to do something similar.

   With the advent of the Linux File System Standard (FS-Stnd), things
   became more complicated. The FS-Stnd 1.2 states that "Provisions must
   be made in the structure of /usr/man to support manual pages which
   are written in different (or multiple) languages." This is achieved
   by introducing another directory level that distinguishes between
   different languages. Quoting again from FS-Stnd 1.2:

   "This naming of language subdirectories of /usr/man is based on
   Appendix E of the POSIX 1003.1 standard which describes the locale
   identification string -- the most well accepted method to describe
   a cultural environment. The <locale> string is:

       <language>[_<territory>][.<character-set>][,<version>]"

   (See the FS-Stnd for a few common <locale> strings.)
   According to these guidelines, we have our man pages in
   /usr/man/<locale>/man[1-9lno]. The formatted versions should then be
   in /usr/man/<locale>/cat[1-9lno] of course, otherwise we could only
   provide them for a single locale.

   HOWEVER,