.\" This is an util-linux manual page example in troff format.
.\"
.\" .TH macro is expecting following arguments:
.\" title section date footer header
.\" The title is usually command name.
.\" The section must match with file name extension.
.\" The date tells month and year when last update happen.
.\" The footer is fixed to "util-linux".
.\" The header is textual string of section
.\" 1 "User Commands"
.\" 2 "System calls"
.\" 3 "Programmer's Manual"
.\" 4 "Special Files"
.\" 5 "File Formats"
.\" 6 "Games"
.\" 7 "Miscellanea"
.\" 8 "System Administration"
.\"
.\" Please read `man 7 groff_man' howto use various macros.
.\"
.TH EXAMPLE "1" "August 2011" "util-linux" "User Commands"
.SH NAME
example \- an util-linux man page howto
.SH SYNOPSIS
.B example
[options]
.I argument
.SH DESCRIPTION
All manual pages need some sort of description. Write such here.
.SH OPTIONS
.TP
\fB\-n\fR, \fB\-\-no\-argument\fR
This option does not use argument.
.TP
\fB\-o\fR, \fB\-\-optional\fR[\fI=argument\fR]
Tell in description an
.I argument
is optional, and what happens when is or is not given. Notice that
.I argument
is not abbreviated, like in usage function. Assuming usage function would
define argument to be
.IR num ,
the manual page should say
.IR number .
.TP
\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
Tell in description option
.I argument
is required.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version information and exit.
.TP
\fB\-h\fR, \fB\-\-help\fR
Display help and exit.
.SH NOTES
Tell details what users might need to know. For example kernel feature or
version requirements.
.PP
The man page groff input lines should not exceed 80 characters length.
.PP
Do not leave empty lines to groff input. If you need break or paragraph use
appropriate groff macros. See
.BR groff_man (7)
how to use man page macros.
.PP
Use of
.I italic
which is underlined in terminal, and
.B bold
are not strictly defined. As some sort of convention
.I arguments
use italic, and the
.B other highlights
are bold.
.\"
.\" The manual page comments are undervalued way of adding clarifications
.\" quite not belong to the manual, questions, TODO items etc. Feel free
.\" to use them.
.\"
.PP
When in the source a new sentence begins somewhere midline, it should use a
double space before its initial letter. This is done because groff uses double
spaces last sentence ends to end of line, and next begins from new line.
Unless double spaces are used in middle of of line the spacing style is
inconsistent.
.SH ENVIRONMENT
Tell which environment variables affect, and how, to execution of the command.
.TP
.B EXAMPLE_PATH
Configuration file path. Notice that a well-known environment variables such as
.B HOME
does not need explanation.
.SH FILES
Tell which file(s) command uses.
.TP
.B $EXAMPLE_PATH
.TQ
.B $HOME/.example.conf
.TQ
.B /etc/example.conf
What are these files, which order and will the evaluation end or continue if a
file is found. In case the explanation is not simple write separated Special
Files manual page that tells about syntax, meaning of key-value settings etc.
The file manual page needs to be referred in
.B SEE ALSO
section.
.TP
.B /var/log/example.log
Another file.
.SH EXAMPLES
Write typical and/or clever use examples here. The bellow examples are stupid,
and you should never write them to real man page.
.TP
.B example -h
Output help screen.
.TP
.B example -V
Output version information.
.SH "EXIT STATUS"
This section can be removed if command has only two return values,
.B 0
for success and
.B 1
for failure. Use of
.B sysexits.h
return values must be mentioned, but does not need to be explained.
.PP
.RS
.PD 0
.TP
.B 0
success
.TP
.B 1
failure
.TP
.B 2
tell why this could happen
.TP
.B 3
etc
.PD
.RE
.SH AUTHORS
.MT rjh@\:example.org
Random J. Hacker
.ME
.br
.MT fred@\:example.com
Fred Foobar
.ME
.SH "SEE ALSO"
.BR groff_man (7),
.BR foo (1),
.BR bar (8)
.SH AVAILABILITY
The example command is part of the util-linux package and is available from
.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
Linux Kernel Archive
.UE .
