Import mdocml-1.11.1
[dragonfly.git] / contrib / mdocml / man.7
1 .\"     $Id: man.7,v 1.99 2011/03/07 01:35:51 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
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 $Mdocdate: March 7 2011 $
18 .Dt MAN 7
19 .Os
20 .Sh NAME
21 .Nm man
22 .Nd man language reference
23 .Sh DESCRIPTION
24 The
25 .Nm man
26 language was historically used to format
27 .Ux
28 manuals.
29 This reference document describes its syntax, structure, and usage.
30 .Pp
31 .Bf -emphasis
32 Do not use
33 .Nm
34 to write your manuals.
35 .Ef
36 Use the
37 .Xr mdoc 7
38 language, instead.
39 .Pp
40 A
41 .Nm
42 document follows simple rules:  lines beginning with the control
43 character
44 .Sq \&.
45 are parsed for macros.
46 Other lines are interpreted within the scope of
47 prior macros:
48 .Bd -literal -offset indent
49 \&.SH Macro lines change control state.
50 Other lines are interpreted within the current state.
51 .Ed
52 .Sh INPUT ENCODING
53 .Nm
54 documents may contain only graphable 7-bit ASCII characters, the
55 space character, and the tab character.
56 .Pp
57 Blank lines are acceptable; where found, the output will assert a
58 vertical space.
59 .Pp
60 If the first character of a line is a space, that line is printed
61 with a leading newline.
62 .Ss Comments
63 Text following a
64 .Sq \e\*q ,
65 whether in a macro or free-form text line, is ignored to the end of
66 line.
67 A macro line with only a control character and comment escape,
68 .Sq \&.\e\*q ,
69 is also ignored.
70 Macro lines with only a control character and optionally whitespace are
71 stripped from input.
72 .Ss Special Characters
73 Special characters may occur in both macro and free-form lines.
74 Sequences begin with the escape character
75 .Sq \e
76 followed by either an open-parenthesis
77 .Sq \&(
78 for two-character sequences; an open-bracket
79 .Sq \&[
80 for n-character sequences (terminated at a close-bracket
81 .Sq \&] ) ;
82 or a single one-character sequence.
83 See
84 .Xr mandoc_char 7
85 for a complete list.
86 Examples include
87 .Sq \e(em
88 .Pq em-dash
89 and
90 .Sq \ee
91 .Pq back-slash .
92 .Ss Text Decoration
93 Terms may be text-decorated using the
94 .Sq \ef
95 escape followed by an indicator: B (bold), I (italic), R (Roman), or P
96 (revert to previous mode):
97 .Pp
98 .D1 \efBbold\efR \efIitalic\efP
99 .Pp
100 A numerical representation 3, 2, or 1 (bold, italic, and Roman,
101 respectively) may be used instead.
102 A text decoration is only valid, if specified in free-form text, until
103 the next macro invocation; if specified within a macro, it's only valid
104 until the macro closes scope.
105 Note that macros like
106 .Sx \&BR
107 open and close a font scope with each argument.
108 .Pp
109 The
110 .Sq \ef
111 attribute is forgotten when entering or exiting a macro block.
112 .Ss Whitespace
113 Whitespace consists of the space character.
114 In free-form lines, whitespace is preserved within a line; unescaped
115 trailing spaces are stripped from input (unless in a literal context).
116 Blank free-form lines, which may include spaces, are permitted and
117 rendered as an empty line.
118 .Pp
119 In macro lines, whitespace delimits arguments and is discarded.
120 If arguments are quoted, whitespace within the quotes is retained.
121 .Ss Scaling Widths
122 Many macros support scaled widths for their arguments, such as
123 stipulating a two-inch paragraph indentation with the following:
124 .Bd -literal -offset indent
125 \&.HP 2i
126 .Ed
127 .Pp
128 The syntax for scaled widths is
129 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? ,
130 where a decimal must be preceded or proceeded by at least one digit.
131 Negative numbers, while accepted, are truncated to zero.
132 The following scaling units are accepted:
133 .Pp
134 .Bl -tag -width Ds -offset indent -compact
135 .It c
136 centimetre
137 .It i
138 inch
139 .It P
140 pica (~1/6 inch)
141 .It p
142 point (~1/72 inch)
143 .It f
144 synonym for
145 .Sq u
146 .It v
147 default vertical span
148 .It m
149 width of rendered
150 .Sq m
151 .Pq em
152 character
153 .It n
154 width of rendered
155 .Sq n
156 .Pq en
157 character
158 .It u
159 default horizontal span
160 .It M
161 mini-em (~1/100 em)
162 .El
163 .Pp
164 Using anything other than
165 .Sq m ,
166 .Sq n ,
167 .Sq u ,
168 or
169 .Sq v
170 is necessarily non-portable across output media.
171 .Pp
172 If a scaling unit is not provided, the numerical value is interpreted
173 under the default rules of
174 .Sq v
175 for vertical spaces and
176 .Sq u
177 for horizontal ones.
178 .Em Note :
179 this differs from
180 .Xr mdoc 7 ,
181 which, if a unit is not provided, will instead interpret the string as
182 literal text.
183 .Ss Sentence Spacing
184 When composing a manual, make sure that sentences end at the end of
185 a line.
186 By doing so, front-ends will be able to apply the proper amount of
187 spacing after the end of sentence (unescaped) period, exclamation mark,
188 or question mark followed by zero or more non-sentence closing
189 delimiters
190 .Po
191 .Sq \&) ,
192 .Sq \&] ,
193 .Sq \&' ,
194 .Sq \&"
195 .Pc .
196 .Sh MANUAL STRUCTURE
197 Each
198 .Nm
199 document must contain the
200 .Sx \&TH
201 macro describing the document's section and title.
202 It may occur anywhere in the document, although conventionally it
203 appears as the first macro.
204 .Pp
205 Beyond
206 .Sx \&TH ,
207 at least one macro or text node must appear in the document.
208 Documents are generally structured as follows:
209 .Bd -literal -offset indent
210 \&.TH FOO 1 2009-10-10
211 \&.SH NAME
212 \efBfoo\efR \e(en a description goes here
213 \&.\e\*q .SH LIBRARY
214 \&.\e\*q For sections 2 & 3 only.
215 \&.\e\*q Not used in OpenBSD.
216 \&.SH SYNOPSIS
217 \efBfoo\efR [\efB\e-options\efR] arguments...
218 \&.SH DESCRIPTION
219 The \efBfoo\efR utility processes files...
220 \&.\e\*q .SH IMPLEMENTATION NOTES
221 \&.\e\*q Not used in OpenBSD.
222 \&.\e\*q .SH RETURN VALUES
223 \&.\e\*q For sections 2, 3, & 9 only.
224 \&.\e\*q .SH ENVIRONMENT
225 \&.\e\*q For sections 1, 6, 7, & 8 only.
226 \&.\e\*q .SH FILES
227 \&.\e\*q .SH EXIT STATUS
228 \&.\e\*q For sections 1, 6, & 8 only.
229 \&.\e\*q .SH EXAMPLES
230 \&.\e\*q .SH DIAGNOSTICS
231 \&.\e\*q For sections 1, 4, 6, 7, & 8 only.
232 \&.\e\*q .SH ERRORS
233 \&.\e\*q For sections 2, 3, & 9 only.
234 \&.\e\*q .SH SEE ALSO
235 \&.\e\*q .BR foo ( 1 )
236 \&.\e\*q .SH STANDARDS
237 \&.\e\*q .SH HISTORY
238 \&.\e\*q .SH AUTHORS
239 \&.\e\*q .SH CAVEATS
240 \&.\e\*q .SH BUGS
241 \&.\e\*q .SH SECURITY CONSIDERATIONS
242 \&.\e\*q Not used in OpenBSD.
243 .Ed
244 .Pp
245 The sections in a
246 .Nm
247 document are conventionally ordered as they appear above.
248 Sections should be composed as follows:
249 .Bl -ohang -offset indent
250 .It Em NAME
251 The name(s) and a short description of the documented material.
252 The syntax for this is generally as follows:
253 .Pp
254 .D1 \efBname\efR \e(en description
255 .It Em LIBRARY
256 The name of the library containing the documented material, which is
257 assumed to be a function in a section 2 or 3 manual.
258 For functions in the C library, this may be as follows:
259 .Pp
260 .D1 Standard C Library (libc, -lc)
261 .It Em SYNOPSIS
262 Documents the utility invocation syntax, function call syntax, or device
263 configuration.
264 .Pp
265 For the first, utilities (sections 1, 6, and 8), this is
266 generally structured as follows:
267 .Pp
268 .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
269 .Pp
270 For the second, function calls (sections 2, 3, 9):
271 .Pp
272 .D1 \&.B char *name(char *\efIarg\efR);
273 .Pp
274 And for the third, configurations (section 4):
275 .Pp
276 .D1 \&.B name* at cardbus ? function ?
277 .Pp
278 Manuals not in these sections generally don't need a
279 .Em SYNOPSIS .
280 .It Em DESCRIPTION
281 This expands upon the brief, one-line description in
282 .Em NAME .
283 It usually contains a break-down of the options (if documenting a
284 command).
285 .It Em IMPLEMENTATION NOTES
286 Implementation-specific notes should be kept here.
287 This is useful when implementing standard functions that may have side
288 effects or notable algorithmic implications.
289 .It Em RETURN VALUES
290 This section documents the return values of functions in sections 2, 3, and 9.
291 .It Em ENVIRONMENT
292 Documents any usages of environment variables, e.g.,
293 .Xr environ 7 .
294 .It Em FILES
295 Documents files used.
296 It's helpful to document both the file name and a short description of how
297 the file is used (created, modified, etc.).
298 .It Em EXIT STATUS
299 This section documents the command exit status for
300 section 1, 6, and 8 utilities.
301 Historically, this information was described in
302 .Em DIAGNOSTICS ,
303 a practise that is now discouraged.
304 .It Em EXAMPLES
305 Example usages.
306 This often contains snippets of well-formed,
307 well-tested invocations.
308 Make sure that examples work properly!
309 .It Em DIAGNOSTICS
310 Documents error conditions.
311 This is most useful in section 4 manuals.
312 Historically, this section was used in place of
313 .Em EXIT STATUS
314 for manuals in sections 1, 6, and 8; however, this practise is
315 discouraged.
316 .It Em ERRORS
317 Documents error handling in sections 2, 3, and 9.
318 .It Em SEE ALSO
319 References other manuals with related topics.
320 This section should exist for most manuals.
321 .Pp
322 .D1 \&.BR bar \&( 1 \&),
323 .Pp
324 Cross-references should conventionally be ordered
325 first by section, then alphabetically.
326 .It Em STANDARDS
327 References any standards implemented or used, such as
328 .Pp
329 .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
330 .Pp
331 If not adhering to any standards, the
332 .Em HISTORY
333 section should be used.
334 .It Em HISTORY
335 A brief history of the subject, including where support first appeared.
336 .It Em AUTHORS
337 Credits to the person or persons who wrote the code and/or documentation.
338 Authors should generally be noted by both name and email address.
339 .It Em CAVEATS
340 Common misuses and misunderstandings should be explained
341 in this section.
342 .It Em BUGS
343 Known bugs, limitations, and work-arounds should be described
344 in this section.
345 .It Em SECURITY CONSIDERATIONS
346 Documents any security precautions that operators should consider.
347 .El
348 .Sh MACRO SYNTAX
349 Macros are one to three characters in length and begin with a
350 control character,
351 .Sq \&. ,
352 at the beginning of the line.
353 The
354 .Sq \(aq
355 macro control character is also accepted.
356 An arbitrary amount of whitespace (spaces or tabs) may sit between the
357 control character and the macro name.
358 Thus, the following are equivalent:
359 .Bd -literal -offset indent
360 \&.PP
361 \&.\ \ \ PP
362 .Ed
363 .Pp
364 To include space characters in macro arguments, arguments may be quoted;
365 see the
366 .Sq MACRO SYNTAX
367 section in the
368 .Xr roff 7
369 manual for details.
370 .Pp
371 The
372 .Nm
373 macros are classified by scope: line scope or block scope.
374 Line macros are only scoped to the current line (and, in some
375 situations, the subsequent line).
376 Block macros are scoped to the current line and subsequent lines until
377 closed by another block macro.
378 .Ss Line Macros
379 Line macros are generally scoped to the current line, with the body
380 consisting of zero or more arguments.
381 If a macro is scoped to the next line and the line arguments are empty,
382 the next line, which must be text, is used instead.
383 Thus:
384 .Bd -literal -offset indent
385 \&.I
386 foo
387 .Ed
388 .Pp
389 is equivalent to
390 .Sq \&.I foo .
391 If next-line macros are invoked consecutively, only the last is used.
392 If a next-line macro is followed by a non-next-line macro, an error is
393 raised, except for
394 .Sx \&br ,
395 .Sx \&sp ,
396 and
397 .Sx \&na .
398 .Pp
399 The syntax is as follows:
400 .Bd -literal -offset indent
401 \&.YO \(lBbody...\(rB
402 \(lBbody...\(rB
403 .Ed
404 .Pp
405 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX"
406 .It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes
407 .It Sx \&AT  Ta    <=1       Ta    current   Ta    \&
408 .It Sx \&B   Ta    n         Ta    next-line Ta    \&
409 .It Sx \&BI  Ta    n         Ta    current   Ta    \&
410 .It Sx \&BR  Ta    n         Ta    current   Ta    \&
411 .It Sx \&DT  Ta    0         Ta    current   Ta    \&
412 .It Sx \&I   Ta    n         Ta    next-line Ta    \&
413 .It Sx \&IB  Ta    n         Ta    current   Ta    \&
414 .It Sx \&IR  Ta    n         Ta    current   Ta    \&
415 .It Sx \&R   Ta    n         Ta    next-line Ta    \&
416 .It Sx \&RB  Ta    n         Ta    current   Ta    \&
417 .It Sx \&RI  Ta    n         Ta    current   Ta    \&
418 .It Sx \&SB  Ta    n         Ta    next-line Ta    \&
419 .It Sx \&SM  Ta    n         Ta    next-line Ta    \&
420 .It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
421 .It Sx \&UC  Ta    <=1       Ta    current   Ta    \&
422 .It Sx \&br  Ta    0         Ta    current   Ta    compat
423 .It Sx \&fi  Ta    0         Ta    current   Ta    compat
424 .It Sx \&ft  Ta    1         Ta    current   Ta    compat
425 .It Sx \&in  Ta    1         Ta    current   Ta    compat
426 .It Sx \&na  Ta    0         Ta    current   Ta    compat
427 .It Sx \&nf  Ta    0         Ta    current   Ta    compat
428 .It Sx \&sp  Ta    1         Ta    current   Ta    compat
429 .El
430 .Pp
431 Macros marked as
432 .Qq compat
433 are included for compatibility with the significant corpus of existing
434 manuals that mix dialects of roff.
435 These macros should not be used for portable
436 .Nm
437 manuals.
438 .Ss Block Macros
439 Block macros comprise a head and body.
440 As with in-line macros, the head is scoped to the current line and, in
441 one circumstance, the next line (the next-line stipulations as in
442 .Sx Line Macros
443 apply here as well).
444 .Pp
445 The syntax is as follows:
446 .Bd -literal -offset indent
447 \&.YO \(lBhead...\(rB
448 \(lBhead...\(rB
449 \(lBbody...\(rB
450 .Ed
451 .Pp
452 The closure of body scope may be to the section, where a macro is closed
453 by
454 .Sx \&SH ;
455 sub-section, closed by a section or
456 .Sx \&SS ;
457 part, closed by a section, sub-section, or
458 .Sx \&RE ;
459 or paragraph, closed by a section, sub-section, part,
460 .Sx \&HP ,
461 .Sx \&IP ,
462 .Sx \&LP ,
463 .Sx \&P ,
464 .Sx \&PP ,
465 or
466 .Sx \&TP .
467 No closure refers to an explicit block closing macro.
468 .Pp
469 As a rule, block macros may not be nested; thus, calling a block macro
470 while another block macro scope is open, and the open scope is not
471 implicitly closed, is syntactically incorrect.
472 .Pp
473 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX"
474 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope  Ta Em Notes
475 .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
476 .It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&
477 .It Sx \&LP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
478 .It Sx \&P   Ta    0         Ta    current    Ta    paragraph   Ta    \&
479 .It Sx \&PP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
480 .It Sx \&RE  Ta    0         Ta    current    Ta    none        Ta    compat
481 .It Sx \&RS  Ta    1         Ta    current    Ta    part        Ta    compat
482 .It Sx \&SH  Ta    >0        Ta    next-line  Ta    section     Ta    \&
483 .It Sx \&SS  Ta    >0        Ta    next-line  Ta    sub-section Ta    \&
484 .It Sx \&TP  Ta    n         Ta    next-line  Ta    paragraph   Ta    \&
485 .El
486 .Pp
487 Macros marked
488 .Qq compat
489 are as mentioned in
490 .Sx Line Macros .
491 .Pp
492 If a block macro is next-line scoped, it may only be followed by in-line
493 macros for decorating text.
494 .Sh REFERENCE
495 This section is a canonical reference to all macros, arranged
496 alphabetically.
497 For the scoping of individual macros, see
498 .Sx MACRO SYNTAX .
499 .Ss \&AT
500 Sets the volume for the footer for compatibility with man pages from
501 .Tn AT&T UNIX
502 releases.
503 The optional arguments specify which release it is from.
504 .Ss \&B
505 Text is rendered in bold face.
506 .Pp
507 See also
508 .Sx \&I
509 and
510 .Sx \&R .
511 .Ss \&BI
512 Text is rendered alternately in bold face and italic.
513 Thus,
514 .Sq .BI this word and that
515 causes
516 .Sq this
517 and
518 .Sq and
519 to render in bold face, while
520 .Sq word
521 and
522 .Sq that
523 render in italics.
524 Whitespace between arguments is omitted in output.
525 .Pp
526 Examples:
527 .Pp
528 .Dl \&.BI bold italic bold italic
529 .Pp
530 The output of this example will be emboldened
531 .Dq bold
532 and italicised
533 .Dq italic ,
534 with spaces stripped between arguments.
535 .Pp
536 See also
537 .Sx \&IB ,
538 .Sx \&BR ,
539 .Sx \&RB ,
540 .Sx \&RI ,
541 and
542 .Sx \&IR .
543 .Ss \&BR
544 Text is rendered alternately in bold face and roman (the default font).
545 Whitespace between arguments is omitted in output.
546 .Pp
547 See
548 .Sx \&BI
549 for an equivalent example.
550 .Pp
551 See also
552 .Sx \&BI ,
553 .Sx \&IB ,
554 .Sx \&RB ,
555 .Sx \&RI ,
556 and
557 .Sx \&IR .
558 .Ss \&DT
559 Has no effect.
560 Included for compatibility.
561 .Ss \&HP
562 Begin a paragraph whose initial output line is left-justified, but
563 subsequent output lines are indented, with the following syntax:
564 .Bd -filled -offset indent
565 .Pf \. Sx \&HP
566 .Op Cm width
567 .Ed
568 .Pp
569 The
570 .Cm width
571 argument must conform to
572 .Sx Scaling Widths .
573 If specified, it's saved for later paragraph left-margins; if unspecified, the
574 saved or default width is used.
575 .Pp
576 See also
577 .Sx \&IP ,
578 .Sx \&LP ,
579 .Sx \&P ,
580 .Sx \&PP ,
581 and
582 .Sx \&TP .
583 .Ss \&I
584 Text is rendered in italics.
585 .Pp
586 See also
587 .Sx \&B
588 and
589 .Sx \&R .
590 .Ss \&IB
591 Text is rendered alternately in italics and bold face.
592 Whitespace between arguments is omitted in output.
593 .Pp
594 See
595 .Sx \&BI
596 for an equivalent example.
597 .Pp
598 See also
599 .Sx \&BI ,
600 .Sx \&BR ,
601 .Sx \&RB ,
602 .Sx \&RI ,
603 and
604 .Sx \&IR .
605 .Ss \&IP
606 Begin an indented paragraph with the following syntax:
607 .Bd -filled -offset indent
608 .Pf \. Sx \&IP
609 .Op Cm head Op Cm width
610 .Ed
611 .Pp
612 The
613 .Cm width
614 argument defines the width of the left margin and is defined by
615 .Sx Scaling Widths .
616 It's saved for later paragraph left-margins; if unspecified, the saved or
617 default width is used.
618 .Pp
619 The
620 .Cm head
621 argument is used as a leading term, flushed to the left margin.
622 This is useful for bulleted paragraphs and so on.
623 .Pp
624 See also
625 .Sx \&HP ,
626 .Sx \&LP ,
627 .Sx \&P ,
628 .Sx \&PP ,
629 and
630 .Sx \&TP .
631 .Ss \&IR
632 Text is rendered alternately in italics and roman (the default font).
633 Whitespace between arguments is omitted in output.
634 .Pp
635 See
636 .Sx \&BI
637 for an equivalent example.
638 .Pp
639 See also
640 .Sx \&BI ,
641 .Sx \&IB ,
642 .Sx \&BR ,
643 .Sx \&RB ,
644 and
645 .Sx \&RI .
646 .Ss \&LP
647 Begin an undecorated paragraph.
648 The scope of a paragraph is closed by a subsequent paragraph,
649 sub-section, section, or end of file.
650 The saved paragraph left-margin width is reset to the default.
651 .Pp
652 See also
653 .Sx \&HP ,
654 .Sx \&IP ,
655 .Sx \&P ,
656 .Sx \&PP ,
657 and
658 .Sx \&TP .
659 .Ss \&P
660 Synonym for
661 .Sx \&LP .
662 .Pp
663 See also
664 .Sx \&HP ,
665 .Sx \&IP ,
666 .Sx \&LP ,
667 .Sx \&PP ,
668 and
669 .Sx \&TP .
670 .Ss \&PP
671 Synonym for
672 .Sx \&LP .
673 .Pp
674 See also
675 .Sx \&HP ,
676 .Sx \&IP ,
677 .Sx \&LP ,
678 .Sx \&P ,
679 and
680 .Sx \&TP .
681 .Ss \&R
682 Text is rendered in roman (the default font).
683 .Pp
684 See also
685 .Sx \&I
686 and
687 .Sx \&B .
688 .Ss \&RB
689 Text is rendered alternately in roman (the default font) and bold face.
690 Whitespace between arguments is omitted in output.
691 .Pp
692 See
693 .Sx \&BI
694 for an equivalent example.
695 .Pp
696 See also
697 .Sx \&BI ,
698 .Sx \&IB ,
699 .Sx \&BR ,
700 .Sx \&RI ,
701 and
702 .Sx \&IR .
703 .Ss \&RE
704 Explicitly close out the scope of a prior
705 .Sx \&RS .
706 .Ss \&RI
707 Text is rendered alternately in roman (the default font) and italics.
708 Whitespace between arguments is omitted in output.
709 .Pp
710 See
711 .Sx \&BI
712 for an equivalent example.
713 .Pp
714 See also
715 .Sx \&BI ,
716 .Sx \&IB ,
717 .Sx \&BR ,
718 .Sx \&RB ,
719 and
720 .Sx \&IR .
721 .Ss \&RS
722 Begin a part setting the left margin.
723 The left margin controls the offset, following an initial indentation,
724 to un-indented text such as that of
725 .Sx \&PP .
726 This has the following syntax:
727 .Bd -filled -offset indent
728 .Pf \. Sx \&Rs
729 .Op Cm width
730 .Ed
731 .Pp
732 The
733 .Cm width
734 argument must conform to
735 .Sx Scaling Widths .
736 If not specified, the saved or default width is used.
737 .Ss \&SB
738 Text is rendered in small size (one point smaller than the default font)
739 bold face.
740 .Ss \&SH
741 Begin a section.
742 The scope of a section is only closed by another section or the end of
743 file.
744 The paragraph left-margin width is reset to the default.
745 .Ss \&SM
746 Text is rendered in small size (one point smaller than the default
747 font).
748 .Ss \&SS
749 Begin a sub-section.
750 The scope of a sub-section is closed by a subsequent sub-section,
751 section, or end of file.
752 The paragraph left-margin width is reset to the default.
753 .Ss \&TH
754 Sets the title of the manual page with the following syntax:
755 .Bd -filled -offset indent
756 .Pf \. Sx \&TH
757 .Ar title section date
758 .Op Ar source Op Ar volume
759 .Ed
760 .Pp
761 Conventionally, the document
762 .Ar title
763 is given in all caps.
764 The recommended
765 .Ar date
766 format is
767 .Sy YYYY-MM-DD
768 as specified in the ISO-8601 standard;
769 if the argument does not conform, it is printed verbatim.
770 If the
771 .Ar date
772 is empty or not specified, the current date is used.
773 The optional
774 .Ar source
775 string specifies the organisation providing the utility.
776 The
777 .Ar volume
778 string replaces the default rendered volume, which is dictated by the
779 manual section.
780 .Pp
781 Examples:
782 .Pp
783 .Dl \&.TH CVS 5 "1992-02-12" GNU
784 .Ss \&TP
785 Begin a paragraph where the head, if exceeding the indentation width, is
786 followed by a newline; if not, the body follows on the same line after a
787 buffer to the indentation width.
788 Subsequent output lines are indented.
789 The syntax is as follows:
790 .Bd -filled -offset indent
791 .Pf \. Sx \&TP
792 .Op Cm width
793 .Ed
794 .Pp
795 The
796 .Cm width
797 argument must conform to
798 .Sx Scaling Widths .
799 If specified, it's saved for later paragraph left-margins; if
800 unspecified, the saved or default width is used.
801 .Pp
802 See also
803 .Sx \&HP ,
804 .Sx \&IP ,
805 .Sx \&LP ,
806 .Sx \&P ,
807 and
808 .Sx \&PP .
809 .Ss \&UC
810 Sets the volume for the footer for compatibility with man pages from
811 BSD releases.
812 The optional first argument specifies which release it is from.
813 .Ss \&br
814 Breaks the current line.
815 Consecutive invocations have no further effect.
816 .Pp
817 See also
818 .Sx \&sp .
819 .Ss \&fi
820 End literal mode begun by
821 .Sx \&nf .
822 .Ss \&ft
823 Change the current font mode.
824 See
825 .Sx Text Decoration
826 for a listing of available font modes.
827 .Ss \&in
828 Indent relative to the current indentation:
829 .Pp
830 .D1 Pf \. Sx \&in Op Cm width
831 .Pp
832 If
833 .Cm width
834 is signed, the new offset is relative.
835 Otherwise, it is absolute.
836 This value is reset upon the next paragraph, section, or sub-section.
837 .Ss \&na
838 Don't align to the right margin.
839 .Ss \&nf
840 Begin literal mode: all subsequent free-form lines have their end of
841 line boundaries preserved.
842 May be ended by
843 .Sx \&fi .
844 .Ss \&sp
845 Insert vertical spaces into output with the following syntax:
846 .Bd -filled -offset indent
847 .Pf \. Sx \&sp
848 .Op Cm height
849 .Ed
850 .Pp
851 Insert
852 .Cm height
853 spaces, which must conform to
854 .Sx Scaling Widths .
855 If 0, this is equivalent to the
856 .Sx \&br
857 macro.
858 Defaults to 1, if unspecified.
859 .Pp
860 See also
861 .Sx \&br .
862 .Sh COMPATIBILITY
863 This section documents areas of questionable portability between
864 implementations of the
865 .Nm
866 language.
867 .Pp
868 .Bl -dash -compact
869 .It
870 In quoted literals, GNU troff allowed pair-wise double-quotes to produce
871 a standalone double-quote in formatted output.
872 It is not known whether this behaviour is exhibited by other formatters.
873 .It
874 troff suppresses a newline before
875 .Sq \(aq
876 macro output; in mandoc, it is an alias for the standard
877 .Sq \&.
878 control character.
879 .It
880 The
881 .Sq \eh
882 .Pq horizontal position ,
883 .Sq \ev
884 .Pq vertical position ,
885 .Sq \em
886 .Pq text colour ,
887 .Sq \eM
888 .Pq text filling colour ,
889 .Sq \ez
890 .Pq zero-length character ,
891 .Sq \ew
892 .Pq string length ,
893 .Sq \ek
894 .Pq horizontal position marker ,
895 .Sq \eo
896 .Pq text overstrike ,
897 and
898 .Sq \es
899 .Pq text size
900 escape sequences are all discarded in mandoc.
901 .It
902 The
903 .Sq \ef
904 scaling unit is accepted by mandoc, but rendered as the default unit.
905 .It
906 The
907 .Sx \&sp
908 macro does not accept negative values in mandoc.
909 In GNU troff, this would result in strange behaviour.
910 .El
911 .Sh SEE ALSO
912 .Xr man 1 ,
913 .Xr mandoc 1 ,
914 .Xr eqn 7 ,
915 .Xr mandoc_char 7 ,
916 .Xr mdoc 7 ,
917 .Xr roff 7 ,
918 .Xr tbl 7
919 .Sh HISTORY
920 The
921 .Nm
922 language first appeared as a macro package for the roff typesetting
923 system in
924 .At v7 .
925 It was later rewritten by James Clark as a macro package for groff.
926 The stand-alone implementation that is part of the
927 .Xr mandoc 1
928 utility written by Kristaps Dzonsons appeared in
929 .Ox 4.6 .
930 .Sh AUTHORS
931 This
932 .Nm
933 reference was written by
934 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
935 .Sh CAVEATS
936 Do not use this language.
937 Use
938 .Xr mdoc 7 ,
939 instead.