-
Notifications
You must be signed in to change notification settings - Fork 4
/
part2-3-2.xml
490 lines (490 loc) · 14.4 KB
/
part2-3-2.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
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Optional Sections</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h3>
Optional 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 optional section. An optional section is not required for a well-formed manual,
but may be necessary for a manual of a given type. For example, the <span class="sec">EXIT STATUS</span> section is not
required, but is necessary for utilities.
</p>
<h4>
IMPLEMENTATION NOTES
</h4>
<p>
For components describing an algorithm, or implementing a generic interface, it's at time useful to document the
implementation itself. As this is not relevant to the calling syntax or description of a component, this is relegated
to the <span class="sec">IMPLEMENTATION NOTES</span> section.
</p>
<p>
Consider a simple sorting function, <span class="func">mysort</span>.
</p>
<div class="mdocin">
.Sh SYNOPSIS
<br />
.In mysort.h
<br />
.Ft void
<br />
.Fn mysort "int *input"
<br />
.Sh DESCRIPTION
<br />
The
<br />
.Fn mysort
<br />
function in-place sorts an integer array
<br />
.Fa input .
<br />
.Sh IMPLEMENTATION NOTES
<br />
The
<br />
.Fn mysort
<br />
function uses a bubble-sort algorithm for sorting and thus operates in
<br />
O(n^2) time with respect to input size.
<br />
Since swapping is in-place, a constant number of allocations occur.
</div>
<p>
In general, <span class="sec">IMPLEMENTATION NOTES</span> is not used, and is thus rarely found in UNIX manuals.
</p>
<h4>
RETURN VALUES
</h4>
<p>
Manuals describing functions (categories <span class="cat">2</span>, <span class="cat">3</span>, and <span
class="cat">9</span>) must use the <span class="sec">RETURN VALUES</span> section to document each function's
return value. If a manual documents functions in a language without return values, or functions do not return a value,
they need not use this section.
</p>
<p>
System calls (category <span class="cat">2</span>) usually employ the <a href="macros.xml#macro_rv"
class="macro">Rv</a> macro to stipulate a standard return value statement.
</p>
<div class="mdocin">
.Sh RETURN VALUES
<br />
.Rv -std
</div>
<p>
Note that the <span class="macroflag">std</span> flag is a required argument to <a href="macros.xml#macro_rv"
class="macro">Rv</a>, for historical reasons.
</p>
<p>
For non-system functions, be as brief as possible.
</p>
<div class="mdocin">
.Sh RETURN VALUES
<br />
The
<br />
.Fn hello
<br />
function returns zero on success and non-zero on failure.
</div>
<h4>
ENVIRONMENT
</h4>
<p>
Both commands and functions may be affected by UNIX environmental variables. These must be documented in the <span
class="sec">ENVIRONMENT</span> section of the manual. Each variable should be listed as a <a
href="macros.xml#macro_ev" class="macro">Ev</a> along with its effect on the component.
</p>
<div class="mdocin">
.Sh ENVIRONMENT
<br />
.Bl -tag -width Ds
<br />
.It Ev TZ
<br />
The time zone for when displaying dates.
<br />
.El
</div>
<p>
Some historical manuals use <span class="sec">ENVIRONMENT VARIABLES</span> instead of <span
class="sec">ENVIRONMENT</span>.
</p>
<h4>
FILES
</h4>
<p>
Both commands and functions may also be affected by files, although this is mainly the purview of commands. These files
should be listed in the <span class="sec">FILES</span> section in a tagged list.
</p>
<div class="mdocin">
.Sh FILES
<br />
.Bl -tag -width Ds
<br />
.It Pa ~/.profile
<br />
User's login profile.
<br />
.El
</div>
<h4>
EXIT STATUS
</h4>
<p>
This section is the dual of <span class="sec">RETURN VALUES</span> for commands in categories <span
class="cat">1</span>, <span class="cat">6</span>, and <span class="cat">8</span>. It documents the exit status
of commands.
</p>
<p>
If your utility exits with zero on success and greater than zero on failure (the standard for most utilities), use the
<a href="macros.xml#macro_ex" class="macro">Ex</a> macro.
</p>
<div class="mdocin">
.Sh EXIT STATUS
<br />
.Ex -std
</div>
<p>
More complex commands should document all possible exit status.
</p>
<h4>
EXAMPLES
</h4>
<p>
In many situations of casual use, the <span class="sec">EXAMPLES</span> section is the first visited in a manual. It
should consist of concise, documented examples of the most common uses of your component.
</p>
<p>
For commands, the <span class="sec">EXAMPLES</span> section should contain a handful of common use cases. In general,
these should consist of standalone invocations and, if the input and output correspond to other utilities, invocations
as part of a pipeline.
</p>
<p>
Although the <span class="cmd">hello</span> example is almost too trivial for documentation, consider if it were used to
greet new users to a Unix system. Thus, a common example would be the following:
</p>
<div class="mdocin">
.Sh EXAMPLES
<br />
The following sends a greeting message to the new user
<br />
.Qq joe .
<br />
.Pp
<br />
.Dl $ hello \(dqDear Joe, \(dq \(bv mail -s \(dqHi!\(dq joe
</div>
<p>
The <a href="macros.xml#macro_dl" class="macro">Dl</a>, used for one-line literal displays, is a common macro in the
<span class="sec">EXAMPLES</span> section. For multi-line displays, use the <a href="macros.xml#macro_bd"
class="macro">Bd</a> <span class="macroflag">literal</span> environment, usually with a default indentation with
<span class="macroflag">offset</span> <span class="macroarg">indent</span>.
</p>
<div class="mdocin">
.Sh EXAMPLES
<br />
The following sends a greeting message to the new user
<br />
.Qq joe .
<br />
.Bd -literal -offset indent
<br />
$ hello \(dqDear Joe, \(dq \(bv \e
<br />
mail -s \(dqHi!\(dq joe
<br />
.Ed
</div>
<p>
For functions and function libraries, it's more common to include a single, thorough source example than individual
examples for each function. These always use the <a href="macros.xml#macro_bd" class="macro">Bd</a> <span
class="macroflag">literal</span> display environment and an indentation.
</p>
<div class="mdocin">
.Sh EXAMPLES
<br />
The following is a simple utility interfacing with the
<br />
.Nm
<br />
library:
<br />
.Bd -literal -offset indent
<br />
#include <stdlib.h>
<br />
#include "hello.h"
<br />
<br />
int
<br />
main(int argc, char *argv[]) {
<br />
hello(0, argc > r ? argv[1] : NULL);
<br />
return(EXIT_SUCCESS);
<br />
}
<br />
.Ed
</div>
<p>
Use terse syntax for your example, without error checking for functions not being documented, e.g., <span
class="func">open</span> or <span class="func">scanf</span>.
</p>
<p>
Some manuals will use the <span class="screen">vS</span> and <span class="screen">vE</span> macros around source code.
These are not <span class="lang">mdoc</span> and should be avoided in portable manuals.
</p>
<h4>
DIAGNOSTICS
</h4>
<p>
If your component emits regular debug, status, error, or warning messages, document the syntax of these messages in
<span class="sec">DIAGNOSTICS</span>.
</p>
<p>
Some historic manuals document function return values in this section, but modern practise is to do in <span
class="sec">RETURN VALUES</span> or, if setting the error constant of the C library, <span
class="sec">ERRORS</span>.
</p>
<p>
The <a href="macros.xml#macro_bl" class="macro">Bl</a> <span class="macroflag">diag</span> lists are most often used
for documenting emitted messages.
</p>
<div class="mdocin">
.Sh DIAGNOSTICS
<br />
.Bl -diag
<br />
.It "%file:%line:%col: %msg[: %extra]"
<br />
An error occured when processing
<br />
.Cm %file
<br />
at line and column
<br />
.Cm %line
<br />
and
<br />
.Cm %col ,
<br />
respectively.
<br />
The error message
<br />
.Cm %msg
<br />
may be followed by additional debugging information in
<br />
.Cm %extra .
<br />
.El
</div>
<h4>
ERRORS
</h4>
<p>
This section is used exclusively by functions that set or return a regular error code. The most common use is for
system calls (category two) setting error constants in the C library. In either case, this section should consist of a
single list documenting all possible error codes. In the latter case, each error should be labelled within the <a
href="macros.xml#macro_er" class="macro">Er</a> macro.
</p>
<h4>
SEE ALSO
</h4>
<p>
This section consists of cross-references to other manuals or literature. It is a standard section in most UNIX
manuals. Any components referenced in your manual should be duplicated here along with any other bibliographic texts.
</p>
<p>
For UNIX manual cross-references, use the <a href="macros.xml#macro_xr" class="macro">Xr</a> macro. These should be
specified in a list ordered first by section, then by name. Non-terminal references should be comma-separated.
</p>
<div class="mdocin">
.Sh SEE ALSO
<br />
.Xr mandoc 1 ,
<br />
.Xr mandoc 3 ,
<br />
.Xr man 7 ,
<br />
.Xr mdoc 7
</div>
<p>
If your manual references other documents or literature, you may include them in this section within a bibliographic
reference as well. The <a href="macros.xml#macro_rs" class="macro">Rs</a> block is used for bibliographic references.
These should be specified after any UNIX manual cross-references.
</p>
<div class="mdocin">
.Sh SEE ALSO
<br />
.Xr mandoc 1 ,
<br />
.Xr mandoc 3 ,
<br />
.Xr man 7 ,
<br />
.Xr mdoc 7
<br />
.Rs
<br />
.%A Brian W. Kernighan
<br />
.%A Lorinda L. Cherry
<br />
.%T System for Typesetting Mathematics
<br />
.%J Communications of the ACM
<br />
.%V 18
<br />
.%P 151\(en157
<br />
.%D March, 1975
<br />
.Re
</div>
<p>
Bibliographic references should be ordered by document title. Advanced references will be covered later in this book.
</p>
<h4>
STANDARDS
</h4>
<p>
If your component references any standards literature, it should be mentioned here. Most standards (e.g., POSIX, ANSI,
etc.) may be semantically noted with the <a href="macros.xml#macro_st" class="macro">St</a> macro. When implementing
standardised wire protocols, references to RFC and other literature should also be mentioned here. These differ from
referenced standards in terms of being implemented versus referred.
</p>
<div class="mdocin">
.Sh STANDARDS
<br />
The
<br />
.Nm
<br />
utility is compliant with the
<br />
.St -xpg4
<br />
specification.
</div>
<p>
If your component consists of deviations from a given standard, they should be mentioned in this section as well. Some
historic manuals use a special <span class="sec">COMPATIBILITY</span> section for this, but this is discouraged unless
when discussing compatibility with non-standard but common utilities.
</p>
<p>
This section has also been referred to as <span class="sec">CONFORMING TO</span> on some GNU/Linux manuals.
</p>
<h4>
HISTORY
</h4>
<p>
Some components have a historical basis: this should be included here. Keep this information terse and, above all,
correct.
</p>
<p>
If your manual includes prior implementations of your component, for example, it's common to include the dates and
developers of those prior implementations.
</p>
<h4>
AUTHORS
</h4>
<p>
Another standard section for UNIX manuals is the <span class="sec">AUTHORS</span> section, which should always mention
the current contact for the utility. The traditional text for this section is as follows.
</p>
<div class="mdocin">
.Sh AUTHORS
<br />
The
<br />
.Nm
<br />
reference was written by
<br />
.An Joe Foo Aq joe@example.com .
</div>
<p>
However, in as e-mail addresses are a ubiquitous form of contact, it's considered good practise to use the correct
semantic notation.
</p>
<div class="mdocin">
.Sh AUTHORS
<br />
The
<br />
.Nm
<br />
reference was written by
<br />
.An Joe Foo ,
<br />
.Mt joe@example.com .
</div>
<p>
The term <span class="screen">reference</span> in this fragment should reflect the content of the manual.
</p>
<h4>
CAVEATS
</h4>
<p>
The <span class="sec">CAVEATS</span> section is not often used. It consists of text relevant to unexpected (but
unchangeable) behaviour of the component.
</p>
<h4>
BUGS
</h4>
<p>
If the component has known bugs, they should be listed here. In some historic manuals, authors used this section to
list <q>no bugs present</q>; however, this text can be misleading for machine-readers of manuals and should be avoided
in new manuals.
</p>
<h4>
SECURITY CONSIDERATIONS
</h4>
<p>
The <span class="sec">SECURITY CONSIDERATIONS</span> section is reserved for components whose deployment may be
sensitive to security conditions, such as network daemons. It should include suggestions on security measures beyond
the scope of the component.
</p>
<p>
This section was historically called <span class="sec">SECURITY</span>.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part3.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-2.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>