14.7 Adding Local man Pages


There's an old and somewhat scatological saying about a job not being finished until thepaperwork is done.[12] In the case of creating scripts and programs, this means writing some sort ofdocumentation. Tools you create can be documented in many different ways, but the usual Unix practice is to produce an online manual page. We'll conclude this chapter with a brief look at creating manual pages for the tools you develop.

[12] Imagine how it applies to writing a book.

Manual-page files are named for the command or utility that they describe, and they are given an extension that matches the number or letter of the man subdirectory in which they reside. For example, a manual-page file for the wgrep command placed into man1 subdirectory would be named wgrep.1.[13]

[13] Perl programs are traditionally documented withPOD, a scheme for embedding the documentation in the Perl source. Ugh.

The simplest possible manual page is just a text file describing a command or topic. However, if you'd like to create something a bit more elaborate, and more like the other manual pages typically found on Unix systems, it is very easy to do so. Manual-page source files are designed for the nroff text formatting system,[14] and they combine the text of the manual page with nroff directives specifying how to format the text. (Not all Unix versions provide the text formatting utilities by default or at all.)

[14] Or the GNU equivalent, groff.

The best way to figure out what the various nroff directives do is to see them in context. In general, they are placed at the beginning of a line and start with a period. Here is a brief manual page source file for the wgrep command, which can also serve as a template for manual pages you might create:

.TH wgrep l  .SH NAME  wgrep - windowed grep utility  .SH SYNOPSIS  wgrep [options] regexp file(s)  .SH DESCRIPTION  .B wgrep  is a  .B grep  utility which prints a window of lines surrounding  each matching line that it finds in the list of files. By default, the window is three lines before and after each matching line.  .PP  .B wgrep  has many options which control how its output looks.  It can range from plain to painfully excessive.  .SH OPTIONS  .TP 5  .B -w  Specifies the window size in the form  .B before:after Either one can be omitted.  .TP 5  .B -n  Include line numbers before each printed line.  .TP 5  .B -s  Include asterisks in front of matching lines.  .PP  .SH BUGS  None of course.  .SH SEE ALSO  egrep(1), VMS SEARCH command

Here is how the formatted version might look:

wgrep(l)                                                  wgrep(l) NAME          wgrep - windowed grep utility SYNOPSIS          wgrep  [options]  regexp  file(s) DESCRIPTION          wgrep is a grep utility which prints a window of lines surrounding each         matching line that it finds in the list of files. By default, the window is         three lines before and after each matching line.         wgrep has many options which control how its output looks. It can range from         plain to painfully excessive. OPTIONS          -w   Specifies the window size in the form before:after.              Either one can be omitted.         -n   Include line numbers before each printed line.         -s   Include asterisks in front of matching lines. BUGS          None, of course. SEE ALSO          egrep(1), VMS SEARCH command

Table 14-3 lists the nroff directives used in the sample manual page along with other related and useful directives.

Table 14-3. Useful nroff constructs

Directive

Explanation

.TH name section

Title heading.

.SH NAME

Section heading (names are uppercase by convention).

.TP [n]

Tagged paragraph: use hanging indent (of n spaces if specified).

.PP

Start new filled paragraph.

.IP

Indented paragraph.

.nf

Stop text filling (adjusting words on lines).

.fi

Start text filling.

.B text

Use bold type for text given as its argument.

.I text

Italicize text given as its argument.

.R text

Use roman type for text given as its argument.

You can simulate a man command for a manual page you are developing with a command like this one:

$ nroff -man file  | more

If you want a printed version of this (or any other) manual page, you'll need to use the troff command as well as other printing-related typesetting utilities provided on the system.



Essential System Administration
Essential System Administration, Third Edition
ISBN: 0596003439
EAN: 2147483647
Year: 2002
Pages: 162

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net