50.10 Make Your Own Man Pages Without Learning troff

We strongly suggest that you write a manual page for each command that you place in your bin directory. UNIX manual pages typically have the following format, which we suggest you follow:

NAME
     the program's name - one line summary of what it does

SYNOPSIS
     how to invoke the program, including all arguments and
     command-line options. (Optional arguments
     are placed in square brackets)

DESCRIPTION
     a description of what the program does-as long as is necessary

OPTIONS
     an explanation of each option

EXAMPLES
     One or more examples of how to use the program

ENVIRONMENT
     Any environment variables that control the program's behavior

FILES
     Files the program internals will read or write.  May include
     temporary files.  Doesn't include files on the command line.

BUGS
     Any known bugs. The standard manual pages don't take
     bug-recording seriously, but this can be very helpful.

AUTHOR
     Who wrote the program

To see how a "real" manual page looks, type man ls.

Feel free to add any other sections that you think are necessary. You can use the nroff (43.13) -man macros (50.11) if you want a nicely formatted manual page. However, nroff is fairly complicated and, for this purpose, not really necessary. Just create a text file that looks like the one we showed above. If you are using a BSD system and want your manual pages formatted with nroff, look at any of the files in /usr/man/man1 and copy it.

Hint: If you insist on formatting your manual page properly, using the troff or groff "man" macros, you can use nroff to preview the file. The man (50.1) command is essentially the same as:

more -s	% nroff -e -man filename | more -s

You can safely omit the -e option to nroff and the -s option to more. And remember that nroff may not be available on many versions of System V UNIX, but the Power Tools disc has gnroff and awf (43.17).

Now, you want to make this manual page "readable" by the standard man command. For BSD systems, there are a few ways to do this. Create the directory man in your home directory; create the directory cat1 as a subdirectory of man; then copy your manual entry into cat1, with the name program.1 (where program is the name of your special command). When you want to read the manual page, give the command:

~	% man -M ~/man program

Shortcut: We like to be more strict about naming things properly, but you can omit the man directory, and just put the cat1 directory into your home directory. In this case, the command would be:

% man -M ~ program

Some systems have a MANPATH environment variable (6.1), a colon-separated list of directories where the man command should look. For example, my MANPATH contains:

/home/mike/man:/usr/local/man:/usr/man

MANPATH can be more convenient than the -M option.

HINT: We are telling you to put the manual page into the cat1 directory rather than the man1 directory because the man program assumes that files in cat1 are already formatted.

If you are sharing your program with other people on the system, you should put your manual entry in a public place. Become superuser and copy your documentation into /usr/local/man/catl, giving it the name program.l (the "l" stands for "local"). If you can't become superuser, get the system administrator to do it for you. Make sure that everyone can read the manual page; the permissions should be something like this:

% ls -l /usr/local/man/catl
-r--r--r--  1 root          468 Aug  5 09:21 program.l

Then give the command man program to read your documentation.

If you are working on some System V variants, the rules are a little different. The organization of the manual pages and the man command itself are slightly different - and really, not as good. Write your manual entry and place it in your doc directory. Then create the following C shell alias (10.3):

alias myman "(cd ~/doc; man -d \!$ | pg)"

or shell function (10.9):

myman() { (cd $HOME/doc; man -d "$1" | pg); }

Now the command myman docfilename will retrieve your manual page. Note that if you use a section-number extension like .1, you have to give the entire filename (e.g., program.1), not just the program's name.

If you want to make your manual page publicly available, copy the file into the directory /usr/man/u_man/man1; you may have to become superuser to do so. Make sure that anyone on the system can read your file. If the entry is extremely long and you want to save space in your filesystem, you can use the pack utility on your documentation file. The resulting file will have the name program.1.z; the man command will automatically unpack the file whenever anyone reads it.