Creating Man Pages

Creating your own man page

This is simply a little tutorial for fun. :) You will finally have your name up their with 'find', 'sed' and 'hey'!

The nroff -man Command

The nroff command is an emulator and by giving the -man option, it outputs the file in a manual page style. This prints everything out, so it is best to catch the output and pipe it into 'more' like so:

nroff -man ~art_wolf/art_wolf.8 | more

It is the nroff syntax we will be looking at and how to make the output resemble a man page.

Nroff's Syntax

nroff has several settings and we will be using most of them to achive our look. Here are the main ones:

Request	Cause Break	Explanation
.B t	no	Text t is bold. Quote to imbed blanks.
.I t	no	Text t is italic. Quote to imbed blanks.
.TP x	yes	Set prevailing indent to 5. Begin indented paragraph with hanging tag given by first argument. Tag x is always placed on a separate line.
.LP	yes	Same as .PP.
.PP	yes	Begin paragraph. Set prevailing indent to 5.
.RE	yes	End of relative indent. Set prevailing indent to amount of starting .RS.
.RS	yes	Start relative indent, move left margin in distance 5.
.SH t	yes	Subhead. Quote to imbed blanks.
.SS t	yes	Subsection. Quote to imbed blanks. No indent for t.
.TH n s c v d	yes	Begin page named n of chapter s; c is the chapter name; d is the date of the most recent change; v is version number. Sets prevailing indent and tabs to 5.

A man-ly example

Read a sample man page here. Save this to your home directory and rename it 'username.8' and modify it to your hearts content :)

.TH USERNAME 1 This is part of a normal man page layout which prints USERNAME(1) at the corners of the man page.

.SH SECTION This sets a head section..surprise surprise.. used like this:

SYNOPSIS sample [options]

.SH SYNOPSIS sample [options]

.TP 5 This gives a break and is used between options to seperate them.

.B sample This sets everything on the line to bold. If there are spaces in the word everything must be enclosed with quotes.

Headings used in a man page

A quick google and here are the main headings used in man pages - now its time for you to try your own. :)

• NAME - This should be the product name followed by a short description. The text on this line is also used as the keyword list for man -k and apropos.

• SYNOPSIS or SYNTAX - Document here the complete syntax of the command used to invoke the product.

• AVAILABILITY - Document here the OS flavours for which the program is available.

• DESCRIPTION - Document here a full but succinct description of the use of the product.

• OPTIONS - Document here all the options available for the invoking command.

• EXAMPLES - Document here situations in which the program can be used, if there are uses that are not obvious.

• NOTES - Document here any information the user should be aware of when using the command.

• MESSAGES AND EXIT CALLS - Document here all errors and other messages returned to the user. Include the cause and the recovery actions whenever appropriate and possible.

• AUTHOR - Document here the product coordinator and/or the major developers and contributors, along with their particular areas of expertise, as appropriate.

• HISTORY - Document here the significant changes in each release of the product.

• RESOURCES - If your product is designed to work under X windows, document here any X resources that affect the product's behaviour.

• FILES - Document here all files, or at least their directories if there are too many files. Also mention here any files in the user's home area that are needed/accessed (e.g., $HOME/.mh_profile, $HOME/Mail/components for the mh and exmh products).

• BUGS - Document here things that do not (yet!) work as designed. Provide work-arounds whenever possible.

• CAVEATS - Document here things that work as designed but which may be unclear or surprising to the user. (This is the System V replacement for the BUGS category; you too can pretend your product has no bugs!).

• SEE ALSO - Document here other related commands and manual sections, especially if not obvious.