As a Unix administrator, the one word of sage advice you can give to any user that is guaranteed to solve any problem is RTFM.
What's an administrator to do when informed by a user that there is no manpage to read? Perhaps the application in question is a custom application or script, or perhaps it's a third-party program that didn't come with a manpage. Why not create the missing manual yourself?
9.3.1 Manpage Basics
Creating a manpage isn't all that difficult. After all, a manpage is simply a text file more specifically, a gzipped text file sprinkled with groff macros. (I'm quite sure groff gets its name from the choking sound you make as you try to decipher its manpage.) For man to do its magic, which starts with being able to find the page, the manpage must live in a directory manpath can see.
Not surprisingly, manpath's configuration file, /etc/manpath.config, contains those paths:
% grep MAP /etc/manpath.config # MANPATH_MAP path_element manpath_element MANPATH_MAP /bin /usr/share/man MANPATH_MAP /usr/bin /usr/share/man MANPATH_MAP /usr/local/bin /usr/local/man MANPATH_MAP /usr/X11R6/bin /usr/X11R6/man
Basically, manpages to programs that come with the system live in /usr/share/man, third-party applications use /usr/local/man, and X applications use /usr/X11R6/man. If you ls any of these directories, you'll find directory names that go from man1 to man9. If you're rusty on the function of each manpage section, run:
% whatis intro intro(1) - introduction to general commands (tools and utilities) intro(2) - introduction to system calls and error numbers intro(3) - introduction to the C libraries intro(4) - introduction to devices and device drivers intro(5) - introduction to file formats intro(6) - introduction to games intro(7) - miscellaneous information pages intro(8) - introduction to system maintenance and operation commands intro(9) - introduction to system kernel interfaces
To read a specific section, specify the number between the command and the page, as in man 7 foo.
9.3.2 Creating a Manpage
You can whip up a nicely formatted manpage by knowing only three groff commands, as shown in Table 9-1.
The easiest way to convince yourself of this is to take a few minutes to type out the following custom manpage. When you're finished, save it as /usr/local/man/man1/boss.1 (as the root user) and view it with man boss. That way, you'll be able to compare those formatting sequences with how the results are displayed on your screen.
.\" Manpage for boss. .\" Contact firstname.lastname@example.org to correct errors or omissions. .TH man 1 "04 January 2004" "1.0" "boss man page" .SH NAME boss \- man page for boss .SH SYNOPSIS boss .SH DESCRIPTION The boss is an ornery creature that can be appeased with doughnuts and the occasional afternoon off for golf. .SH OPTIONS The boss does not take any options. .SH SEE ALSO doughnut(1), golf(8) .SH BUGS No known bugs at this time. .SH AUTHOR Dru Lavigne (email@example.com)
If you take the time to view this listing, you'll find it looks like any manpage. In fact, it's an excellent idea to take a look at several manpages before you create your own. This will give you an idea of how you'd like your custom page to appear.
Notice first that the lines that began with .\" don't appear anywhere in the formatted manpage, as they are comments. The information in the title (.TH) line appears at the very top and bottom of the manpage. The .SH lines appear nicely bolded, and the following lines are indented for you. Remember that SH. NAME is mandatory, but you can create as many .SH sections as you wish.
As you read other manpages, you'll see that SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, DIAGNOSTICS, ENVIRONMENT, SEE ALSO, HISTORY, and BUGS are quite common. You'll also get an idea of what type of text belongs in each section.
9.3.3 Getting Fancier
If you want to include fancier formatting in your manpage, find an existing manpage that has the desired format. Then, instead of opening the manpage with man, send it to zmore. (Remember, you won't be able to read gzipped manpages directly with more.)
For example, if I want to include switches, I'd borrow from a manpage with switches. ls springs to mind. So I'll read through:
% zmore /usr/share/man/man1/ls.1.gz
and compare it to man ls. In this manpage, the switches occur in the DESCRIPTION section and the first switch is -A. The switch itself is in bold text and the switch description is indented with the characters . and .. covered over with white. The formatting sequences to achieve this are:
.BL -tag -width indent .It Fl A List all entries except for .Pa \&. and .Pa .. .
If you're curious as to the exact meaning of each formatting sequence, you'll find them scattered throughout man 7 groff. If you don't have the time to be curious, simply find the section that does what you want and add it to your own manpage. Save your results, then see if it worked by sending your custom manpage to man.
9.3.4 Printing Manpages
It's often desirable to print certain manpages. If you've ever tried sending a manpage directly to a printer, you probably found that the results weren't what you were expecting. However, you can use groff to convert the manpage to something more printer-friendly. PostScript is usually your best bet, and you're in luck, as groff knows how to convert to PostScript.
First, it's not a bad idea to get the exact location of the source of the manpage. Continuing with ls as an example:
% man -w ls /usr/share/man/cat1/ls.1.gz (source: /usr/share/man/man1/ls.1.gz)
Note that you're interested in the source, not in the location that includes the word cat.
Once you know the location, use zcat to open the compressed file, pipe the results to groff, and redirect the groff output to a PostScript file:
# zcat /usr/share/man/man1/ls.1.gz | groff > ls.ps # file ls.ps ls.ps: PostScript document text conforming at level 3.0
Note that the default invocation of groff assumes that you wish to convert a manpage to PostScript, so you need no additional switches.
9.3.5 Hacking the Hack
If you'd like to publish your manpages on a local web site, groff can also convert to HTML see man 1 groff for details.
If you prefer to convert to PDF, consider installing GNU GhostScript from your ports or packages collection. Once installed, read man 1 gs for more details.
9.3.6 See Also