= Man Page HOWTO

== Introduction

See further information on link:#copying[copying conditions] below.

$Id$

The author's latest version is at
http://www.schweikhardt.net/man_page_howto.html. 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.

[[q1]]
== 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(1)`, `makewhatis(8)`, `catman(8)`. Reliability and
accuracy of the information are, of course, up to you. But even in this
respect you will find link:#q9[some ideas below] that help you avoid
some common glitches.

[[xml]]
== Why not to write a man page!

Man pages will remain an important distribution format, but nowadays
there are good reasons to consider writing your documentation masters in
a richer, more Web-friendly format. Many open-source projects (including
the Linux kernel, GNOME, KDE, FreeBSD, the Free Software Foundation, and
the Linux Documentation Project) have agreed to use XML-DocBook as their
preferred master format.

There are many good reasons for this, including the fact that moving to
XML will give you the ability to easily generate both HTML and print
output from the same masters. Ultimately, moving to XML will allow rich
searching and indexing of documentation in ways that troff markup cannot
support.

Now that the http://cyberelk.net/tim/xmlto/[xmlto] toolchain is
generally available (it shipped with Red Hat 7.3), producing man pages
with XML-DocBook is easy. Write your page as a docbook RefEntry. You
will then ve able to generate troff markup from a document named
`foobar.xml` with this command:

....
bash$ xmlto man foobar.xml
....

Note that this gives you troff macro source that can be installed in the
man hierarchy just as though you had written it by hand. It is good
practice to ship both the XML source and the generated man page source
with your distribution.

If you have an existing man page you want to convert up to an XML
RefEntry, that's also easy to do. Please consider converting your
existing documentation with
http://www.catb.org/~esr/doclifter/[doclifter].

Some of the good-practice guidelines we'll recommend below make it easy
for conversion tools like doclifter to do their work, so that even if
you choose to keep maintaining your documentation as `man(7)` sources,
distribution-makers and othere will be able to automatically translate
it into something XML tools can work on.

== If you decide to write in man(7) format...

It's not 1978 any more, there are more devices in the world than the
now-extinct CAT phototypesetter troff was designed for, and you don't
really know which one your readers will be using to view your page. So
it's much more important than it used to be to write your man page
structurally, and avoid trying to pull visual tricks with low-level
troff requests. They probably won't come out as you intended, anyway —
man page viewers and parsers often don't know how to interpret those
tricks.

Here are the safe requests:

.The Good
[cols=",",]
|===
|.SH, .SS |Section and subsection headers. Safe as houses.

|.P, .PP |New-paragraph macros. Equally safe.

|.TP |All-purpose tagged list construct. Be careful what you put after
these; remember that `.PP` resets the indent and ends the list.

|.UR, .UE, .UN |Hyperlink macros. Generally harmless when
misinterpreted.
|===

If you want to make your man page device-dependent and hard to parse,
here are some excellent way to accomplish that:

.The Bad
[cols=",",]
|===
|.LP |Synonym for `.PP`. Historically, `.LP` had a slightly different
effect on whitespace than `.PP`, but the distinction is lost in modern
versions. Still, you never know where your page will be read, nor with
how archaic a version of the man macros....

|.RS, .RE |Change relative indent. Confuses the heck out of programs,
especially when it's intermingled with stuff like `.TP`. Avoid.

|.ta, .DT |Troff-level tab set, and tab reset. Dubious in a modern,
multi-device environment where you can't necessarily predict tab
settings.

|.HP |Hanging-indent macro. Just messes with whitespace, so you don't
actually know what the results will be on different devices.

|.PD |Interparagraph-vertical-distance setting. Almost guaranteed to be
useless in a modern environment. What's that going to mean on a web
page, bunky?

|.IP |Indented-paragraph macro. The two-argument version with a bullet
is not completely useless, but consider using `.TP` instead. It's easy
to get confused and write the single-argument version, which only messes
with indentation.
|===

If you care about being friendly to XML translation, it's also wise to
stay away from using low-level troff constructs like `.br`, `.in` and
`.ti` to tweak the whitespace in your page layout. The whitespace layout
won't be preserved anyway, and translator programs have a hard time
interpreting these structurally.

Finally, one bad construct we just can't get around using:

.The Ugly
[cols=",",]
|===
|.nf, .fi |The stop-filling and start-filling macros. Necessary because
stock man(7) doesn't have anything like Ultrix's `.EX`/`.EE` or mm's
`.DS`/`.DE` for unfilled displays (like program listings and command
examples).
|===

There is more about good use of font macros link:#q8[ later in the
document].

[[q2]]
== How are man pages accessed?

You need to know the precise mechanism for acccessing man pages in order
to give your man page the right name and install it in the right place.
Each man page should be categorized in a specific section, denoted by a
single character. The most common sections under Linux, and their human
readable names, are:

[cols=",",options="header",]
|===
|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 |(Deprecated) New documentation, that may be moved to a more
appropriate section.

|o |(Deprecated) Old documentation, that may be kept for a grace period.

|l |(Deprecated) Local documentation referring to this particular
system.
|===

The name of the man page's source file (the input to the formatting
system) is the name of the command, function or file name, followed by a
dot, followed by the section character. 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'.

[NOTE]
====
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 having someone execute your program
but read someone else's man page, or vice versa. Checking out the
http://www.execpc.com/lsm/[Linux Software Map] (LSM) database on a
program name is a place to start ensuring name uniqueness.

Now we know the name to give our file. The next decision is the
directory in which it will finally be installed (say, when the user runs
``make install`' for your package.) On Linux, all man pages are below
directories listed in the environment variable `MANPATH`. The
doc-related tools use `MANPATH` in the same way the shell uses PATH to
locate executables. In fact, `MANPATH` has the same format as PATH. Each
contains a colon-separated list of directories (with the exception that
`MANPATH` does not allow empty fields and relative pathnames -- it uses
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 designator introduced in the link:#q2[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
link:#q12[paragraph 12]. 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
ftp://tsx-11.mit.edu/pub/linux/docs/linux-standards/fsstnd/[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*, I can not recommend switching to that structure at this time.
The FS-Stnd 1.2 also allows that

* "Systems which use a unique language and code set for all manual pages
may omit the <locale> substring and store all manual pages in <mandir>.
For example, systems which only have English manual pages coded with
ASCII, may store manual pages (the man[1-9] directories) directly in
/usr/man. (That is the traditional circumstance and arrangement in
fact.)"

I would not switch until all tools (like xman, tkman, info and many
others that read man pages) can cope with the new structure.

[[q3]]
== 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_). Please refer to the paragraph link:#q8[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
....

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)
....

