Hack 90 Create Your Own Manpages


figs/moderate.gif figs/hack90.gif

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.

Table 9-1. groff commands

Command

Usage

.\"

A comment

.TH

The title

.SH NAME

The only required section


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 admin@mycompany.com 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 (dlavigne6@sympatico.ca)

If you wish, compress your manpage with gzip /usr/local/man/man1/boss.1.


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

  • man manpath

  • man 7 groff (the groff formatting commands look for the Request Short Reference section)

  • man 7 mdoc (a mini-tutorial that includes a template for creating manpages)



BSD Hacks
BSD Hacks
ISBN: 0596006799
EAN: 2147483647
Year: 2006
Pages: 160
Authors: Lavigne

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