docs: update Documentation/howto-man-page.txt
Signed-off-by: Karel Zak <kzak@redhat.com>
This commit is contained in:
parent
97c5380f9c
commit
6a23bf93fd
|
@ -1,196 +1,2 @@
|
|||
.\" 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
|
||||
.BR \-n ,\ \-\-no\-argument
|
||||
.\" \fB\-n\fR, \fB\-\-no\-argument\fR
|
||||
This option does not use an argument.
|
||||
.TP
|
||||
.BR \-\-optional [ =\c
|
||||
.IR argument ]
|
||||
.\" \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
|
||||
.BR \-r ,\ \-\-required\ \c
|
||||
.I argument
|
||||
.\"\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
|
||||
Tell in this description that the
|
||||
.I argument
|
||||
is required.
|
||||
.TP
|
||||
.BR \-V ", " \-\-version
|
||||
.\"\fB\-V\fR, \fB\-\-version\fR
|
||||
Display version information and exit.
|
||||
.TP
|
||||
.BR \-h ,\ \-\-help
|
||||
.\"\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
|
||||
.B groff
|
||||
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 .
|
||||
Since v2.37 util-linux project uses asciidoc format to maintain man pages.
|
||||
See man-common/manpage-stub.adoc for more details.
|
||||
|
|
Loading…
Reference in New Issue