Here's the explanation as I promised.

[[NAME]]
=== 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.

Please do not make more than one of these name lines. Some people have
done this on man pages that document multiple closely related commands,
but it's not a good idea. Linux `makewhatis(8)` indexes on words found
in DESCRIPTION and INTRODUCTION sections as well as the NAME line, so as
long as you put your key word somewhere in that text you'll get the same
effect. And `apropos(1)` only display the first description line anyway.
Finally multiple name/description lines cannot be automatically
translated to RefEntry format, which permits multiple names but only one
description. So, if you're tempted to write something like:

....
.SH NAME
mzip2, munzip2 \- a magic file compressor
.br
mzcat \- decompresses files to stdout
.br
mzip2recover \- recovers data from damaged mzip2 files
....

please do this instead:

....
.SH NAME
mzip2, munzip2, mzcat, mzip2recover \- file compression and decompression tools
.SH DESCRIPTION
.I mzcat 
decompresses files to stdout
.PP
.I mzip2recover
recovers data from damaged mzip2 files
....

=== The SYNOPSIS section

...is intended to give a short overview of 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.

When writing command synopses, remember the standard notation:

[cols=",",options="header",]
|===
|Notation: |Meaning
|arg... |Required argument, can be repeated any number of times. Please
don't use "arg+" for this!

|[ arg ] |Optional argument — may be omitted

|[ arg... ] |Optional argument — may be omitted, but can be repeated any
number of times. Please don't write "[arg]..." or "arg*" for this!

|[ arg1 \| arg2 \| ... argn ] |Any one of these options, optionally

|\{ arg1 \| arg2 \| ... argn } |Any one of these options, but at least
one in the group is required. Please don't write this with parens,
rather than set braces!
|===

If you have a program with a bunch of single-character options, please
avoid writing the synopsis in the old terse Bell Labs style, e.g:

