docs: improve the wording and conventions in the man-page howto
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
This commit is contained in:
parent
1000a59543
commit
cfbebb2905
|
@ -1,12 +1,12 @@
|
||||||
.\" This is an util-linux manual page example in troff format.
|
.\" This is a util-linux manual page example in troff format.
|
||||||
.\"
|
.\"
|
||||||
.\" .TH macro is expecting following arguments:
|
.\" The .TH macro expects the following arguments:
|
||||||
.\" title section date footer header
|
.\" title section date footer header
|
||||||
.\" The title is usually command name.
|
.\" The title is usually the command name.
|
||||||
.\" The section must match with file name extension.
|
.\" The section must match the filename extension.
|
||||||
.\" The date tells month and year when last update happen.
|
.\" The date is the month and year when the last update happened.
|
||||||
.\" The footer is fixed to "util-linux".
|
.\" The footer is fixed to "util-linux".
|
||||||
.\" The header is textual string of section
|
.\" The header is a textual description of the section:
|
||||||
.\" 1 "User Commands"
|
.\" 1 "User Commands"
|
||||||
.\" 2 "System calls"
|
.\" 2 "System calls"
|
||||||
.\" 3 "Programmer's Manual"
|
.\" 3 "Programmer's Manual"
|
||||||
|
@ -16,35 +16,36 @@
|
||||||
.\" 7 "Miscellanea"
|
.\" 7 "Miscellanea"
|
||||||
.\" 8 "System Administration"
|
.\" 8 "System Administration"
|
||||||
.\"
|
.\"
|
||||||
.\" Please read `man 7 groff_man' howto use various macros.
|
.\" Please read `man 7 groff_man' to see how to use the various macros.
|
||||||
.\"
|
.\"
|
||||||
.TH EXAMPLE "1" "August 2011" "util-linux" "User Commands"
|
.TH EXAMPLE "1" "July 2014" "util-linux" "User Commands"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
example \- an util-linux man page howto
|
example \- a util-linux man-page howto
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.B example
|
.B example
|
||||||
[options]
|
[options]
|
||||||
.I argument
|
.I argument
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
All manual pages need some sort of description. Write such here.
|
Each manual page needs some sort of description of the command.
|
||||||
|
Write such here.
|
||||||
.SH OPTIONS
|
.SH OPTIONS
|
||||||
.TP
|
.TP
|
||||||
\fB\-n\fR, \fB\-\-no\-argument\fR
|
\fB\-n\fR, \fB\-\-no\-argument\fR
|
||||||
This option does not use argument.
|
This option does not use an argument.
|
||||||
.TP
|
.TP
|
||||||
\fB\-o\fR, \fB\-\-optional\fR[\fI=argument\fR]
|
\fB\-o\fR, \fB\-\-optional\fR[\fI=argument\fR]
|
||||||
Tell in description an
|
Tell in this description that the
|
||||||
.I argument
|
.I argument
|
||||||
is optional, and what happens when is or is not given. Notice that
|
is optional, and what happens when it is or is not given. Notice that the word
|
||||||
.I argument
|
.I argument
|
||||||
is not abbreviated, like in usage function. Assuming usage function would
|
is not abbreviated as is customary in the usage text. For example, when the
|
||||||
define argument to be
|
usage text uses the argument
|
||||||
.IR num ,
|
.IR num ,
|
||||||
the manual page should say
|
the manual page should say
|
||||||
.IR number .
|
.IR number .
|
||||||
.TP
|
.TP
|
||||||
\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
|
\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
|
||||||
Tell in description option
|
Tell in this description that the
|
||||||
.I argument
|
.I argument
|
||||||
is required.
|
is required.
|
||||||
.TP
|
.TP
|
||||||
|
@ -52,27 +53,33 @@ is required.
|
||||||
Display version information and exit.
|
Display version information and exit.
|
||||||
.TP
|
.TP
|
||||||
\fB\-h\fR, \fB\-\-help\fR
|
\fB\-h\fR, \fB\-\-help\fR
|
||||||
Display help and exit.
|
Display help text and exit.
|
||||||
.SH NOTES
|
.SH NOTES
|
||||||
Tell details what users might need to know. For example kernel feature or
|
Tell details that users might need to know. For example, kernel feature or
|
||||||
version requirements.
|
version requirements.
|
||||||
.PP
|
.PP
|
||||||
The man page groff input lines should not exceed 80 characters length.
|
The man-page source lines should not exceed 80 characters in length.
|
||||||
.PP
|
.PP
|
||||||
Do not leave empty lines to groff input. If you need break or paragraph use
|
Do not leave empty lines in the groff input. If you need a break or a new
|
||||||
appropriate groff macros. See
|
paragraph, use the appropriate groff macros. See
|
||||||
.BR groff_man (7)
|
.BR groff_man (7)
|
||||||
how to use man page macros.
|
how to use man page macros.
|
||||||
.PP
|
.PP
|
||||||
Use of
|
The use cases of
|
||||||
.I italic
|
.I italic
|
||||||
which is underlined in terminal, and
|
(which is underlined on a terminal) and
|
||||||
.B bold
|
.B bold
|
||||||
are not strictly defined. As some sort of convention
|
are not strictly defined. The main convention is that
|
||||||
.I arguments
|
.I symbolic arguments
|
||||||
use italic, and the
|
use italic, and
|
||||||
.B other highlights
|
.B commands
|
||||||
are bold.
|
and
|
||||||
|
.B literal arguments
|
||||||
|
use bold, and
|
||||||
|
.I other highlights
|
||||||
|
use
|
||||||
|
.B either
|
||||||
|
one.
|
||||||
.\"
|
.\"
|
||||||
.\" The manual page comments are undervalued way of adding clarifications
|
.\" The manual page comments are undervalued way of adding clarifications
|
||||||
.\" quite not belong to the manual, questions, TODO items etc. Feel free
|
.\" quite not belong to the manual, questions, TODO items etc. Feel free
|
||||||
|
@ -80,37 +87,39 @@ are bold.
|
||||||
.\"
|
.\"
|
||||||
.PP
|
.PP
|
||||||
When in the source a new sentence begins somewhere midline, it should use a
|
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
|
double space before its initial letter. This is done because \fBgroff\fR
|
||||||
spaces last sentence ends to end of line, and next begins from new line.
|
uses a double space after a sentence when this sentence ends at the end of
|
||||||
Unless double spaces are used in middle of of line the spacing style is
|
an input line and the next sentence begins on the next line.
|
||||||
inconsistent.
|
Unless a double space is used before other sentence starts as well, the
|
||||||
|
spacing style will be inconsistent.
|
||||||
.SH ENVIRONMENT
|
.SH ENVIRONMENT
|
||||||
Tell which environment variables affect, and how, to execution of the command.
|
Tell which environment variables affect, and how, the execution of the command.
|
||||||
.TP
|
.TP
|
||||||
.B EXAMPLE_PATH
|
.B EXAMPLE_PATH
|
||||||
Configuration file path. Notice that a well-known environment variables such as
|
Configuration file path. Notice that well-known environment variables, such as
|
||||||
.B HOME
|
.BR HOME ,
|
||||||
does not need explanation.
|
do not need explanation.
|
||||||
.SH FILES
|
.SH FILES
|
||||||
Tell which file(s) command uses.
|
Tell which file(s) the command uses.
|
||||||
.TP
|
.TP
|
||||||
.B $EXAMPLE_PATH
|
.B $EXAMPLE_PATH
|
||||||
.TQ
|
.TQ
|
||||||
.B $HOME/.example.conf
|
.B $HOME/.example.conf
|
||||||
.TQ
|
.TQ
|
||||||
.B /etc/example.conf
|
.B /etc/example.conf
|
||||||
What are these files, which order and will the evaluation end or continue if a
|
What are these files, in which order are they read, and will the evaluation
|
||||||
file is found. In case the explanation is not simple write separated Special
|
end or continue if one of them is found.
|
||||||
Files manual page that tells about syntax, meaning of key-value settings etc.
|
In case the explanation is not simple, write a separate "Special Files"
|
||||||
The file manual page needs to be referred in
|
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
|
.B SEE ALSO
|
||||||
section.
|
section.
|
||||||
.TP
|
.TP
|
||||||
.B /var/log/example.log
|
.B /var/log/example.log
|
||||||
Another file.
|
Another file.
|
||||||
.SH EXAMPLES
|
.SH EXAMPLES
|
||||||
Write typical and/or clever use examples here. The bellow examples are stupid,
|
Write typical and/or clever use examples here. The below examples are stupid,
|
||||||
and you should never write them to real man page.
|
and you should never write them in a real man page.
|
||||||
.TP
|
.TP
|
||||||
.B example -h
|
.B example -h
|
||||||
Output help screen.
|
Output help screen.
|
||||||
|
@ -118,7 +127,7 @@ Output help screen.
|
||||||
.B example -V
|
.B example -V
|
||||||
Output version information.
|
Output version information.
|
||||||
.SH "EXIT STATUS"
|
.SH "EXIT STATUS"
|
||||||
This section can be removed if command has only two return values,
|
This section can be left out if the command has only two return values,
|
||||||
.B 0
|
.B 0
|
||||||
for success and
|
for success and
|
||||||
.B 1
|
.B 1
|
||||||
|
|
Loading…
Reference in New Issue