How do I document several programs/functions in a single man page?

Linux Man Page Howto
Prev |  | Next

# 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:

1. have identical copies for each name.

2. connect all man pages using hard links.

3. symbolic links pointing to the actual man page.

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

Prev | Home | Next
How should a formatted man page look? |  | Which macro package should I use?