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.