....
doclifter [ -qhsvx ] file...
....

This is too easily confused with the newer X-style keyword option like
-geometry (which is why it's GNU practice to lead long options with a
double dash). For the benefit of programs that actually parse
command-synopsis notation, it is better to be more explicit:

....
doclifter [ -q ] [ -h ] [ -s ] [ -v ] [ -x ] file...
....

Please don't include running test in this section. E.g. rather than
this:

....
.SH SYNOPSIS
.TP
.B ddd
.RB "[\|" \-\-help "\|]"
.RB "[\|" \-\-gdb "\|]"
.RB "[\|" \-\-dbx "\|]"
.TP
but usually just
.TP
.B ddd
.I program
....

write this:

....
.SH SYNOPSIS
.TP
.B ddd
.RB "[\|" \-\-help "\|]"
.RB "[\|" \-\-gdb "\|]"
.RB "[\|" \-\-dbx "\|]"
.SH USAGE
This program is usually just invoked as
.B ddd
.I program
....

DocBook has a markup sub-language for describing command synopses that
unfortunately doesn't have a way to describe text annotations. Tools
like doclifter that try to translate man pages to DocBook cannot
automatically know what to do with such annotations.

If you're writing a description of C function entry points to a library,
there are two style guidelines to keep in mind:

First, put any struct declarations, typedefs, and externs of variables
_before_ the function entry point declarations, rather than after (just
as you would in a program).

Second, use ANSI C prototype syntax rather than K&R. That is, instead of
this:

....
int foo(ptr)
char *ptr;
....

write this:

....
int foo(char *ptr);
....

just as the function would appear in a modern header file.

=== 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 command-line option affects program
behaviour. You knew that, didn't you? If your program is simple enough,
this information may be folded into the DESCRIPTION section.

=== 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.

[[q4]]
== How do I document several programs/functions in a single man page?

Many programs (grep, egrep) and functions (`printf`, `fprintf`, ...) are
documented in a single man page. However, these man pages would be quite
useless if they were only accessible under one name. We cannot expect a
user to remember that the egrep man page is actually the grep man page.
It is therefore necessary to have the man page available under different
names. You have several possibilities to achieve this:

[arabic]
. have identical copies for each name.
. connect all man pages using hard links.
. symbolic links pointing to the actual man page.
. use groff's `source' mechanism provided by the `.so` macro.

The first way is obviously a waste of disk space. The second is not
recommended because intelligent versions of the catman program can save
a lot of work by looking at the the file type or contents. Hard links
will prevent catman from being clever. (Note that catman's purpose is to
format all man pages so they can be displayed quickly.) The third
alternative has a slight drawback: if flexibility is a concern, you have
to be aware that there are file systems that do not support symbolic
links. The upshot of this is that the Best Thing (TM) is using groff's
source mechanism. Here's how to do it: If you want to have your man page
available under the names `foo' and `bar' in section 1, then put the man
page in foo.1 and have bar.1 look like this:

....
.so man1/foo.1
....

