blob: ee3cb4e2fe0d83bbfe8692e59c2930c965770593 [file] [log] [blame]
.\" This is a util-linux manual page example in troff format.
.\" The .TH macro expects the following arguments:
.\" title section date footer header
.\" The title is usually the command name.
.\" The section must match the filename extension.
.\" The date is the month and year when the last update happened.
.\" The footer is fixed to "util-linux".
.\" The header is a textual description of the 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' to see how to use the various macros.
.TH EXAMPLE "1" "July 2014" "util-linux" "User Commands"
example \- a util-linux man-page howto
.B example
.I argument
Each manual page needs some sort of description of the command.
Write such here.
\fB\-n\fR, \fB\-\-no\-argument\fR
This option does not use an argument.
\fB\-o\fR, \fB\-\-optional\fR[\fI=argument\fR]
Tell in this description that the
.I argument
is optional, and what happens when it is or is not given. Notice that the word
.I argument
is not abbreviated as is customary in the usage text. For example, when the
usage text uses the argument
.IR num ,
the manual page should say
.IR number .
\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
Tell in this description that the
.I argument
is required.
\fB\-V\fR, \fB\-\-version\fR
Display version information and exit.
\fB\-h\fR, \fB\-\-help\fR
Display help text and exit.
Tell details that users might need to know. For example, kernel feature or
version requirements.
The man-page source lines should not exceed 80 characters in length.
Do not leave empty lines in the groff input. If you need a break or a new
paragraph, use the appropriate groff macros. See
.BR groff_man (7)
how to use man page macros.
The use cases of
.I italic
(which is underlined on a terminal) and
.B bold
are not strictly defined. The main convention is that
.I symbolic arguments
use italic, and
.B commands
.B literal arguments
use bold, and
.I other highlights
.B either
.\" 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.
When in the source a new sentence begins somewhere midline, it should use a
double space before its initial letter. This is done because \fBgroff\fR
uses a double space after a sentence when this sentence ends at the end of
an input line and the next sentence begins on the next line.
Unless a double space is used before other sentence starts as well, the
spacing style will be inconsistent.
Tell which environment variables affect, and how, the execution of the command.
Configuration file path. Notice that well-known environment variables, such as
do not need explanation.
Tell which file(s) the command uses.
.B $HOME/.example.conf
.B /etc/example.conf
What are these files, in which order are they read, and will the evaluation
end or continue if one of them is found.
In case the explanation is not simple, write a separate "Special Files"
manual page that tells about syntax, meaning of key-value settings, etc.
This "Special Files" manual page then needs to be referred in the
.B /var/log/example.log
Another file.
Write typical and/or clever use examples here. The below examples are stupid,
and you should never write them in a real man page.
.B example -h
Output help screen.
.B example -V
Output version information.
This section can be left out if the 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.
.PD 0
.B 0
.B 1
.B 2
tell why this could happen
.B 3
.MT rjh@\
Random J. Hacker
.MT fred@\
Fred Foobar
.BR groff_man (7),
.BR foo (1),
.BR bar (8)
The example command is part of the util-linux package and is available from
.UR ftp://\\:/pub\:/linux\:/utils\:/util-linux/
Linux Kernel Archive
.UE .