Make Your Own Manpages Without Learning troff (Unix Power Tools, 3rd Edition)

3.21. Make Your Own Manpages 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 -man macros (Section 3.22) 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 previously. 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.

NOTE: 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 (Section 2.1) command is essentially the same as this:

-s Section 11.7

% nroff -e -man filename | more -s

Go to http://examples.oreilly.com/upt3 for more information on: gnroffawf

You can safely omit the -e option to nroff and the -s option to more, or even substitute in your favorite pager, such as less. And remember that nroff may not be available on all systems, but the web site has gnroff and awf. In fact, on some systems, nroff is simply a script that emulates the real nroff using groff.

Now, you want to make this manual page "readable" by the standard man command. There are a few ways to do this, depending on your system. 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, try the command:

~ Section 31.11

% man -M ~/man program

NOTE: 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 as follows:
% man -M ~ program

Some systems have a MANPATH environment variable (Section 35.3), 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.

NOTE: 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"). You may need to create /usr/local and /usr/local/man first. 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 other systems, 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 (Section 29.3):

less Section 12.3

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

or shell function (Section 29.11):

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

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 system manual page directory for section 1; 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 gzip (Section 15.6) utility on your documentation file. The resulting file will have the name program.1.gz; newer versions of the man command will automatically uncompress the file on-the-fly.

--ML and SJC