xref: /freebsd/contrib/mandoc/man.7 (revision 0957b409)
1.\"	$Id: man.7,v 1.137 2018/04/05 22:12:33 schwarze Exp $
2.\"
3.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4.\" Copyright (c) 2011-2015 Ingo Schwarze <schwarze@openbsd.org>
5.\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
6.\"
7.\" Permission to use, copy, modify, and distribute this software for any
8.\" purpose with or without fee is hereby granted, provided that the above
9.\" copyright notice and this permission notice appear in all copies.
10.\"
11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18.\"
19.Dd $Mdocdate: April 5 2018 $
20.Dt MAN 7
21.Os
22.Sh NAME
23.Nm man
24.Nd legacy formatting language for manual pages
25.Sh DESCRIPTION
26Traditionally, the
27.Nm man
28language has been used to write
29.Ux
30manuals for the
31.Xr man 1
32utility.
33It supports limited control of presentational details like fonts,
34indentation and spacing.
35This reference document describes the structure of manual pages
36and the syntax and usage of the man language.
37.Pp
38.Bf -emphasis
39Do not use
40.Nm
41to write your manuals:
42.Ef
43It lacks support for semantic markup.
44Use the
45.Xr mdoc 7
46language, instead.
47.Pp
48In a
49.Nm
50document, lines beginning with the control character
51.Sq \&.
52are called
53.Dq macro lines .
54The first word is the macro name.
55It usually consists of two capital letters.
56For a list of available macros, see
57.Sx MACRO OVERVIEW .
58The words following the macro name are arguments to the macro.
59.Pp
60Lines not beginning with the control character are called
61.Dq text lines .
62They provide free-form text to be printed; the formatting of the text
63depends on the respective processing context:
64.Bd -literal -offset indent
65\&.SH Macro lines change control state.
66Text lines are interpreted within the current state.
67.Ed
68.Pp
69Many aspects of the basic syntax of the
70.Nm
71language are based on the
72.Xr roff 7
73language; see the
74.Em LANGUAGE SYNTAX
75and
76.Em MACRO SYNTAX
77sections in the
78.Xr roff 7
79manual for details, in particular regarding
80comments, escape sequences, whitespace, and quoting.
81.Sh MANUAL STRUCTURE
82Each
83.Nm
84document must contain the
85.Sx \&TH
86macro describing the document's section and title.
87It may occur anywhere in the document, although conventionally it
88appears as the first macro.
89.Pp
90Beyond
91.Sx \&TH ,
92at least one macro or text line must appear in the document.
93.Pp
94The following is a well-formed skeleton
95.Nm
96file for a utility
97.Qq progname :
98.Bd -literal -offset indent
99\&.TH PROGNAME 1 2009-10-10
100\&.SH NAME
101\efBprogname\efR \e(en one line about what it does
102\&.\e\(dq .SH LIBRARY
103\&.\e\(dq For sections 2, 3, and 9 only.
104\&.\e\(dq Not used in OpenBSD.
105\&.SH SYNOPSIS
106\efBprogname\efR [\efB\e-options\efR] \efIfile ...\efR
107\&.SH DESCRIPTION
108The \efBfoo\efR utility processes files ...
109\&.\e\(dq .Sh CONTEXT
110\&.\e\(dq For section 9 functions only.
111\&.\e\(dq .SH IMPLEMENTATION NOTES
112\&.\e\(dq Not used in OpenBSD.
113\&.\e\(dq .SH RETURN VALUES
114\&.\e\(dq For sections 2, 3, and 9 function return values only.
115\&.\e\(dq .SH ENVIRONMENT
116\&.\e\(dq For sections 1, 6, 7, and 8 only.
117\&.\e\(dq .SH FILES
118\&.\e\(dq .SH EXIT STATUS
119\&.\e\(dq For sections 1, 6, and 8 only.
120\&.\e\(dq .SH EXAMPLES
121\&.\e\(dq .SH DIAGNOSTICS
122\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
123\&.\e\(dq .SH ERRORS
124\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
125\&.\e\(dq .SH SEE ALSO
126\&.\e\(dq .BR foobar ( 1 )
127\&.\e\(dq .SH STANDARDS
128\&.\e\(dq .SH HISTORY
129\&.\e\(dq .SH AUTHORS
130\&.\e\(dq .SH CAVEATS
131\&.\e\(dq .SH BUGS
132\&.\e\(dq .SH SECURITY CONSIDERATIONS
133\&.\e\(dq Not used in OpenBSD.
134.Ed
135.Pp
136The sections in a
137.Nm
138document are conventionally ordered as they appear above.
139Sections should be composed as follows:
140.Bl -ohang -offset indent
141.It Em NAME
142The name(s) and a short description of the documented material.
143The syntax for this is generally as follows:
144.Pp
145.D1 \efBname\efR \e(en description
146.It Em LIBRARY
147The name of the library containing the documented material, which is
148assumed to be a function in a section 2 or 3 manual.
149For functions in the C library, this may be as follows:
150.Pp
151.D1 Standard C Library (libc, -lc)
152.It Em SYNOPSIS
153Documents the utility invocation syntax, function call syntax, or device
154configuration.
155.Pp
156For the first, utilities (sections 1, 6, and 8), this is
157generally structured as follows:
158.Pp
159.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
160.Pp
161For the second, function calls (sections 2, 3, 9):
162.Pp
163.D1 \&.B char *name(char *\efIarg\efR);
164.Pp
165And for the third, configurations (section 4):
166.Pp
167.D1 \&.B name* at cardbus ? function ?
168.Pp
169Manuals not in these sections generally don't need a
170.Em SYNOPSIS .
171.It Em DESCRIPTION
172This expands upon the brief, one-line description in
173.Em NAME .
174It usually contains a break-down of the options (if documenting a
175command).
176.It Em CONTEXT
177This section lists the contexts in which functions can be called in section 9.
178The contexts are autoconf, process, or interrupt.
179.It Em IMPLEMENTATION NOTES
180Implementation-specific notes should be kept here.
181This is useful when implementing standard functions that may have side
182effects or notable algorithmic implications.
183.It Em RETURN VALUES
184This section documents the return values of functions in sections 2, 3, and 9.
185.It Em ENVIRONMENT
186Documents any usages of environment variables, e.g.,
187.Xr environ 7 .
188.It Em FILES
189Documents files used.
190It's helpful to document both the file name and a short description of how
191the file is used (created, modified, etc.).
192.It Em EXIT STATUS
193This section documents the command exit status for
194section 1, 6, and 8 utilities.
195Historically, this information was described in
196.Em DIAGNOSTICS ,
197a practise that is now discouraged.
198.It Em EXAMPLES
199Example usages.
200This often contains snippets of well-formed,
201well-tested invocations.
202Make sure that examples work properly!
203.It Em DIAGNOSTICS
204Documents error conditions.
205In section 4 and 9 manuals, these are usually messages
206printed by the kernel to the console and to the kernel log.
207In section 1, 6, 7, and 8, these are usually messages
208printed by userland programs to the standard error output.
209.Pp
210Historically, this section was used in place of
211.Em EXIT STATUS
212for manuals in sections 1, 6, and 8; however, this practise is
213discouraged.
214.It Em ERRORS
215Documents
216.Xr errno 2
217settings in sections 2, 3, 4, and 9.
218.It Em SEE ALSO
219References other manuals with related topics.
220This section should exist for most manuals.
221.Pp
222.D1 \&.BR bar \&( 1 \&),
223.Pp
224Cross-references should conventionally be ordered
225first by section, then alphabetically.
226.It Em STANDARDS
227References any standards implemented or used, such as
228.Pp
229.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
230.Pp
231If not adhering to any standards, the
232.Em HISTORY
233section should be used.
234.It Em HISTORY
235A brief history of the subject, including where support first appeared.
236.It Em AUTHORS
237Credits to the person or persons who wrote the code and/or documentation.
238Authors should generally be noted by both name and email address.
239.It Em CAVEATS
240Common misuses and misunderstandings should be explained
241in this section.
242.It Em BUGS
243Known bugs, limitations, and work-arounds should be described
244in this section.
245.It Em SECURITY CONSIDERATIONS
246Documents any security precautions that operators should consider.
247.El
248.Sh MACRO OVERVIEW
249This overview is sorted such that macros of similar purpose are listed
250together, to help find the best macro for any given purpose.
251Deprecated macros are not included in the overview, but can be found
252in the alphabetical reference below.
253.Ss Page header and footer meta-data
254.Bl -column "PP, LP, P" description
255.It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
256.It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
257.It Sx UC Ta display BSD version in the page footer (<= 1 argument)
258.El
259.Ss Sections and paragraphs
260.Bl -column "PP, LP, P" description
261.It Sx SH Ta section header (one line)
262.It Sx SS Ta subsection header (one line)
263.It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
264.It Sx RS , RE Ta reset the left margin: Op Ar width
265.It Sx IP Ta indented paragraph: Op Ar head Op Ar width
266.It Sx TP Ta tagged paragraph: Op Ar width
267.It Sx HP Ta hanged paragraph: Op Ar width
268.It Sx PD Ta set vertical paragraph distance: Op Ar height
269.It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
270.It Sx in Ta additional indent: Op Ar width
271.El
272.Ss Physical markup
273.Bl -column "PP, LP, P" description
274.It Sx B Ta boldface font
275.It Sx I Ta italic font
276.It Sx SB Ta small boldface font
277.It Sx SM Ta small roman font
278.It Sx BI Ta alternate between boldface and italic fonts
279.It Sx BR Ta alternate between boldface and roman fonts
280.It Sx IB Ta alternate between italic and boldface fonts
281.It Sx IR Ta alternate between italic and roman fonts
282.It Sx RB Ta alternate between roman and boldface fonts
283.It Sx RI Ta alternate between roman and italic fonts
284.El
285.Sh MACRO REFERENCE
286This section is a canonical reference to all macros, arranged
287alphabetically.
288For the scoping of individual macros, see
289.Sx MACRO SYNTAX .
290.Ss \&AT
291Sets the volume for the footer for compatibility with man pages from
292.At
293releases.
294The optional arguments specify which release it is from.
295.Ss \&B
296Text is rendered in bold face.
297.Pp
298See also
299.Sx \&I .
300.Ss \&BI
301Text is rendered alternately in bold face and italic.
302Thus,
303.Sq .BI this word and that
304causes
305.Sq this
306and
307.Sq and
308to render in bold face, while
309.Sq word
310and
311.Sq that
312render in italics.
313Whitespace between arguments is omitted in output.
314.Pp
315Examples:
316.Pp
317.Dl \&.BI bold italic bold italic
318.Pp
319The output of this example will be emboldened
320.Dq bold
321and italicised
322.Dq italic ,
323with spaces stripped between arguments.
324.Pp
325See also
326.Sx \&IB ,
327.Sx \&BR ,
328.Sx \&RB ,
329.Sx \&RI ,
330and
331.Sx \&IR .
332.Ss \&BR
333Text is rendered alternately in bold face and roman (the default font).
334Whitespace between arguments is omitted in output.
335.Pp
336See
337.Sx \&BI
338for an equivalent example.
339.Pp
340See also
341.Sx \&BI ,
342.Sx \&IB ,
343.Sx \&RB ,
344.Sx \&RI ,
345and
346.Sx \&IR .
347.Ss \&DT
348Restore the default tabulator positions.
349They are at intervals of 0.5 inches.
350This has no effect unless the tabulator positions were changed with the
351.Xr roff 7
352.Ic \&ta
353request.
354.Ss \&EE
355This is a non-standard GNU extension, included only for compatibility.
356In
357.Xr mandoc 1 ,
358it does the same as
359.Sx \&fi .
360.Ss \&EX
361This is a non-standard GNU extension, included only for compatibility.
362In
363.Xr mandoc 1 ,
364it does the same as
365.Sx \&nf .
366.Ss \&HP
367Begin a paragraph whose initial output line is left-justified, but
368subsequent output lines are indented, with the following syntax:
369.Bd -filled -offset indent
370.Pf \. Sx \&HP
371.Op Ar width
372.Ed
373.Pp
374The
375.Ar width
376argument is a
377.Xr roff 7
378scaling width.
379If specified, it's saved for later paragraph left-margins; if unspecified, the
380saved or default width is used.
381.Pp
382See also
383.Sx \&IP ,
384.Sx \&LP ,
385.Sx \&P ,
386.Sx \&PP ,
387and
388.Sx \&TP .
389.Ss \&I
390Text is rendered in italics.
391.Pp
392See also
393.Sx \&B .
394.Ss \&IB
395Text is rendered alternately in italics and bold face.
396Whitespace between arguments is omitted in output.
397.Pp
398See
399.Sx \&BI
400for an equivalent example.
401.Pp
402See also
403.Sx \&BI ,
404.Sx \&BR ,
405.Sx \&RB ,
406.Sx \&RI ,
407and
408.Sx \&IR .
409.Ss \&IP
410Begin an indented paragraph with the following syntax:
411.Bd -filled -offset indent
412.Pf \. Sx \&IP
413.Op Ar head Op Ar width
414.Ed
415.Pp
416The
417.Ar width
418argument is a
419.Xr roff 7
420scaling width defining the left margin.
421It's saved for later paragraph left-margins; if unspecified, the saved or
422default width is used.
423.Pp
424The
425.Ar head
426argument is used as a leading term, flushed to the left margin.
427This is useful for bulleted paragraphs and so on.
428.Pp
429See also
430.Sx \&HP ,
431.Sx \&LP ,
432.Sx \&P ,
433.Sx \&PP ,
434and
435.Sx \&TP .
436.Ss \&IR
437Text is rendered alternately in italics and roman (the default font).
438Whitespace between arguments is omitted in output.
439.Pp
440See
441.Sx \&BI
442for an equivalent example.
443.Pp
444See also
445.Sx \&BI ,
446.Sx \&IB ,
447.Sx \&BR ,
448.Sx \&RB ,
449and
450.Sx \&RI .
451.Ss \&LP
452Begin an undecorated paragraph.
453The scope of a paragraph is closed by a subsequent paragraph,
454sub-section, section, or end of file.
455The saved paragraph left-margin width is reset to the default.
456.Pp
457See also
458.Sx \&HP ,
459.Sx \&IP ,
460.Sx \&P ,
461.Sx \&PP ,
462and
463.Sx \&TP .
464.Ss \&ME
465End a mailto block.
466This is a non-standard GNU extension, included only for compatibility.
467See
468.Sx \&MT .
469.Ss \&MT
470Begin a mailto block.
471This is a non-standard GNU extension, included only for compatibility.
472It has the following syntax:
473.Bd -literal -offset indent
474.Pf \. Sx \&MT Ar address
475link description to be shown
476.Pf \. Sx ME
477.Ed
478.Ss \&OP
479Optional command-line argument.
480This is a non-standard GNU extension, included only for compatibility.
481It has the following syntax:
482.Bd -filled -offset indent
483.Pf \. Sx \&OP
484.Ar key Op Ar value
485.Ed
486.Pp
487The
488.Ar key
489is usually a command-line flag and
490.Ar value
491its argument.
492.Ss \&P
493Synonym for
494.Sx \&LP .
495.Pp
496See also
497.Sx \&HP ,
498.Sx \&IP ,
499.Sx \&LP ,
500.Sx \&PP ,
501and
502.Sx \&TP .
503.Ss \&PD
504Specify the vertical space to be inserted before each new paragraph.
505.br
506The syntax is as follows:
507.Bd -filled -offset indent
508.Pf \. Sx \&PD
509.Op Ar height
510.Ed
511.Pp
512The
513.Ar height
514argument is a
515.Xr roff 7
516scaling width.
517It defaults to
518.Cm 1v .
519If the unit is omitted,
520.Cm v
521is assumed.
522.Pp
523This macro affects the spacing before any subsequent instances of
524.Sx \&HP ,
525.Sx \&IP ,
526.Sx \&LP ,
527.Sx \&P ,
528.Sx \&PP ,
529.Sx \&SH ,
530.Sx \&SS ,
531and
532.Sx \&TP .
533.Ss \&PP
534Synonym for
535.Sx \&LP .
536.Pp
537See also
538.Sx \&HP ,
539.Sx \&IP ,
540.Sx \&LP ,
541.Sx \&P ,
542and
543.Sx \&TP .
544.Ss \&RB
545Text is rendered alternately in roman (the default font) and bold face.
546Whitespace between arguments is omitted in output.
547.Pp
548See
549.Sx \&BI
550for an equivalent example.
551.Pp
552See also
553.Sx \&BI ,
554.Sx \&IB ,
555.Sx \&BR ,
556.Sx \&RI ,
557and
558.Sx \&IR .
559.Ss \&RE
560Explicitly close out the scope of a prior
561.Sx \&RS .
562The default left margin is restored to the state before that
563.Sx \&RS
564invocation.
565.Pp
566The syntax is as follows:
567.Bd -filled -offset indent
568.Pf \. Sx \&RE
569.Op Ar level
570.Ed
571.Pp
572Without an argument, the most recent
573.Sx \&RS
574block is closed out.
575If
576.Ar level
577is 1, all open
578.Sx \&RS
579blocks are closed out.
580Otherwise,
581.Ar level No \(mi 1
582nested
583.Sx \&RS
584blocks remain open.
585.Ss \&RI
586Text is rendered alternately in roman (the default font) and italics.
587Whitespace between arguments is omitted in output.
588.Pp
589See
590.Sx \&BI
591for an equivalent example.
592.Pp
593See also
594.Sx \&BI ,
595.Sx \&IB ,
596.Sx \&BR ,
597.Sx \&RB ,
598and
599.Sx \&IR .
600.Ss \&RS
601Temporarily reset the default left margin.
602This has the following syntax:
603.Bd -filled -offset indent
604.Pf \. Sx \&RS
605.Op Ar width
606.Ed
607.Pp
608The
609.Ar width
610argument is a
611.Xr roff 7
612scaling width.
613If not specified, the saved or default width is used.
614.Pp
615See also
616.Sx \&RE .
617.Ss \&SB
618Text is rendered in small size (one point smaller than the default font)
619bold face.
620.Ss \&SH
621Begin a section.
622The scope of a section is only closed by another section or the end of
623file.
624The paragraph left-margin width is reset to the default.
625.Ss \&SM
626Text is rendered in small size (one point smaller than the default
627font).
628.Ss \&SS
629Begin a sub-section.
630The scope of a sub-section is closed by a subsequent sub-section,
631section, or end of file.
632The paragraph left-margin width is reset to the default.
633.Ss \&TH
634Sets the title of the manual page for use in the page header
635and footer with the following syntax:
636.Bd -filled -offset indent
637.Pf \. Sx \&TH
638.Ar title section date
639.Op Ar source Op Ar volume
640.Ed
641.Pp
642Conventionally, the document
643.Ar title
644is given in all caps.
645The recommended
646.Ar date
647format is
648.Sy YYYY-MM-DD
649as specified in the ISO-8601 standard;
650if the argument does not conform, it is printed verbatim.
651If the
652.Ar date
653is empty or not specified, the current date is used.
654The optional
655.Ar source
656string specifies the organisation providing the utility.
657When unspecified,
658.Xr mandoc 1
659uses its
660.Fl Ios
661argument.
662The
663.Ar volume
664string replaces the default rendered volume, which is dictated by the
665manual section.
666.Pp
667Examples:
668.Pp
669.Dl \&.TH CVS 5 "1992-02-12" GNU
670.Ss \&TP
671Begin a paragraph where the head, if exceeding the indentation width, is
672followed by a newline; if not, the body follows on the same line after a
673buffer to the indentation width.
674Subsequent output lines are indented.
675The syntax is as follows:
676.Bd -filled -offset indent
677.Pf \. Sx \&TP
678.Op Ar width
679.Ed
680.Pp
681The
682.Ar width
683argument is a
684.Xr roff 7
685scaling width.
686If specified, it's saved for later paragraph left-margins; if
687unspecified, the saved or default width is used.
688.Pp
689See also
690.Sx \&HP ,
691.Sx \&IP ,
692.Sx \&LP ,
693.Sx \&P ,
694and
695.Sx \&PP .
696.Ss \&UC
697Sets the volume for the footer for compatibility with man pages from
698.Bx
699releases.
700The optional first argument specifies which release it is from.
701.Ss \&UE
702End a uniform resource identifier block.
703This is a non-standard GNU extension, included only for compatibility.
704See
705.Sx \&UE .
706.Ss \&UR
707Begin a uniform resource identifier block.
708This is a non-standard GNU extension, included only for compatibility.
709It has the following syntax:
710.Bd -literal -offset indent
711.Pf \. Sx \&UR Ar uri
712link description to be shown
713.Pf \. Sx UE
714.Ed
715.Ss \&fi
716End literal mode begun by
717.Sx \&nf .
718.Ss \&in
719Indent relative to the current indentation:
720.Pp
721.D1 Pf \. Sx \&in Op Ar width
722.Pp
723If
724.Ar width
725is signed, the new offset is relative.
726Otherwise, it is absolute.
727This value is reset upon the next paragraph, section, or sub-section.
728.Ss \&nf
729Begin literal mode: all subsequent free-form lines have their end of
730line boundaries preserved.
731May be ended by
732.Sx \&fi .
733Literal mode is implicitly ended by
734.Sx \&SH
735or
736.Sx \&SS .
737.Sh MACRO SYNTAX
738The
739.Nm
740macros are classified by scope: line scope or block scope.
741Line macros are only scoped to the current line (and, in some
742situations, the subsequent line).
743Block macros are scoped to the current line and subsequent lines until
744closed by another block macro.
745.Ss Line Macros
746Line macros are generally scoped to the current line, with the body
747consisting of zero or more arguments.
748If a macro is scoped to the next line and the line arguments are empty,
749the next line, which must be text, is used instead.
750Thus:
751.Bd -literal -offset indent
752\&.I
753foo
754.Ed
755.Pp
756is equivalent to
757.Sq \&.I foo .
758If next-line macros are invoked consecutively, only the last is used.
759If a next-line macro is followed by a non-next-line macro, an error is
760raised.
761.Pp
762The syntax is as follows:
763.Bd -literal -offset indent
764\&.YO \(lBbody...\(rB
765\(lBbody...\(rB
766.Ed
767.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
768.It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes
769.It Sx \&AT  Ta    <=1       Ta    current   Ta    \&
770.It Sx \&B   Ta    n         Ta    next-line Ta    \&
771.It Sx \&BI  Ta    n         Ta    current   Ta    \&
772.It Sx \&BR  Ta    n         Ta    current   Ta    \&
773.It Sx \&DT  Ta    0         Ta    current   Ta    \&
774.It Sx \&EE  Ta    0         Ta    current   Ta    compat
775.It Sx \&EX  Ta    0         Ta    current   Ta    compat
776.It Sx \&I   Ta    n         Ta    next-line Ta    \&
777.It Sx \&IB  Ta    n         Ta    current   Ta    \&
778.It Sx \&IR  Ta    n         Ta    current   Ta    \&
779.It Sx \&OP  Ta    0, 1      Ta    current   Ta    compat
780.It Sx \&PD  Ta    1         Ta    current   Ta    \&
781.It Sx \&RB  Ta    n         Ta    current   Ta    \&
782.It Sx \&RI  Ta    n         Ta    current   Ta    \&
783.It Sx \&SB  Ta    n         Ta    next-line Ta    \&
784.It Sx \&SM  Ta    n         Ta    next-line Ta    \&
785.It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
786.It Sx \&UC  Ta    <=1       Ta    current   Ta    \&
787.It Sx \&fi  Ta    0         Ta    current   Ta    compat
788.It Sx \&in  Ta    1         Ta    current   Ta    compat
789.It Sx \&nf  Ta    0         Ta    current   Ta    compat
790.El
791.Pp
792Macros marked as
793.Qq compat
794are included for compatibility with the significant corpus of existing
795manuals that mix dialects of roff.
796These macros should not be used for portable
797.Nm
798manuals.
799.Ss Block Macros
800Block macros comprise a head and body.
801As with in-line macros, the head is scoped to the current line and, in
802one circumstance, the next line (the next-line stipulations as in
803.Sx Line Macros
804apply here as well).
805.Pp
806The syntax is as follows:
807.Bd -literal -offset indent
808\&.YO \(lBhead...\(rB
809\(lBhead...\(rB
810\(lBbody...\(rB
811.Ed
812.Pp
813The closure of body scope may be to the section, where a macro is closed
814by
815.Sx \&SH ;
816sub-section, closed by a section or
817.Sx \&SS ;
818part, closed by a section, sub-section, or
819.Sx \&RE ;
820or paragraph, closed by a section, sub-section, part,
821.Sx \&HP ,
822.Sx \&IP ,
823.Sx \&LP ,
824.Sx \&P ,
825.Sx \&PP ,
826or
827.Sx \&TP .
828No closure refers to an explicit block closing macro.
829.Pp
830As a rule, block macros may not be nested; thus, calling a block macro
831while another block macro scope is open, and the open scope is not
832implicitly closed, is syntactically incorrect.
833.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
834.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope  Ta Em Notes
835.It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
836.It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&
837.It Sx \&LP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
838.It Sx \&P   Ta    0         Ta    current    Ta    paragraph   Ta    \&
839.It Sx \&PP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
840.It Sx \&RE  Ta    0         Ta    current    Ta    none        Ta    compat
841.It Sx \&RS  Ta    1         Ta    current    Ta    part        Ta    compat
842.It Sx \&SH  Ta    >0        Ta    next-line  Ta    section     Ta    \&
843.It Sx \&SS  Ta    >0        Ta    next-line  Ta    sub-section Ta    \&
844.It Sx \&TP  Ta    n         Ta    next-line  Ta    paragraph   Ta    \&
845.It Sx \&UE  Ta    0         Ta    current    Ta    none        Ta    compat
846.It Sx \&UR  Ta    1         Ta    current    Ta    part        Ta    compat
847.El
848.Pp
849Macros marked
850.Qq compat
851are as mentioned in
852.Sx Line Macros .
853.Pp
854If a block macro is next-line scoped, it may only be followed by in-line
855macros for decorating text.
856.Ss Font handling
857In
858.Nm
859documents, both
860.Sx Physical markup
861macros and
862.Xr roff 7
863.Ql \ef
864font escape sequences can be used to choose fonts.
865In text lines, the effect of manual font selection by escape sequences
866only lasts until the next macro invocation; in macro lines, it only lasts
867until the end of the macro scope.
868Note that macros like
869.Sx \&BR
870open and close a font scope for each argument.
871.Sh SEE ALSO
872.Xr man 1 ,
873.Xr mandoc 1 ,
874.Xr eqn 7 ,
875.Xr mandoc_char 7 ,
876.Xr mdoc 7 ,
877.Xr roff 7 ,
878.Xr tbl 7
879.Sh HISTORY
880The
881.Nm
882language first appeared as a macro package for the roff typesetting
883system in
884.At v7 .
885It was later rewritten by James Clark as a macro package for groff.
886Eric S. Raymond wrote the extended
887.Nm
888macros for groff in 2007.
889The stand-alone implementation that is part of the
890.Xr mandoc 1
891utility written by Kristaps Dzonsons appeared in
892.Ox 4.6 .
893.Sh AUTHORS
894This
895.Nm
896reference was written by
897.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
898.Sh CAVEATS
899Do not use this language.
900Use
901.Xr mdoc 7 ,
902instead.
903