sample - An annotated example of manual page layout for commands and calls.

NAME

The name, or list of names, by which the command is called, followed by a dash and then a one-line summary of the action performed. This line is used to generate the whatis (1) database.

SYNOPSIS

Commands:

The syntax of the command and its arguments, as typed on the command line.  Boldface words are literals which must by typed exactly as printed.  Words in italics or underlined describe values which you must supply.  References to bold or italicized items are not capitalized in other sections, even when they begin a sentence.
Syntactic symbols appear in roman face:

[ ]

An argument, when surrounded by brackets is optional.

|

Arguments separated by a vertical bar are exclusive.

You can supply only one item from such a list.

...

Arguments followed by an ellipsis can be repeated. When an ellipsis follows a bracketed set, the expression within the brackets can be repeated.

Functions:

If required, the data declaration, or #include directive, is shown first, followed by the function declaration.  If libraries are required, they may also be listed.  Otherwise, just the function declaration is shown.

DESCRIPTION

A narrative overview of the command or function's external behavior. This includes how it interacts with files or data, and how it handles the standard input, standard output and standard error. Internals and implementation details are normally omitted. This section attempts to provide a succinct overview in answer to the question, "what does it do?"

Literal text from the synopsis appears in boldface, as do literal filenames and references to items that appear elsewhere in the page. Arguments are italicized or underlined.

This part can sometimes get extremely technical and in some sections assumes a strong familiarity with the operating system or software package being discussed.  Thus, if you find parts you don't understand just skim past them until you find something useful.

OPTIONS

A list of the command line options and arguments which may be used to alter the behavior of the command.  This is the most frequently useful section of the manual page.  Refer to the synopsis for the exact syntax for using options.  Look for whether an option must be preceded by a dash, whether some options can be grouped together after one dash, whether an option has an agrument and if so whether there must be a space between the argument and the option name.

USAGE

If a command has an interactive interface or interprets an input grammar, details of its use are described in this section. 

DIAGNOSTICS

Also known as ERRORS, this explains what happens when something goes wrong and often gives valuable ideas for fixing them.  If you can't get a program to work, this is the first place to look.  Note that it usually appears very near the end of the manual page and thus is often overlooked by those who get frustrated with the DESCRIPTION part.

FILES

A list of files associated with the command or function.  This is a good section to look at to see what kind of external effects the command might have or to find resource files which you might use to alter its behavior.

SEE ALSO

This is the most important section of any manual page, especially for begining users.  It is a comma-separated list of related manual pages, followed by references to other published materials.  If a keyword search (using man -k keyword) doesn't turn up the page you want, look in the SEE ALSO sections of some of the pages that are returned.  They are likely to lead you to the right place or at least give you some ideas for better keywords to try.  This is nearly the last part of the page but it is essential that you do not overlook it.

BUGS

A description of limitations, known defects, and possible problems associated with the command or function.  It's a good idea to read this before you try to use the command.