189 lines
4.8 KiB
Plaintext
189 lines
4.8 KiB
Plaintext
.\" 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" "April 2016" "util-linux" "User Commands"
|
|
.SH NAME
|
|
example \- a util-linux man-page howto
|
|
.SH SYNOPSIS
|
|
.B example
|
|
[options]
|
|
.I argument
|
|
.SH DESCRIPTION
|
|
Each manual page needs some sort of description of the command.
|
|
Write such here.
|
|
.SH OPTIONS
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-no\-argument\fR
|
|
This option does not use an argument.
|
|
.TP
|
|
\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 .
|
|
.IP
|
|
Notice that after release v2.28 it was decided that introducing new options
|
|
taking optional arguments should be limited to long-only options. This is
|
|
done primarily to avoid problematic behaviour of short options. Imagine for
|
|
example normal option
|
|
.B \-n
|
|
and optional option
|
|
.BR \-o .
|
|
One will expect
|
|
.B command \ \-no
|
|
and
|
|
.B command \ \-on
|
|
to be the same, but in fact the former is two separate options while the
|
|
later will use
|
|
.B n
|
|
as option argument of
|
|
.BR -o .
|
|
So it is best to avoid short forms of optional options altogether.
|
|
.TP
|
|
\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
|
|
Tell in this description that the
|
|
.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 text and exit.
|
|
.SH NOTES
|
|
Tell details that users might need to know. For example, kernel feature or
|
|
version requirements.
|
|
.PP
|
|
The man-page source lines should not exceed 80 characters in length.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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
|
|
and
|
|
.B literal arguments
|
|
use bold, and
|
|
.I other highlights
|
|
use
|
|
.B either
|
|
one.
|
|
.\"
|
|
.\" 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 \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.
|
|
.SH ENVIRONMENT
|
|
Tell which environment variables affect, and how, the execution of the command.
|
|
.TP
|
|
.B EXAMPLE_PATH
|
|
Configuration file path. Notice that well-known environment variables, such as
|
|
.BR HOME ,
|
|
do not need explanation.
|
|
.SH FILES
|
|
Tell which file(s) the command uses.
|
|
.TP
|
|
.B $EXAMPLE_PATH
|
|
.TQ
|
|
.B $HOME/.example.conf
|
|
.TQ
|
|
.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 SEE ALSO
|
|
section.
|
|
.TP
|
|
.B /var/log/example.log
|
|
Another file.
|
|
.SH EXAMPLES
|
|
Write typical and/or clever use examples here. The below examples are stupid,
|
|
and you should never write them in a real man page.
|
|
.TP
|
|
.B example -h
|
|
Output help screen.
|
|
.TP
|
|
.B example -V
|
|
Output version information.
|
|
.SH "EXIT STATUS"
|
|
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.
|
|
.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 https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
|
|
Linux Kernel Archive
|
|
.UE .
|