Creating Man Pages

Creating your own man page

[ Author : John Doyle (art_wolf) : 2005 ]

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    Explanation
                   Break?

    .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 flavors 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 behavior.

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!)