9c969f181c55ca65d45153ca8630d8556edb2bae
[dragonfly.git] / usr.bin / mandoc / man.7
1 .\"     $Id: man.7,v 1.13 2009/10/27 21:40:07 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd October 29, 2009
18 .Dt MAN 7
19 .Os
20 .
21 .
22 .Sh NAME
23 .Nm man
24 .Nd man language reference
25 .
26 .
27 .Sh DESCRIPTION
28 The
29 .Nm man
30 language was historically used to format
31 .Ux
32 manuals.  This reference document describes its syntax, structure, and
33 usage.
34 .
35 .Pp
36 .Bf -emphasis
37 Do not use
38 .Nm
39 to write your manuals.
40 .Ef
41 Use the
42 .Xr mdoc 7
43 language, instead.
44 .
45 .Pp
46 An
47 .Nm
48 document follows simple rules:  lines beginning with the control
49 character
50 .Sq \&.
51 are parsed for macros.  Other lines are interpreted within the scope of
52 prior macros:
53 .Bd -literal -offset indent
54 \&.SH Macro lines change control state.
55 Other lines are interpreted within the current state.
56 .Ed
57 .
58 .
59 .Sh INPUT ENCODING
60 .Nm
61 documents may contain only graphable 7-bit ASCII characters, the
62 space character, and the tabs character.  All manuals must have
63 .Ux
64 line termination.
65 .
66 .Pp
67 Blank lines are acceptable; where found, the output will assert a
68 vertical space.
69 .
70 .Pp
71 The
72 .Sq \ec
73 escape is common in historical
74 .Nm
75 documents; if encountered at the end of a word, it ensures that the
76 subsequent word isn't off-set by whitespace.
77 .
78 .
79 .Ss Comments
80 Text following a
81 .Sq \e\*" ,
82 whether in a macro or free-form text line, is ignored to the end of
83 line.  A macro line with only a control character and comment escape,
84 .Sq \&.\e" ,
85 is also ignored.  Macro lines with only a control charater and
86 optionally whitespace are stripped from input.
87 .
88 .
89 .Ss Special Characters
90 Special characters may occur in both macro and free-form lines.
91 Sequences begin with the escape character
92 .Sq \e
93 followed by either an open-parenthesis
94 .Sq \&(
95 for two-character sequences; an open-bracket
96 .Sq \&[
97 for n-character sequences (terminated at a close-bracket
98 .Sq \&] ) ;
99 or a single one-character sequence.  See
100 .Xr mandoc_char 7
101 for a complete list.  Examples include
102 .Sq \e(em
103 .Pq em-dash
104 and
105 .Sq \ee
106 .Pq back-slash .
107 .
108 .
109 .Ss Text Decoration
110 Terms may be text-decorated using the
111 .Sq \ef
112 escape followed by an indicator: B (bold), I, (italic), or P and R
113 (Roman, or reset).
114 .
115 .
116 .Ss Whitespace
117 Unless specifically escaped, consecutive blocks of whitespace are pruned
118 from input.  These are later re-added, if applicable, by a front-end
119 utility such as
120 .Xr mandoc 1 .
121 .
122 .Ss Scaling Widths
123 Many macros support scaled widths for their arguments, such as
124 stipulating a two-inch paragraph indentation with the following:
125 .Bd -literal -offset indent
126 \&.HP 2i
127 .Ed
128 .
129 .Pp
130 The syntax for scaled widths is
131 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? ,
132 where a decimal must be preceded or proceeded by at least one digit.
133 Negative numbers, while accepted, are truncated to zero.  The following
134 scaling units are accepted:
135 .
136 .Pp
137 .Bl -tag -width Ds -offset indent -compact
138 .It c
139 centimetre
140 .It i
141 inch
142 .It P
143 pica (~1/6 inch)
144 .It p
145 point (~1/72 inch)
146 .It f
147 synonym for
148 .Sq u
149 .It v
150 default vertical span
151 .It m
152 width of rendered
153 .Sq m
154 .Pq em
155 character
156 .It n
157 width of rendered
158 .Sq n
159 .Pq en
160 character
161 .It u
162 default horizontal span
163 .It M
164 mini-em (~1/100 em)
165 .El
166 .Pp
167 Using anything other than
168 .Sq m ,
169 .Sq n ,
170 .Sq u ,
171 or
172 .Sq v
173 is necessarily non-portable across output media.  See
174 .Sx COMPATIBILITY .
175 .
176 .Pp
177 If a scaling unit is not provided, the numerical value is interpreted
178 under the default rules of
179 .Sq v
180 for vertical spaces and
181 .Sq u
182 for horizontal ones.
183 .Em Note :
184 this differs from
185 .Xr mdoc 7 ,
186 which, if a unit is not provided, will instead interpret the string as
187 literal text.
188 .
189 .
190 .Sh MANUAL STRUCTURE
191 Each
192 .Nm
193 document must contain contains at least the
194 .Sx \&TH
195 macro describing the document's section and title.  It may occur
196 anywhere in the document, although conventionally, it appears as the
197 first macro.
198 .
199 .Pp
200 Beyond
201 .Sx \&TH ,
202 at least one macro or text node must appear in the document.  Documents
203 are generally structured as follows:
204 .Bd -literal -offset indent
205 \&.TH FOO 1 "13 Aug 2009"
206 \&.
207 \&.SH NAME
208 \efBfoo\efR \e(en a description goes here
209 \&.\e\*q The next is for sections 2 & 3 only.
210 \&.\e\*q .SH LIBRARY
211 \&.
212 \&.SH SYNOPSIS
213 \efBfoo\efR [\efB\e-options\efR] arguments...
214 \&.
215 \&.SH DESCRIPTION
216 The \efBfoo\efR utility processes files...
217 \&.
218 \&.\e\*q .SH IMPLEMENTATION NOTES
219 \&.\e\*q The next is for sections 1 & 8 only.
220 \&.\e\*q .SH EXIT STATUS
221 \&.\e\*q The next is for sections 2, 3, & 9 only.
222 \&.\e\*q .SH RETURN VALUES
223 \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
224 \&.\e\*q .SH ENVIRONMENT
225 \&.\e\*q .SH FILES
226 \&.\e\*q .SH EXAMPLES
227 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
228 \&.\e\*q .SH DIAGNOSTICS
229 \&.\e\*q The next is for sections 2, 3, & 9 only.
230 \&.\e\*q .SH ERRORS
231 \&.\e\*q .SH SEE ALSO
232 \&.\e\*q \efBbar\efR(1)
233 \&.\e\*q .SH STANDARDS
234 \&.\e\*q .SH HISTORY
235 \&.\e\*q .SH AUTHORS
236 \&.\e\*q .SH CAVEATS
237 \&.\e\*q .SH BUGS
238 \&.\e\*q .SH SECURITY CONSIDERATIONS
239 .Ed
240 .Pp
241 The sections in a
242 .Nm
243 document are conventionally ordered as they appear above.  Sections
244 should be composed as follows:
245 .Bl -tag -width Ds -offset Ds
246 .It NAME
247 The name(s) and a short description of the documented material.  The
248 syntax for this is generally as follows:
249 .Pp
250 .D1 \efBname\efR \e(en description
251 .It LIBRARY
252 The name of the library containing the documented material, which is
253 assumed to be a function in a section 2 or 3 manual.  For functions in
254 the C library, this may be as follows:
255 .Pp
256 .D1 Standard C Library (libc, -lc)
257 .It SYNOPSIS
258 Documents the utility invocation syntax, function call syntax, or device
259 configuration.
260 .Pp
261 For the first, utilities (sections 1, 6, and 8), this is
262 generally structured as follows:
263 .Pp
264 .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
265 .Pp
266 For the second, function calls (sections 2, 3, 9):
267 .Pp
268 .D1 \. Ns Sx \&B No char *name(char *\efIarg\efR);
269 .Pp
270 And for the third, configurations (section 4):
271 .Pp
272 .D1 \. Ns Sx \&B No name* at cardbus ? function ?
273 .Pp
274 Manuals not in these sections generally don't need a SYNOPSIS.
275 .It DESCRIPTION
276 This expands upon the brief, one-line description in NAME.  It usually
277 contains a break-down of the options (if documenting a command).
278 .It IMPLEMENTATION NOTES
279 Implementation-specific notes should be kept here.  This is useful when
280 implementing standard functions that may have side effects or notable
281 algorithmic implications.
282 .It EXIT STATUS
283 .It RETURN VALUES
284 .It ENVIRONMENT
285 .It FILES
286 .It EXAMPLES
287 .It DIAGNOSTICS
288 .It ERRORS
289 .It SEE ALSO
290 .It STANDARDS
291 .It HISTORY
292 .It AUTHORS
293 .It CAVEATS
294 .It BUGS
295 .It SECURITY CONSIDERATIONS
296 .El
297 .
298 .
299 .Sh MACRO SYNTAX
300 Macros are one to three three characters in length and begin with a
301 control character ,
302 .Sq \&. ,
303 at the beginning of the line.  An arbitrary amount of whitespace may
304 sit between the control character and the macro name.  Thus, the
305 following are equivalent:
306 .Bd -literal -offset indent
307 \&.PP
308 \&.\ \ \ PP
309 .Ed
310 .
311 .Pp
312 The
313 .Nm
314 macros are classified by scope: line scope or block scope.  Line
315 macros are only scoped to the current line (and, in some situations,
316 the subsequent line).  Block macros are scoped to the current line and
317 subsequent lines until closed by another block macro.
318 .
319 .
320 .Ss Line Macros
321 Line macros are generally scoped to the current line, with the body
322 consisting of zero or more arguments.  If a macro is scoped to the next
323 line and the line arguments are empty, the next line is used instead,
324 else the general syntax is used.  Thus:
325 .Bd -literal -offset indent
326 \&.I
327 foo
328 .Ed
329 .
330 .Pp
331 is equivalent to
332 .Sq \&.I foo .
333 If next-line macros are invoked consecutively, only the last is used.
334 If a next-line macro is proceded by a block macro, it is ignored.
335 .Bd -literal -offset indent
336 \&.YO \(lBbody...\(rB
337 \(lBbody...\(rB
338 .Ed
339 .
340 .Pp
341 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
342 .It Em Macro Ta Em Arguments Ta Em Scope
343 .It Sx \&B   Ta    n         Ta    next-line
344 .It Sx \&BI  Ta    n         Ta    current
345 .It Sx \&BR  Ta    n         Ta    current
346 .It Sx \&DT  Ta    0         Ta    current
347 .It Sx \&I   Ta    n         Ta    next-line
348 .It Sx \&IB  Ta    n         Ta    current
349 .It Sx \&IR  Ta    n         Ta    current
350 .It Sx \&PD  Ta    n         Ta    current
351 .It Sx \&R   Ta    n         Ta    next-line
352 .It Sx \&RB  Ta    n         Ta    current
353 .It Sx \&RI  Ta    n         Ta    current
354 .It Sx \&SB  Ta    n         Ta    next-line
355 .It Sx \&SM  Ta    n         Ta    next-line
356 .It Sx \&TH  Ta    >1, <6    Ta    current
357 .It Sx \&UC  Ta    n         Ta    current
358 .It Sx \&br  Ta    0         Ta    current
359 .It Sx \&fi  Ta    0         Ta    current
360 .It Sx \&i   Ta    n         Ta    current
361 .It Sx \&na  Ta    0         Ta    current
362 .It Sx \&nf  Ta    0         Ta    current
363 .It Sx \&r   Ta    0         Ta    current
364 .It Sx \&sp  Ta    1         Ta    current
365 .El
366 .
367 .Pp
368 The
369 .Sx \&PD ,
370 .Sx \&RS ,
371 .Sx \&RE ,
372 .Sx \&UC ,
373 .Sx \&br ,
374 .Sx \&fi ,
375 .Sx \&i ,
376 .Sx \&na ,
377 .Sx \&nf ,
378 .Sx \&r ,
379 and
380 .Sx \&sp
381 macros should not be used.  They're included for compatibility.
382 .
383 .
384 .Ss Block Macros
385 Block macros are comprised of a head and body.  Like for in-line macros,
386 the head is scoped to the current line and, in one circumstance, the
387 next line; the body is scoped to subsequent lines and is closed out by a
388 subsequent block macro invocation.
389 .Bd -literal -offset indent
390 \&.YO \(lBhead...\(rB
391 \(lBhead...\(rB
392 \(lBbody...\(rB
393 .Ed
394 .
395 .Pp
396 The closure of body scope may be to the section, where a macro is closed
397 by
398 .Sx \&SH ;
399 sub-section, closed by a section or
400 .Sx \&SS ;
401 part, closed by a section, sub-section, or
402 .Sx \&RE ;
403 or paragraph, closed by a section, sub-section, part,
404 .Sx \&HP ,
405 .Sx \&IP ,
406 .Sx \&LP ,
407 .Sx \&P ,
408 .Sx \&PP ,
409 or
410 .Sx \&TP .
411 No closure refers to an explicit block closing macro.
412 .
413 .Pp
414 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent
415 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope
416 .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph
417 .It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph
418 .It Sx \&LP  Ta    0         Ta    current    Ta    paragraph
419 .It Sx \&P   Ta    0         Ta    current    Ta    paragraph
420 .It Sx \&PP  Ta    0         Ta    current    Ta    paragraph
421 .It Sx \&RE  Ta    0         Ta    current    Ta    none
422 .It Sx \&RS  Ta    1         Ta    current    Ta    part
423 .It Sx \&SH  Ta    >0        Ta    next-line  Ta    section
424 .It Sx \&SS  Ta    >0        Ta    next-line  Ta    sub-section
425 .It Sx \&TP  Ta    n         Ta    next-line  Ta    paragraph
426 .El
427 .
428 .Pp
429 If a block macro is next-line scoped, it may only be followed by in-line
430 macros (excluding
431 .Sx \&DT ,
432 .Sx \&PD ,
433 .Sx \&TH ,
434 .Sx \&UC ,
435 .Sx \&br ,
436 .Sx \&na ,
437 .Sx \&sp ,
438 .Sx \&nf ,
439 and
440 .Sx \&fi ) .
441 .
442 .
443 .Sh REFERENCE
444 This section is a canonical reference to all macros, arranged
445 alphabetically.  For the scoping of individual macros, see
446 .Sx MACRO SYNTAX .
447 .
448 .Ss \&B
449 Text is rendered in bold face.
450 .Ss \&BI
451 Text is rendered alternately in bold face and italic.  Thus,
452 .Sq .BI this word and that
453 causes
454 .Sq this
455 and
456 .Sq and
457 to render in bold face, while
458 .Sq word
459 and
460 .Sq that
461 render in italics.  Whitespace between arguments is omitted in output.
462 .Ss \&BR
463 Text is rendered alternately in bold face and roman (the default font).
464 Whitespace between arguments is omitted in output.
465 .Ss \&DT
466 Has no effect.  Included for compatibility.
467 .Ss \&HP
468 Begin a paragraph whose initial output line is left-justified, but
469 subsequent output lines are indented, with the following syntax:
470 .Bd -literal -offset indent
471 \&.HP [width]
472 .Ed
473 .
474 .Pp
475 If scaling width
476 .Va width
477 is specified, it's saved for later paragraph left-margins; if
478 unspecified, the saved or default width is used.
479 .Ss \&I
480 Text is rendered in italics.
481 .Ss \&IB
482 Text is rendered alternately in italics and bold face.  Whitespace
483 between arguments is omitted in output.
484 .Ss \&IP
485 Begin a paragraph with the following syntax:
486 .Bd -literal -offset indent
487 \&.IP [head [width]]
488 .Ed
489 .
490 .Pp
491 This follows the behaviour of the
492 .Sx \&TP
493 except for the macro syntax (all arguments on the line, instead of
494 having next-line scope).  If
495 .Va width
496 is specified, it's saved for later paragraph left-margins; if
497 unspecified, the saved or default width is used.
498 .Ss \&IR
499 Text is rendered alternately in italics and roman (the default font).
500 Whitespace between arguments is omitted in output.
501 .Ss \&LP
502 Begin an undecorated paragraph.  The scope of a paragraph is closed by a
503 subsequent paragraph, sub-section, section, or end of file.  The saved
504 paragraph left-margin width is re-set to the default.
505 .Ss \&P
506 Synonym for
507 .Sx \&LP .
508 .Ss \&PP
509 Synonym for
510 .Sx \&LP .
511 .Ss \&R
512 Text is rendered in roman (the default font).
513 .Ss \&RB
514 Text is rendered alternately in roman (the default font) and bold face.
515 Whitespace between arguments is omitted in output.
516 .Ss \&RE
517 Explicitly close out the scope of a prior
518 .Sx \&RS .
519 .Ss \&RI
520 Text is rendered alternately in roman (the default font) and italics.
521 Whitespace between arguments is omitted in output.
522 .Ss \&RS
523 Begin a part setting the left margin.  The left margin controls the
524 offset, following an initial indentation, to un-indented text such as
525 that of
526 .Sx \&PP .
527 A scaling width may be specified as following:
528 .Bd -literal -offset indent
529 \&.RS [width]
530 .Ed
531 .
532 .Pp
533 If
534 .Va width
535 is not specified, the saved or default width is used.
536 .Ss \&SB
537 Text is rendered in small size (one point smaller than the default font)
538 bold face.
539 .Ss \&SH
540 Begin a section.  The scope of a section is only closed by another
541 section or the end of file.  The paragraph left-margin width is re-set
542 to the default.
543 .Ss \&SM
544 Text is rendered in small size (one point smaller than the default
545 font).
546 .Ss \&SS
547 Begin a sub-section.  The scope of a sub-section is closed by a
548 subsequent sub-section, section, or end of file.  The paragraph
549 left-margin width is re-set to the default.
550 .Ss \&TH
551 Sets the title of the manual page with the following syntax:
552 .Bd -literal -offset indent
553 \&.TH title section [date [source [volume]]]
554 .Ed
555 .
556 .Pp
557 At least the
558 .Va title
559 and
560 .Va section
561 arguments must be provided.  The
562 .Va date
563 argument should be formatted as
564 .Qq %b [%d] %Y
565 format, described in
566 .Xr strptime 3 .
567 The
568 .Va source
569 string specifies the organisation providing the utility.  The
570 .Va volume
571 replaces the default rendered volume as dictated by the manual section.
572 .Ss \&TP
573 Begin a paragraph where the head, if exceeding the indentation width, is
574 followed by a newline; if not, the body follows on the same line after a
575 buffer to the indentation width.  Subsequent output lines are indented.
576 .
577 .Pp
578 The indentation scaling width may be set as follows:
579 .Bd -literal -offset indent
580 \&.TP [width]
581 .Ed
582 .
583 .Pp
584 If
585 .Va width
586 is specified, it's saved for later paragraph left-margins; if
587 unspecified, the saved or default width is used.
588 .Ss \&PD
589 Has no effect.  Included for compatibility.
590 .Ss \&UC
591 Has no effect.  Included for compatibility.
592 .Ss \&br
593 Breaks the current line.  Consecutive invocations have no further effect.
594 .Ss \&fi
595 End literal mode begun by
596 .Sx \&nf .
597 .Ss \&i
598 Italicise arguments.  If no arguments are specified, all subsequent text
599 is italicised.
600 .Ss \&na
601 Don't align to the right margin.
602 .Ss \&nf
603 Begin literal mode: all subsequent free-form lines have their end of
604 line boundaries preserved.  May be ended by
605 .Sx \&fi .
606 .Ss \&r
607 Fonts and styles (bold face, italics) reset to roman (default font).
608 .Ss \&sp
609 Insert n spaces, where n is the macro's positive numeric argument.  If
610 0, this is equivalent to the
611 .Sx \&br
612 macro.
613 .
614 .
615 .Sh COMPATIBILITY
616 This section documents compatibility with other roff implementations, at
617 this time limited to
618 .Xr groff 1 .
619 .Bl -hyphen
620 .It
621 In quoted literals, groff allowed pair-wise double-quotes to produce a
622 standalone double-quote in formatted output.  This idiosyncratic
623 behaviour is no longer applicable.
624 .It
625 The
626 .Sq sp
627 macro does not accept negative numbers.
628 .It
629 Blocks of whitespace are stripped from both macro and free-form text
630 lines (except when in literal mode), while groff would retain whitespace
631 in free-form text lines.
632 .El
633 .
634 .
635 .Sh SEE ALSO
636 .Xr mandoc 1 ,
637 .Xr mandoc_char 7
638 .
639 .
640 .Sh AUTHORS
641 The
642 .Nm
643 reference was written by
644 .An Kristaps Dzonsons Aq kristaps@kth.se .
645 .
646 .
647 .Sh CAVEATS
648 Do not use this language.  Use
649 .Xr mdoc 7 ,
650 instead.
651 .