docs: improve the wording and conventions in the man-page howto
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
This commit is contained in:
Benno Schulenberg
Karel Zak
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
|
||||
.\" 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 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 textual string of section
|
||||
.\" The header is a textual description of the section:
|
||||
.\" 1 "User Commands"
|
||||
.\" 2 "System calls"
|
||||
.\" 3 "Programmer's Manual"
|
||||
|
|
@ -16,35 +16,36 @@
|
|||
.\" 7 "Miscellanea"
|
||||
.\" 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
|
||||
example \- an util-linux man page howto
|
||||
example \- a 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.
|
||||
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 argument.
|
||||
This option does not use an argument.
|
||||
.TP
|
||||
\fB\-o\fR, \fB\-\-optional\fR[\fI=argument\fR]
|
||||
Tell in description an
|
||||
Tell in this description that the
|
||||
.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
|
||||
is not abbreviated, like in usage function. Assuming usage function would
|
||||
define argument to be
|
||||
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 .
|
||||
.TP
|
||||
\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
|
||||
Tell in description option
|
||||
Tell in this description that the
|
||||
.I argument
|
||||
is required.
|
||||
.TP
|
||||
|
|
@ -52,27 +53,33 @@ is required.
|
|||
Display version information and exit.
|
||||
.TP
|
||||
\fB\-h\fR, \fB\-\-help\fR
|
||||
Display help and exit.
|
||||
Display help text and exit.
|
||||
.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.
|
||||
.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
|
||||
Do not leave empty lines to groff input. If you need break or paragraph use
|
||||
appropriate groff macros. See
|
||||
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
|
||||
Use of
|
||||
The use cases of
|
||||
.I italic
|
||||
which is underlined in terminal, and
|
||||
(which is underlined on a terminal) and
|
||||
.B bold
|
||||
are not strictly defined. As some sort of convention
|
||||
.I arguments
|
||||
use italic, and the
|
||||
.B other highlights
|
||||
are 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
|
||||
|
|
@ -80,37 +87,39 @@ are bold.
|
|||
.\"
|
||||
.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.
|
||||
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, to execution of the command.
|
||||
Tell which environment variables affect, and how, the 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.
|
||||
Configuration file path. Notice that well-known environment variables, such as
|
||||
.BR HOME ,
|
||||
do not need explanation.
|
||||
.SH FILES
|
||||
Tell which file(s) command uses.
|
||||
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, 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
|
||||
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 bellow examples are stupid,
|
||||
and you should never write them to real man page.
|
||||
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.
|
||||
|
|
@ -118,7 +127,7 @@ Output help screen.
|
|||
.B example -V
|
||||
Output version information.
|
||||
.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
|
||||
for success and
|
||||
.B 1
|
||||
|
|
|
|||
Loading…
Reference in New Issue