It is important to specify the `man1/` directory part as well as the
file name `foo.1' because when groff is run by the browser it will have
the manual base directory as its current working directory (cwd) and
groff interprets `.so` arguments relative to the cwd.

[[q5]]
== Which macro package should I use?

There are a number of macro packages especially designed for use in
writing man pages. Usually they are in the groff macro directory
`/usr/lib/groff/tmac`. The file names are `tmac.<something>`, where
<something> is the argument to groff's -m option. Groff will use
`tmac.<something>` when it is given the ``-m` <something>' option. Often
the blank between ``-m`' and `<something>' is omitted so we may say
``groff -man`' when we are formatting man pages using the `tmac.an`
macro package. That's the reason for the strange name `tmac.an'. Besides
tmac.an there is another popular macro package, `tmac.doc`, which
originated at the University of California at Berkeley. Many BSD man
pages use it and it seems that UCB has made it its standard for
documentation. The `tmac.doc` macros are much more flexible but alas,
there are manual browsers that will not use them but always call
`groff -man`. For example, all xman programs I have seen will screw up
on man pages requiring `tmac.doc`. So do yourself a favor: use `tmac.an`
-- use of any other macro package is considered harmful. `tmac.andoc`is
a pseudo macro package that takes a look at the source and then loads
either `tmac.an` or `tmac.doc`. Actually, any man page browser should
use it but to this point, not all of them do, so it is best we cling to
ye olde `tmac.an`. Anything I tell you from now on and concerning macros
only holds true for `tmac.an`. If you want to use the `tmac.doc` macros
anyway, here is a pointer to detailed information on how to use them:
http://www.freebsd.org/cgi/man.cgi[http://www.FreeBSD.org/cgi/man.cgi].
There is a searchable index form on the page. Enter `groff_mdoc` and it
will find you `groff_mdoc(7)`, a tutorial sampler for writing BSD man
pages. Some distros (I'm told) also come with `mdoc(7)`,
`mdoc_samples(7)`, and `groff_man(7)`.

The definitive dope for troff, with all macros explained, is the Troff
User's Manual, available as
http://cm.bell-labs.com/sys/doc/troff.html[html],
http://cm.bell-labs.com/sys/doc/troff.ps[PostScript (ps&#44; 760K)] or
http://cm.bell-labs.com/sys/doc/troff.pdf[Portable Document Format
(pdf&#44; 240K)]. by Jospeh F. Ossanna and Brian W. Kernighan, revised
November 1992. AT&T Bell Labs have made it publicly available. Don't
forget to check out the late great http://www.kohala.com/start/[W.
Richard Steven's homepage] (famous for Unix Network Programming as well
as the _TCP/IP Illustrated_ trilogy), who also has a list of
http://www.kohala.com/start/troff/troff.html[Troff Resources] including
tbl, eqn, pic and other filters.

[[q6]]
== What preprocessors may I use?

Groff comes with at least three preprocessors, tbl, eqn, and pic (on
some systems they are named gtbl, geqn and gpic.) Their purpose is to
translate preprocessor macros and their data to regular troff input. Tbl
is a table preprocessor, eqn is an equations/maths preprocessor and pic
is a picture preprocessor. Please refer to the man pages for more
information on what functionality they provide. To put it in a nutshell:
don't write man pages requiring _any_ preprocessor. Eqn will generally
produce terrible output for typewriter-like devices, unfortunately the
type of device 99% of all man pages are viewed on (well, at least I do).
For example, XAllocColor.3x uses a few formulas with exponentiation. Due
to the nature of typewriter-like devices, the exponent will be on the
same line as the base. N to the power of two appears as `N2'. Tbl should
be avoided because all xman programs I have seen fail on them. Xman
3.1.6 uses the following command to format man pages, e.g. `signal(7)`:

....
gtbl /usr/man/man7/signal.7 | geqn | gtbl |  \
        groff -Tascii -man /tmp/xmana01760 2> /dev/null
....

which screws up for sources using gtbl, because gtbl output is fed again
into gtbl. The effect is a man page without your table. I don't know if
it's a bug or a feature that gtbl chokes on its own output or if xman
could be a little smarter and not use gtbl twice. Furthermore, some
systems use grog to determine what options to pass to groff.
Unfortunately grog sometimes guesses wrong and recommends `groff -t`
when in fact tbl must not be used.

We are basically left with two workarounds for tables:

[arabic]
. Format the table yourself manually and put it between .nf and .fi
lines so that it will be left unformatted. You won't have bold and
italics this way but this beats having your table swallowed any day.
. Use any tbl macros you like but distribute the tbl output instead of
the input. There is however this quirk with grog who thinks that any
file containing a line starting with `.TS` requires tbl. Tbl output for
some reason unbeknownst to me still contains `.TS` and `.TE`. It seems
you can simply remove them and have the result still look okay. YMMV, so
please test this with your particular man page.

I have yet to see a man page requiring pic preprocessing. But I would
not like it. As you can see above, xman will not use it and groff will
certainly do the funky wadakiki on the input.

[[q7]]
== Should I distribute source and/or already formatted documentation?

Let me give the pros and cons of a few selected possibilities:

Source only:::
  * _Pro:_ smaller distribution package.
  * _Con:_ inaccessible on systems without groff.
Uncompressed formatted only:::
  * _Pro:_ accessible even on systems without groff.
  * _Con:_ the user can't generate a dvi or postscript file.
  * _Con:_ waste of disk space on systems that also handle compressed
  pages.
Compressed formatted only:::
  * _Pro:_ accessible even on systems without groff.
  * _Con:_ the user can't generate a dvi or postscript file.
  * _Con:_ which compression format would you use? .Z? .z? .gz? All of
  them?
Source and uncompressed formatted:::
  * _Pro:_ accessible even on systems without groff.
  * _Con:_ larger distribution package
  * _Con:_ some systems may expect compressed formatted man pages.
  * _Con:_ redundant information on systems equipped with groff.

IMHO it is best to distribute source only. The argument that it's
inaccessible on systems without groff does not matter. The 500+ man
pages of the Linux Documentation Project are source only. The man pages
of XFree86 are source only. The man pages from the FSF are source only.
In fact, I have rarely seen software distributed with formatted man
pages. If any sysadmin is really concerned about having man pages
accessible then he also has groff installed.

[[q8]]
== What are the font conventions?

First of all: don't use direct font operators like `\fB`, `\fP` etc. Use
macros which take arguments. This way you avoid a common glitch:
forgetting the font change at the end of the word and having the bold or
italic extend up to the next font change. Believe me, it happens more
often than you think. The `tmac.an` macros provide the following type
faces:

[cols=",",]
|===
|B |Bold
|BI |Bold alternating with italics
|BR |Bold alternating with Roman
|I |Italics
|IB |Italics alternating with bold
|IR |Italics alternating with Roman
|RB |Roman alternating with bold
|RI |Roman alternating with italics
|SM |Small (scaled 9/10 of the regular size)
|SB |Small bold (_not_ small alternating with bold)
|===

X alternating with Y means that the odd arguments are typeset in X while
the even arguments are typeset in Y. For example

....
.BI "Arg 1 is Bold, " "Arg 2 is Italics, " "and= Bold, " "and Italics."
....

The double quotes are needed to include white space into an argument;
without them, no white space appears between the alternating typefaces.
In fact, you'll only need the macros for alternating typefaces in cases
where you _want_ to avoid white space between typeface changes. So much
for what's available. Here's how you should make use of the different
typefaces: (portions shamelessly stolen from man(7))

Although there are many arbitrary conventions for man pages in the UNIX
world, the existence of several hundred Linux-specific man pages defines
our standards: For functions, the arguments are always specified using
italics, even in the SYNOPSIS section, where the rest of the function is
specified in bold:

....
.BI "myfunction(int " argc ", char **" argv ); 
....

Filenames are always in italics, except in the SYNOPSIS section, where
included files are in bold. So you should use

....
.I /usr/include/stdio.h
....

and

....
.B #include <stdio.h>
....

Special macros, which are usually in upper case, are in bold:

....
.B MAXINT
....

When enumerating a list of error codes, the codes are in bold. This list
usually uses the `.TP` (paragraph with hanging tag) macro as follows:

....
.TP
.B EBADF
.I fd is not a valid file descriptor.
.TP 
.B EINVAL 
.I fd is unsuitable for reading 
....

Any reference to another man page (or to the subject of the current man
page) is in bold. If the manual section number is given, it is given in
Roman, without any spaces:

....
.BR man (7)
....

Acronyms look best when typeset in small-caps type face. So I recommend

[[q9]]
== Polishing your man page

Following are some guidelines that increase reliability, readability and
'formatability' of your documentation.

* Test examples to make sure they work (use cut and paste to give your
shell the exact wording from the man page). Copy the output of your
command into your man page, don't just type what you _think_ your
program will print.
* Proof read, ispell, and have someone else read it, especially if you
are not a native English speaker. The HOWTO you are reading has passed
the latter test (special thanks to Michael Miller for a particularly
heroic contribution! All the remaining rough edges are entirely my
fault). Additional volunteers are always welcome.
* Test your man page: Does groff complain when you format your man page?
It's nice to have the groff command line in a comment. Does the `man(1)`
command complain when you call `man yourprog`? Does it produce the
expected result? Will `xman(1m)` and `tkman(1tk)` cope with your manual?
XFree86 3.1 has xman 3.1.6 - X11R6, it will try to uncompress using:
+
....
gzip -c -d < %s > %s
zcat < %s > %s 
....
* Will `makewhatis(8)` be able to extract the one-line description from
the NAME section?

[[q10]]
== How do I get a plain text man page without all that ^H^_ stuff?

Have a look at `col(1)`, because col can filter out backspace sequences.
Just in case you can't wait that long:

....
funnyprompt$ groff -t -e -mandoc -Tascii manpage.1 | \
               col -bx > manpage.txt
....

The `-t` and `-e` switches tell groff to preprocess using tbl and eqn.
This is overkill for man pages that don't require preprocessing but it
does no harm apart from a few CPU cycles wasted. On the other hand, not
using `-t` when it is actually required does harm: the table is terribly
formatted. You can even find out (well, "guess" is a better word) what
command is needed to format a certain groff document (not just man
pages) by issuing

....
funnyprompt$ grog /usr/man/man7/signal.7 groff -t -man /usr/man/man7/signal.7
....

"Grog" stands for "GROff Guess", and it does what it says — guess. If it
were perfect we wouldn't need options any more. I've seen it guess
incorrectly on macro packages and on preprocessors. Here is a little
perl script I wrote that can delete the page headers and footers,
thereby saving you a few pages (and mother nature a tree) when printing
long and elaborate man pages. Save it in a file named `strip-headers` &
chmod 755.

....
    #!/usr/bin/perl -wn
    #  make it slurp the whole file at once:
    undef $/;
    #  delete first header:
    s/^\n*.*\n+//;
    #  delete last footer:
    s/\n+.*\n+$/\n/g;
    #  delete page breaks:
    s/\n\n+[^ \t].*\n\n+(\S+).*\1\n\n+/\n/g;
    #  collapse two or more blank lines into a single one:
    s/\n{3,}/\n\n/g;
    #  see what's left...
    print;
....

You have to use it as the first filter after the man command as it
relies on the number of newlines being output by groff. For example:

....
funnyprompt$ man bash | strip-headers | col -bx > bash.txt
....

[[q11]]
== How do I get a high quality PostScript man page?

....
funnyprompt$ groff -t -e -mandoc -Tps manpage.1 > manpage.ps
....

Print or view that using your favorite PostScript printer/viewer. See
link:#q10[question 10)] for an explanation of the options.

[[q12]]
== How do I get `apropos' and `whatis' to work?

Suppose you wonder what compilers are installed on your system and how
these can be invoked. To answer this (frequently asked) question you say

....
funnyprompt$ apropos compiler
f77 (1) - Fortran 77 compiler
gcc (1) - GNU C and C++ compiler
pc (1) - Pascal compiler
....

Apropos and whatis are used to quickly report which man page has
information on a certain topic. Both programs search a number of files
named `whatis' that may be found in each of the manual base directories.
As previously stated, the whatis data base files contain a one line
entry for any man page in the respective directory tree. In fact, that
line is exactly the NAME section (to be precise: joined on one line and
with hyphenation removed; note that the section is mentioned within
parentheses). The whatis database files are created with the
`makewhatis(8)` program. There are several versions around, so please
refer to the man page to determine what options are available. In order
for makewhatis to be able to extract the NAME sections correctly it is
important that you, the manual writer, adhere to the NAME section format
described under link:#q3[question 3)]. The differences between apropos
and whatis are simply where in the line they look, and what they are
looking for. Apropos (which is equivalent to `man -k`) searches the
argument string anywhere on the line, whereas whatis (equivalent to
`man -f`) tries to match a complete command name only on the part before
the dash. Consequently, ``whatis cc`' will report if there is a cc
manual and remain quiet for gcc.

== Corrections and suggestions welcome!

[[copying]]
=== A) Copying conditions

Copyright 1995-2001 by Jens Schweikhardt. All rights reserved.

....
"Two clause" BSD License:

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.
....

[[acknowledgements]]
=== B) Acknowledgements

* Eric S. Raymond for converting the HTML to asciidoc.
* Michael Miller for proofreading the whole HOWTO (in February 2001);
Gordon Torrie for many helpful grammar remarks (in August 2001). Any
remaining grammar or style bogons are entirely my fault.
* http://www.suse.de/[S.u.S.E. (.de)] (or link:[.com]) who are the only
distributor to keep sending me a free copy of their latest product,
acknowledging my work as a howto author.

If your name is missing here, drop me a note.
