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