Help--Online Documentation, etc.
If you're not satisfied with the simple manual pages we discussed in article
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
So here's a sample for you to copy.
discuss it blow by blow, I'll include lots of comments (these start with
.\" Title: Program name, manual section, and date
.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.
.\"grind \- create output from input
.\" Section heading: SYNOPSIS, followed by syntax summary
.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
.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
.\" The .TP macro precedes each option
.B \-b \" print the -b option in bold.
Print output in binary.
.B \-c \" \- requests a minus sign, which is preferable to a hyphen (-)
Eliminate ASCII characters from input before processing.
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.
temporary file (typically 100 Megabytes)
In order to optimize computational speed, this program always produces
the same result, independent of the input.
.\" Use .LP between paragraphs
If the moon is full,
may destroy your input file. To say nothing of your sex life.
.\" Good manual pages end by stating who wrote the program.
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 50.2
, to know about.
Table 50.2: Important -man Macros
||Title of the manual page.
||Section heading; one for each section.
||Formats options correctly (sets up the "hanging indent").
||Used between paragraphs in a section.
For some arcane reason, all manual pages use the silly
, etc., macros to make font changes.
I've adhered to this
style in the example, but it's much easier to use "in line" font
There may be some systems on which this doesn't work properly, but I've
never seen any.