dmesg: add --follow-new

[thirdparty/util-linux.git] / Documentation / howto-man-page.txt

.\" 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 .