## 3.22. Writing a Simple Manpage with the -man Macros

If you're not satisfied with the simple manual pages we discussed in Section 3.21, here's how to go all the way and create a "real" manual page. As we said, the best way to create a manual page is to copy one that already exists. So here's a sample for you to copy. Rather than discuss it blow by blow, I'll include lots of comments (these start with `.\"` or `\"`).

>     .\" Title: Program name, manual section, and date

`1` Section 2.1

>     .TH GRIND 1
>     .\" Section heading: NAME, followed by command name and one line summary
>     .\" It's important to copy this exactly; the "whatis" database (used
>     .\" for apropos) looks for the summary line.
>     .SH NAME
>     grind \- create output from input
>     .\" Section heading: SYNOPSIS, followed by syntax summary
>     .SH SYNOPSIS
>     .B grind              \" .B: bold font; use it for the command name.
>     [ -b ] [ -c ] [ -d ]  \" Put optional arguments in square brackets.
>     [ input [ output ]]   \" Arguments can be spread across several lines.
>     .br                   \" End the synopsis with an explicit line break (.br)
>     .\" A new section: DESCRIPTION, followed by what the command does
>     .SH DESCRIPTION
>     .I Grind       \" .I:  Italic font for the word "Grind"
>     performs lots of computations. Input to
>     .IR grind ,    \" .IR: One word italic, next word roman, no space between.
>     is taken from the file
>     .IR input ,
>     and output is sent to the file
>     .IR output ,
>     which default to standard input and standard output if not specified.
>     .\" Another section: now we're going to discuss the -b, -c, and -d options
>     .SH OPTIONS
>     .\" The .TP macro precedes each option
>     .TP
>     .B \-b  \" print the -b option in bold.
>     Print output in binary.
>     .TP
>     .B \-c  \" \- requests a minus sign, which is preferable to a hyphen (-)
>     Eliminate ASCII characters from input before processing.
>     .TP
>     .B \-d
>     Cause daemons to overrun your computer.
>     .\" OK, we're done with the description and the options; now mention
>     .\" other requirements (like environment and files needed) as well as
>     .\" what can go wrong. You can add any other sections you want.
>     .SH FILES
>     .PD 0
>     .TP 20
>     .B /dev/null
>     data file
>     .TP
>     .B /tmp/grind*
>     temporary file (typically 314.159 Gigabytes)
>     .PD
>     .SH BUGS
>     In order to optimize computational speed, this program always produces
>     the same result, independent of the input.
>     .\" Use .LP between paragraphs
>     .LP
>     If the moon is full,
>     .I grind
>     may destroy your input file. To say nothing of your sex life.
>     .\" Good manual pages end by stating who wrote the program.
>     .SH AUTHOR
>     I wouldn't admit to this hack if my life depended on it.

After all that, you should have noticed that there are four important macros (listed in Table 3-1) to know about.

#### Table 3-1. Important -man macros

Macro | Meaning
--- | ---
.TH | Title of the manual page.
.SH | Section heading; one for each section.
.TP | Formats options correctly (sets up the "hanging indent").
.LP | Used between paragraphs in a section.

For some arcane reason, all manual pages use the silly `.B`, `.BI`, etc. macros to make font changes. I've adhered to this style in the example, but it's much easier to use inline font changes: `\fI` for italic, `\fB` for bold, and `\fR` for roman. There may be some systems on which this doesn't work properly, but I've never seen any.

--ML and SJC

Copyright © 2003 O'Reilly & Associates. All rights reserved.