1 .\" This is a util-linux manual page example in troff format.
3 .\" The .TH macro expects the following arguments:
4 .\" title section date footer header
5 .\" The title is usually the command name.
6 .\" The section must match the filename extension.
7 .\" The date is the month and year when the last update happened.
8 .\" The footer is fixed to "util-linux".
9 .\" The header is a textual description of the section:
12 .\" 3 "Programmer's Manual"
17 .\" 8 "System Administration"
19 .\" Please read `man 7 groff_man' to see how to use the various macros.
21 .TH EXAMPLE "1" "April 2016" "util-linux" "User Commands"
23 example \- a util-linux man-page howto
29 Each manual page needs some sort of description of the command.
33 \fB\-n\fR, \fB\-\-no\-argument\fR
34 This option does not use an argument.
36 \fB\-\-optional\fR[\fI=argument\fR]
37 Tell in this description that the
39 is optional, and what happens when it is or is not given. Notice that the word
41 is not abbreviated as is customary in the usage text. For example, when the
42 usage text uses the argument
44 the manual page should say
47 Notice that after release v2.28 it was decided that introducing new options
48 taking optional arguments should be limited to long-only options. This is
49 done primarily to avoid problematic behaviour of short options. Imagine for
58 to be the same, but in fact the former is two separate options while the
63 So it is best to avoid short forms of optional options altogether.
65 \fB\-r\fR, \fB\-\-required\fR \fIargument\fR
66 Tell in this description that the
70 \fB\-V\fR, \fB\-\-version\fR
71 Display version information and exit.
73 \fB\-h\fR, \fB\-\-help\fR
74 Display help text and exit.
76 Tell details that users might need to know. For example, kernel feature or
79 The man-page source lines should not exceed 80 characters in length.
81 Do not leave empty lines in the groff input. If you need a break or a new
82 paragraph, use the appropriate groff macros. See
84 how to use man page macros.
88 (which is underlined on a terminal) and
90 are not strictly defined. The main convention is that
102 .\" The manual page comments are undervalued way of adding clarifications
103 .\" quite not belong to the manual, questions, TODO items etc. Feel free
107 When in the source a new sentence begins somewhere midline, it should use a
108 double space before its initial letter. This is done because \fBgroff\fR
109 uses a double space after a sentence when this sentence ends at the end of
110 an input line and the next sentence begins on the next line.
111 Unless a double space is used before other sentence starts as well, the
112 spacing style will be inconsistent.
114 Tell which environment variables affect, and how, the execution of the command.
117 Configuration file path. Notice that well-known environment variables, such as
119 do not need explanation.
121 Tell which file(s) the command uses.
125 .B $HOME/.example.conf
128 What are these files, in which order are they read, and will the evaluation
129 end or continue if one of them is found.
130 In case the explanation is not simple, write a separate "Special Files"
131 manual page that tells about syntax, meaning of key-value settings, etc.
132 This "Special Files" manual page then needs to be referred in the
136 .B /var/log/example.log
139 Write typical and/or clever use examples here. The below examples are stupid,
140 and you should never write them in a real man page.
146 Output version information.
148 This section can be left out if the command has only two return values,
154 return values must be mentioned, but does not need to be explained.
166 tell why this could happen
173 .MT rjh@\:example.org
177 .MT fred@\:example.com
185 The example command is part of the util-linux package and is available from
186 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/