How should a formatted man page look?

Linux Man Page Howto
Prev |  | Next

# 3. How should a formatted man page look?

Let me present you an example. Below I will explain it in detail. If you read this as plain text it won't show the different typefaces (bold and italics). [TODO: the bold and italics has disappeared with the conversion to SGML/HTML; Bring it back.] Please refer to the paragraph "What are the font conventions?" for further explanations. Here comes the man page for the (hypothetical) `foo` program.

    FOO(1)                     User Manuals                    FOO(1)

    NAME
        foo - frobnicate the bar library

    SYNOPSIS
        foo [-bar] [-c config-file ] file ...

    DESCRIPTION
         foo  frobnicates the bar library by tweaking internal symbol
         tables. By default it parses all baz segments and rearranges
         them  in  reverse  order  by time for the xyzzy(1) linker to
         find them. The symdef entry is then compressed using the WBG
         (Whiz-Bang-Gizmo) algorithm.  All files are processed in the
         order specified.

    OPTIONS
         -b   Do not write `busy' to stdout while processing.

         -c config-file
              Use the alternate system wide  config-file  instead  of
              /etc/foo.conf.   This overrides any FOOCONF environment
              variable.

         -a   In addition to the baz segments, also parse the  blurfl
              headers.

         -r   Recursive  mode.  Operates  as fast as lightning at the
              expense of a megabyte of virtual memory.

    FILES
         /etc/foo.conf
              The system wide configuration file. See foo(5) for fur-
              ther details.
         ~/.foorc
              Per  user  configuration  file.  See foo(5) for further
              details.

    ENVIRONMENT
         FOOCONF
              If non-null the full pathname for an  alternate  system
              wide foo.conf.  Overridden by the -c option.

    DIAGNOSTICS
         The following diagnostics may be issued on stderr:

         Bad magic number.
              The input file does not look like an archive file.
         Old style baz segments.
              foo  can  only  handle  new  style  baz segments. COBOL
              object libraries are not supported in this version.

    BUGS
         The command name should have been chosen more  carefully  to
         reflect its purpose.

    AUTHOR
         Jens Schweikhardt <howto at schweikhardt dot net>

    SEE ALSO
         bar(1), foo(5), xyzzy(1)

    Linux                Last change: MARCH 1995                    2

Here's the explanation as I promised.

The NAME section

...is the only required section. Man pages without a name section are as useful as refrigerators at the north pole. This section also has a standardized format consisting of a comma-separated list of program or function names, followed by a dash, followed by a short (usually one line) description of the functionality the program (or function, or file) is supposed to provide. By means of `makewhatis`(8), the name sections make it into the `whatis` database files. `Makewhatis` is the reason the name section must exist, and why it must adhere to the format I described. In the `groff` source it must look like

.SH NAME foo \- frobnicate the bar library

The \- is of importance here. The backslash is needed to make the dash distinct from a hyphenation dash that may appear in either the command name or the one line description.

The SYNOPSIS section

...is intended to give a short overview on available program options. For functions this sections lists corresponding include files and the prototype so the programmer knows the type and number of arguments as well as the return type.

The DESCRIPTION section

...eloquently explains why your sequence of 0s and 1s is worth anything at all. Here's where you write down all your knowledge. This is the Hall Of Fame. Win other programmers' and users' admiration by making this section the source of reliable and detailed information. Explain what the arguments are for, the file format, what algorithms do the dirty jobs.

The OPTIONS section

...gives a description of how each option affects program behaviour. You knew that, didn't you?

The FILES section

...lists files the program or function uses. For example, it lists configuration files, startup files, and files the program directly operates on. It is a good idea to give the full pathname of these files and to make the install process modify the directory part to match user preferences: the `groff` manuals have a default prefix of /usr/local, so they reference /usr/local/lib/groff/* by default. However, if you install using 'make prefix=/opt/gnu' the references in the man page change to /opt/gnu/lib/groff/*

The ENVIRONMENT section

...lists all environment variables that affect your program or function and tells how, of course. Most commonly the variables will hold pathnames, filenames or default options.

The DIAGNOSTICS section

...should give an overview of the most common error messages from your program and how to cope with them. There's no need to explain system error error messages (from `perror`(3)) or fatal signals (from `psignal`(3)) as they can appear during execution of any program.

The BUGS section

...should ideally be non-existent. If you're brave, you can describe here the limitations, known inconveniences and features that others may regard as misfeatures. If you're not so brave, rename it the TO DO section ;-)

The AUTHOR section

...is nice to have in case there are gross errors in the documentation or program behaviour (Bzzt!) and you want to mail a bug report.

The SEE ALSO section

...is a list of related man pages in alphabetical order. Conventionally, it is the last section. You are free to invent other sections if they really don't fit in one of those described so far. So how exactly did you generate that man page? I expected that question, here's the source, Luke:

    .\" Process this file with
    .\" groff -man -Tascii foo.1
    .\"
    .TH FOO 1 "MARCH 1995" Linux "User Manuals"
    .SH NAME
    foo \- frobnicate the bar library
    .SH SYNOPSIS
    .B foo [-bar] [-c
    .I config-file
    .B ]
    .I file
    .B ...
    .SH DESCRIPTION
    .B foo
    frobnicates the bar library by tweaking internal
    symbol tables. By default it parses all baz segments
    and rearranges them in reverse order by time for the
    .BR xyzzy (1)
    linker to find them. The symdef entry is then compressed
    using the WBG (Whiz-Bang-Gizmo) algorithm.
    All files are processed in the order specified.
    .SH OPTIONS
    .IP -b
    Do not write `busy' to stdout while processing.
    .IP "-c config-file"
    Use the alternate system wide
    .I config-file
    instead of
    .IR /etc/foo.conf .
    This overrides any
    .B FOOCONF
    environment variable.
    .IP -a
    In addition to the baz segments, also parse the
    blurfl headers.
    .IP -r
    Recursive mode. Operates as fast as lightning
    at the expense of a megabyte of virtual memory.
    .SH FILES
    .I /etc/foo.conf
    .RS
    The system wide configuration file. See
    .BR foo (5)
    for further details.
    .RE
    .I ~/.foorc
    .RS
    Per user configuration file. See
    .BR foo (5)
    for further details.
    .SH ENVIRONMENT
    .IP FOOCONF
    If non-null the full pathname for an alternate system wide
    .IR foo.conf .
    Overridden by the
    .B -c
    option.
    .SH DIAGNOSTICS
    The following diagnostics may be issued on stderr:

    Bad magic number.
    .RS
    The input file does not look like an archive file.
    .RE
    Old style baz segments.
    .RS
    .B foo
    can only handle new style baz segments. COBOL
    object libraries are not supported in this version.
    .SH BUGS
    The command name should have been chosen more carefully
    to reflect its purpose.
    .SH AUTHOR
    Jens Schweikhardt <howto at schweikhardt dot net>
    .SH "SEE ALSO"
    .BR bar (1),
    .BR foo (5),
    .BR xyzzy (1)

Prev | Home | Next
How are man pages accessed? |  | How do I document several programs/functions in a single man page?