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