]>
Commit | Line | Data |
---|---|---|
cfbebb29 | 1 | .\" This is a util-linux manual page example in troff format. |
05620dd4 | 2 | .\" |
cfbebb29 | 3 | .\" The .TH macro expects the following arguments: |
05620dd4 | 4 | .\" title section date footer header |
cfbebb29 BS |
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. | |
05620dd4 | 8 | .\" The footer is fixed to "util-linux". |
cfbebb29 | 9 | .\" The header is a textual description of the section: |
05620dd4 SK |
10 | .\" 1 "User Commands" |
11 | .\" 2 "System calls" | |
12 | .\" 3 "Programmer's Manual" | |
13 | .\" 4 "Special Files" | |
14 | .\" 5 "File Formats" | |
15 | .\" 6 "Games" | |
16 | .\" 7 "Miscellanea" | |
17 | .\" 8 "System Administration" | |
18 | .\" | |
cfbebb29 | 19 | .\" Please read `man 7 groff_man' to see how to use the various macros. |
05620dd4 | 20 | .\" |
326c5c93 | 21 | .TH EXAMPLE "1" "April 2016" "util-linux" "User Commands" |
05620dd4 | 22 | .SH NAME |
cfbebb29 | 23 | example \- a util-linux man-page howto |
05620dd4 SK |
24 | .SH SYNOPSIS |
25 | .B example | |
26 | [options] | |
27 | .I argument | |
28 | .SH DESCRIPTION | |
cfbebb29 BS |
29 | Each manual page needs some sort of description of the command. |
30 | Write such here. | |
05620dd4 SK |
31 | .SH OPTIONS |
32 | .TP | |
33 | \fB\-n\fR, \fB\-\-no\-argument\fR | |
cfbebb29 | 34 | This option does not use an argument. |
05620dd4 | 35 | .TP |
326c5c93 | 36 | \fB\-\-optional\fR[\fI=argument\fR] |
cfbebb29 | 37 | Tell in this description that the |
05620dd4 | 38 | .I argument |
cfbebb29 | 39 | is optional, and what happens when it is or is not given. Notice that the word |
05620dd4 | 40 | .I argument |
cfbebb29 BS |
41 | is not abbreviated as is customary in the usage text. For example, when the |
42 | usage text uses the argument | |
05620dd4 SK |
43 | .IR num , |
44 | the manual page should say | |
45 | .IR number . | |
326c5c93 SK |
46 | .IP |
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 | |
50 | example normal option | |
51 | .B \-n | |
52 | and optional option | |
53 | .BR \-o . | |
54 | One will expect | |
55 | .B command \ \-no | |
56 | and | |
57 | .B command \ \-on | |
58 | to be the same, but in fact the former is two separate options while the | |
59 | later will use | |
60 | .B n | |
61 | as option argument of | |
62 | .BR -o . | |
63 | So it is best to avoid short forms of optional options altogether. | |
05620dd4 SK |
64 | .TP |
65 | \fB\-r\fR, \fB\-\-required\fR \fIargument\fR | |
cfbebb29 | 66 | Tell in this description that the |
05620dd4 SK |
67 | .I argument |
68 | is required. | |
69 | .TP | |
70 | \fB\-V\fR, \fB\-\-version\fR | |
71 | Display version information and exit. | |
72 | .TP | |
73 | \fB\-h\fR, \fB\-\-help\fR | |
cfbebb29 | 74 | Display help text and exit. |
05620dd4 | 75 | .SH NOTES |
cfbebb29 | 76 | Tell details that users might need to know. For example, kernel feature or |
05620dd4 SK |
77 | version requirements. |
78 | .PP | |
cfbebb29 | 79 | The man-page source lines should not exceed 80 characters in length. |
05620dd4 | 80 | .PP |
cfbebb29 BS |
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 | |
05620dd4 SK |
83 | .BR groff_man (7) |
84 | how to use man page macros. | |
85 | .PP | |
cfbebb29 | 86 | The use cases of |
05620dd4 | 87 | .I italic |
cfbebb29 | 88 | (which is underlined on a terminal) and |
05620dd4 | 89 | .B bold |
cfbebb29 BS |
90 | are not strictly defined. The main convention is that |
91 | .I symbolic arguments | |
92 | use italic, and | |
93 | .B commands | |
94 | and | |
95 | .B literal arguments | |
96 | use bold, and | |
97 | .I other highlights | |
98 | use | |
99 | .B either | |
100 | one. | |
05620dd4 SK |
101 | .\" |
102 | .\" The manual page comments are undervalued way of adding clarifications | |
103 | .\" quite not belong to the manual, questions, TODO items etc. Feel free | |
104 | .\" to use them. | |
105 | .\" | |
106 | .PP | |
107 | When in the source a new sentence begins somewhere midline, it should use a | |
cfbebb29 BS |
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. | |
05620dd4 | 113 | .SH ENVIRONMENT |
cfbebb29 | 114 | Tell which environment variables affect, and how, the execution of the command. |
05620dd4 SK |
115 | .TP |
116 | .B EXAMPLE_PATH | |
cfbebb29 BS |
117 | Configuration file path. Notice that well-known environment variables, such as |
118 | .BR HOME , | |
119 | do not need explanation. | |
05620dd4 | 120 | .SH FILES |
cfbebb29 | 121 | Tell which file(s) the command uses. |
05620dd4 SK |
122 | .TP |
123 | .B $EXAMPLE_PATH | |
124 | .TQ | |
125 | .B $HOME/.example.conf | |
126 | .TQ | |
127 | .B /etc/example.conf | |
cfbebb29 BS |
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 | |
05620dd4 SK |
133 | .B SEE ALSO |
134 | section. | |
135 | .TP | |
136 | .B /var/log/example.log | |
137 | Another file. | |
138 | .SH EXAMPLES | |
cfbebb29 BS |
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. | |
05620dd4 SK |
141 | .TP |
142 | .B example -h | |
143 | Output help screen. | |
144 | .TP | |
145 | .B example -V | |
146 | Output version information. | |
147 | .SH "EXIT STATUS" | |
cfbebb29 | 148 | This section can be left out if the command has only two return values, |
05620dd4 SK |
149 | .B 0 |
150 | for success and | |
151 | .B 1 | |
152 | for failure. Use of | |
153 | .B sysexits.h | |
154 | return values must be mentioned, but does not need to be explained. | |
155 | .PP | |
156 | .RS | |
157 | .PD 0 | |
158 | .TP | |
159 | .B 0 | |
160 | success | |
161 | .TP | |
162 | .B 1 | |
163 | failure | |
164 | .TP | |
165 | .B 2 | |
166 | tell why this could happen | |
167 | .TP | |
168 | .B 3 | |
169 | etc | |
170 | .PD | |
171 | .RE | |
172 | .SH AUTHORS | |
8a69abf0 | 173 | .MT rjh@\:example.org |
05620dd4 | 174 | Random J. Hacker |
8a69abf0 | 175 | .ME |
05620dd4 | 176 | .br |
8a69abf0 | 177 | .MT fred@\:example.com |
05620dd4 | 178 | Fred Foobar |
8a69abf0 | 179 | .ME |
05620dd4 SK |
180 | .SH "SEE ALSO" |
181 | .BR groff_man (7), | |
182 | .BR foo (1), | |
183 | .BR bar (8) | |
184 | .SH AVAILABILITY | |
185 | The example command is part of the util-linux package and is available from | |
d673b74e | 186 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
05620dd4 SK |
187 | Linux Kernel Archive |
188 | .UE . |