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