-
Notifications
You must be signed in to change notification settings - Fork 4
/
part2-3-1.xml
378 lines (378 loc) · 10.4 KB
/
part2-3-1.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Required Sections</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3>
Required Sections
</h3>
<p>
As discussed previously, a section is begun by the <a href="macros.xml#macro_sh" class="macro">Sh</a> macro and
continues until the end of file or another section.
</p>
<div class="mdocsyntax">
.<a href="macros.xml#macro_sh" class="macro">Sh</a> <span class="macroarg">SECTION NAME</span>
<br />
Text and macros within the section.
</div>
<p>
What follows is a description of each required section: if your manual does not have the documented section, it should
not be considered as well-formed. Do note, however, that some types of manuals lack the <span
class="sec">SYNOPSIS</span> section.
</p>
<h4>
NAME
</h4>
<p>
The <span class="sec">NAME</span> section immediately follows the document prologue and is thus usually the first macro
of the document body. It specifies the name of each documented component, and provides a brief description of the
components as a whole.
</p>
<p>
The following is an example of the <span class="sec">NAME</span> section for a single utility, <span class="cmd">hi</span>.
</p>
<div class="mdocin">
.Sh NAME
<br />
.Nm foo
<br />
.Nd print a simple greeting
</div>
<p>
The <a href="macros.xml#macro_nd" class="macro">Nd</a> macro should consist of a single line without trailing
punctuation or leading capitalisation. As a rule of thumb, this description should be a sentence clause in the
imperative mood for commands and functions, or simply a noun phrase for file formats, devices, and miscellanea.
</p>
<p>
Example imperative:
</p>
<div class="mdocin">
.Nm foo
<br />
.Nd print a simple greeting
</div>
<p>
Example noun phrase:
</p>
<div class="mdocin">
.Nm mdoc
<br />
.Nd mdoc language reference
</div>
<p>
In the event of multiple named components, such as a function library or aliased commands, comma-separate each command
but for the last. It's common to alphabetically order this listing.
</p>
<div class="mdocin">
.Nm hello ,
<br />
.Nm hi
<br />
.Nd print greetings
</div>
<p>
Note that the punctuation should be separate from the macro argument. This allows the formatter to distinguish between
the name and trailing punctuation.
</p>
<h4>
SYNOPSIS
</h4>
<p>
The <span class="sec">SYNOPSIS</span> section, if specified, follows the <span class="sec">NAME</span> section. It
specifies the calling syntax of a component, thus, it is necessary for functions and commands. The <span
class="sec">SYNOPSIS</span> section has a layout dictated by convention, and depends upon the category.
</p>
<h5>
Commands
</h5>
<p>
For command manuals in category <span class="cat">1</span>, <span class="cat">6</span>, and <span class="cat">9</span>,
each command must have its full syntax stipulated.
</p>
<div class="mdocin">
.Nm hello
<br />
.Op Fl a
<br />
.Op Fl o Ar output
<br />
.Op Ar prefix
</div>
<p>
This defines three optional arguments for the <span class="cmd">hi</span> command: a flag, a flag with an argument, and
an argument. Flags should be purely alphabetical, without regard to whether a flag takes an argument. Arguments should
also be alphabetised.
</p>
<p>
Note that if your manual only documents one component, it's unnecessary to re-write the command name for <a
href="macros.xml#macro_nm" class="macro">Nm</a>. If omitted, the last specified <a
href="macros.xml#macro_nm" class="macro">Nm</a> in the <span class="sec">NAME</span> will be used.
</p>
<p>
Multiple commands are specified in the order they appear within the <span class="sec">NAME</span> section.
</p>
<div class="mdocin">
.Nm hello
<br />
.Op Fl a
<br />
.Op Fl o Ar output
<br />
.Op Ar prefix
<br />
.Nm hi
</div>
<p>
Since there are multiple <a href="macros.xml#macro_nm" class="macro">Nm</a> macros in the <span
class="sec">NAME</span> section, it's necessary that we specify the name of each command. In this example, an
additional command <span class="cmd">hi</span> is specified, which has neither flags nor arguments.
</p>
<h5>
Functions
</h5>
<p>
Function libraries are more complicated, as they involve more diverse content. A function library <span
class="sec">SYNOPSIS</span> section consists of all documented material, including header files, functions,
variables, macros, and so on.
</p>
<p>
A minimum function manual consists of a single function call and the header file of its prototype (if in a language
requiring header files, such as C):
</p>
<div class="mdocin">
.In greeting.h
<br />
.Ft int
<br />
.Fo hello
<br />
.Fa "int C"
<br />
.Fa "const char *output"
<br />
.Fc
</div>
<p>
The header file comes before those functions it describes. If one or more header files are required, list them in the
order of inclusion in source files.
</p>
<div class="mdocin">
.In sys/types.h
<br />
.In greeting.h
<br />
.Ft int
<br />
.Fo hello
<br />
.Fa "u_int C"
<br />
.Fa "const char *output"
<br />
.Fc
</div>
<p>
If multiple functions are documented, list them in the order they appear in the <span class="sec">NAME</span> section.
</p>
<div class="mdocin">
.In sys/types.h
<br />
.In greeting.h
<br />
.Ft int
<br />
.Fo hello
<br />
.Fa "u_int C"
<br />
.Fa "const char *output"
<br />
.Fc
<br />
.Ft void
<br />
.Fn hi
</div>
<p>
List any global variables with the <a href="macros.xml#macro_vt" class="macro">Vt</a> and/or <a
href="macros.xml#macro_va" class="macro">Va</a> macro following function prototypes.
</p>
<div class="mdocin">
.In sys/types.h
<br />
.In greeting.h
<br />
.Ft int
<br />
.Fo hello
<br />
.Fa "u_int C"
<br />
.Fa "const char *output"
<br />
.Fc
<br />
.Ft void
<br />
.Fn hi
<br />
.Vt extern const char * const * greetings;
</div>
<p>
Macro definitions, however, should come before the function prototypes. These use the <a href="macros.xml#macro_fd"
class="macro">Fd</a> macro and must include the preprocessor directive for the macro.
</p>
<div class="mdocin">
.In sys/types.h
<br />
.In greeting.h
<br />
.Fd #define GREETING
<br />
.Ft int
<br />
.Fo hello
<br />
.Fa "u_int C"
<br />
.Fa "const char *output"
<br />
.Fc
<br />
.Ft void
<br />
.Fn hi
<br />
.Vt extern const char * const * greetings;
</div>
<p>
Some manuals define a range of functions with differing header dependencies. In general it's not a good idea to group
these within the same manual. However, if necessary, arrange the functions and variables underneath their header file
<a href="macros.xml#macro_in" class="macro">In</a> macros. These need not necessarily much with the <span
class="sec">NAME</span> section ordering, but should be as close as possible.
</p>
<h4>
DESCRIPTION
</h4>
<p>
This section documents the component itself, and is usually the longest. For commands, each command is described in
detail along with its arguments. For functions, each function must be described along with its types and arguments.
</p>
<h5>
Commands
</h5>
<p>
A command or set of commands is documented in <span class="sec">DESCRIPTION</span> with a brief explanation of
behaviour, default usage, then a list of arguments. Some utilities state default usage following the argument list;
however, manpages beginning with these statements are more readable and economical.
</p>
<div class="mdocin">
The
<br />
.Nm
<br />
command prints a mixed-case greeting to standard output.
<br />
.Pp
<br />
The arguments are as follows:
<br />
.Bl -tag -width Ds
<br />
.It Fl C
<br />
Whether to uppercase the output.
<br />
.It Fl o Ar output
<br />
A file into which output should be written.
<br />
.It Ar prefix
<br />
A string prefixed to the output.
<br />
.El
</div>
<p>
If multiple commands are included, they should be listed in the order they appear in <span class="sec">NAME</span> and
<span class="sec">DESCRIPTION</span>. Remember to specify a documented command, in this case, whenever invoking the <a
href="macros.xml#macro_nm" class="macro">Nm</a> macro. Command exit statuses are documented in <span
class="sec">EXIT STATUS</span>.
</p>
<h5>
Functions
</h5>
<p>
Functions do not share the <span class="screen">The arguments are as follows</span> convention that commands enjoy.
Most often, a function is described in paragraph form.
</p>
<div class="mdocin">
The
<br />
.Fn hello
<br />
function prints a greeting to standard out.
<br />
If
<br />
.Fa C
<br />
is non-zero, output is upper-cased.
<br />
If
<br />
.Fa prefix
<br />
is non-NULL, it is prefixed to the output.
</div>
<p>
A function with many variables, or complicated variables, may wish to choose the same listed-argument notation of
commands.
</p>
<div class="mdocin">
The
<br />
.Fn hello
<br />
function prints a greeting to standard out.
<br />
The arguments are as follows:
<br />
.Bl -tag -width Ds
<br />
.It Fa "C"
<br />
If non-zero, output is upper-cased.
<br />
.It Fa "prefix"
<br />
If non-NULL,
<br />
.Fa prefix
<br />
is prefixed to the output.
<br />
.El
</div>
<p>
Above all, you must be careful to document each argument to each function. Function return values are usually
documented in <span class="sec">RETURN VALUES</span>.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part2-3-2.xml">Next</a></td>
<td class="nav-home"><a href="http://manpages.bsd.lv/index.html">Home</a></td>
<td class="nav-history"><a href="http://manpages.bsd.lv/cgi-bin/cvsweb/part2-3-1.xml?cvsroot=manpages">History</a></td>
</tr>
</tbody>
</table>
<p class="edits">
Last edited by $Author$ on $Date$. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.
</p>
</body>
</html>