          &manemail;

&manfirstname; &mansurname;
2002
&manusername;
&mandate;
&manucpackage;

&mansection;

# &manpackage;

program to do something

          &manpackage;

          thisthat
          -flags

           -o option

          argument
          more

## DESCRIPTION

Long drawn-out discussion of `&manpackage;`. It's a good idea to break this up into subsections, like these:

### A Sample Subsection

### Yet Another Sample Subsection

References to the foo SECTION (or other) manual page should use the <citerefentry> element as here.

Each paragraph within a section is contained within a <para> tag.

## OPTIONS

Some people make this separate from the description.

`this`|`that`

  The user MUST specify either `this` or `that` to run the program. The { and } braces mean one of the enclosed is required. The bar (|) separates exclusive options (i.e. you cannot have both at once.)

`-o`

  Pass the user-supplied option to `foo` to change its behaviour. The fact that option is underlined or in italics means that the user replaces it with a valid value for this option. The [ and ] brackets mean it isn't required.

`argument`

  The last `argument` is required, because it is not in brackets.

`more`

  means that the user can optionally specify additional arguments at the end. The ellipses (...) indicate one or more of this parameter is allowed.

## RETURN VALUE

What the program or function returns if successful.

## ERRORS

Return codes, either exit status or errno settings.

## EXAMPLES

Give some example uses of the program.

## ENVIRONMENT

Environment variables this program might care about.

## FILES

All files used by the program. Typical usage is like this:

`/usr/man`

  default man tree

`/usr/man/man*/*.*`

  unformatted (nroff source) man pages

## NOTES

Miscellaneous commentary.

## CAVEATS

Things to take special care with, sometimes called WARNINGS.

## DIAGNOSTICS

All the possible error messages the program can print out, what they mean, and how to correct them if applicable.

## BUGS

Things that are broken or just don't work quite right.

## RESTRICTIONS

Bugs you don't plan to fix. :-)

## AUTHOR

Who wrote it (or AUTHORS if multiple).

## HISTORY

Programs derived from other sources sometimes have this.

## SEE ALSO

Other man pages to check out, like man(1), man(7), mandb(8), catman(8).