4. 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:
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.
