2011-08-12 14:23:58 -05:00
|
|
|
.\" 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
|
2014-06-25 06:21:15 -05:00
|
|
|
\fB\-o\fR, \fB\-\-optional\fR[\fI=argument\fR]
|
2011-08-12 14:23:58 -05:00
|
|
|
Tell in description an
|
|
|
|
.I argument
|
|
|
|
is optional, and what happens when is or is not given. Notice that
|
|
|
|
.I argument
|
2012-02-21 14:19:25 -06:00
|
|
|
is not abbreviated, like in usage function. Assuming usage function would
|
2011-08-12 14:23:58 -05:00
|
|
|
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
|
2012-02-21 14:19:25 -06:00
|
|
|
inconsistent.
|
2011-08-12 14:23:58 -05:00
|
|
|
.SH ENVIRONMENT
|
|
|
|
Tell which environment variables affect, and how, to execution of the command.
|
|
|
|
.TP
|
|
|
|
.B EXAMPLE_PATH
|
2012-02-21 14:19:25 -06:00
|
|
|
Configuration file path. Notice that a well-known environment variables such as
|
2011-08-12 14:23:58 -05:00
|
|
|
.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
|
2012-05-30 12:49:37 -05:00
|
|
|
.MT rjh@\:example.org
|
2011-08-12 14:23:58 -05:00
|
|
|
Random J. Hacker
|
2012-05-30 12:49:37 -05:00
|
|
|
.ME
|
2011-08-12 14:23:58 -05:00
|
|
|
.br
|
2012-05-30 12:49:37 -05:00
|
|
|
.MT fred@\:example.com
|
2011-08-12 14:23:58 -05:00
|
|
|
Fred Foobar
|
2012-05-30 12:49:37 -05:00
|
|
|
.ME
|
2011-08-12 14:23:58 -05:00
|
|
|
.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 .
|