Import mdocml-1.13.1
[dragonfly.git] / contrib / mdocml / man.7
CommitLineData
070c62a6 1.\" $Id: man.7,v 1.127 2014/06/22 16:39:45 schwarze Exp $
80387638 2.\"
f88b6c16 3.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
070c62a6
FF
4.\" Copyright (c) 2011, 2012, 2013 Ingo Schwarze <schwarze@openbsd.org>
5.\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
80387638
SW
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.\"
070c62a6 19.Dd $Mdocdate: June 22 2014 $
80387638
SW
20.Dt MAN 7
21.Os
22.Sh NAME
23.Nm man
36342e81 24.Nd legacy formatting language for manual pages
80387638 25.Sh DESCRIPTION
36342e81 26Traditionally, the
80387638 27.Nm man
36342e81 28language has been used to write
80387638 29.Ux
36342e81
SW
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.
80387638
SW
37.Pp
38.Bf -emphasis
39Do not use
40.Nm
36342e81 41to write your manuals:
80387638 42.Ef
36342e81 43It lacks support for semantic markup.
80387638
SW
44Use the
45.Xr mdoc 7
46language, instead.
47.Pp
36342e81 48In a
80387638 49.Nm
36342e81 50document, lines beginning with the control character
80387638 51.Sq \&.
36342e81
SW
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:
80387638
SW
64.Bd -literal -offset indent
65\&.SH Macro lines change control state.
36342e81 66Text lines are interpreted within the current state.
80387638 67.Ed
36342e81
SW
68.Pp
69Many aspects of the basic syntax of the
80387638 70.Nm
36342e81
SW
71language are based on the
72.Xr roff 7
73language; see the
74.Em LANGUAGE SYNTAX
80387638 75and
36342e81
SW
76.Em MACRO SYNTAX
77sections in the
78.Xr roff 7
79manual for details, in particular regarding
80comments, escape sequences, whitespace, and quoting.
80387638
SW
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 ,
36342e81 92at least one macro or text line must appear in the document.
a4c7eb57
SW
93.Pp
94The following is a well-formed skeleton
95.Nm
96file for a utility
97.Qq progname :
80387638 98.Bd -literal -offset indent
a4c7eb57 99\&.TH PROGNAME 1 2009-10-10
80387638 100\&.SH NAME
070c62a6 101\efBprogname\efR \e(en one line about what it does
36342e81 102\&.\e\(dq .SH LIBRARY
070c62a6 103\&.\e\(dq For sections 2, 3, and 9 only.
36342e81 104\&.\e\(dq Not used in OpenBSD.
80387638 105\&.SH SYNOPSIS
070c62a6 106\efBprogname\efR [\efB\e-options\efR] \efIfile ...\efR
80387638 107\&.SH DESCRIPTION
070c62a6
FF
108The \efBfoo\efR utility processes files ...
109\&.\e\(dq .Sh CONTEXT
110\&.\e\(dq For section 9 functions only.
36342e81
SW
111\&.\e\(dq .SH IMPLEMENTATION NOTES
112\&.\e\(dq Not used in OpenBSD.
113\&.\e\(dq .SH RETURN VALUES
070c62a6 114\&.\e\(dq For sections 2, 3, and 9 function return values only.
36342e81 115\&.\e\(dq .SH ENVIRONMENT
070c62a6 116\&.\e\(dq For sections 1, 6, 7, and 8 only.
36342e81
SW
117\&.\e\(dq .SH FILES
118\&.\e\(dq .SH EXIT STATUS
070c62a6 119\&.\e\(dq For sections 1, 6, and 8 only.
36342e81
SW
120\&.\e\(dq .SH EXAMPLES
121\&.\e\(dq .SH DIAGNOSTICS
070c62a6 122\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
36342e81 123\&.\e\(dq .SH ERRORS
070c62a6 124\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
36342e81 125\&.\e\(dq .SH SEE ALSO
070c62a6 126\&.\e\(dq .BR foobar ( 1 )
36342e81
SW
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.
80387638
SW
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).
070c62a6
FF
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.
80387638
SW
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.
070c62a6
FF
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
80387638
SW
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
070c62a6
FF
215Documents
216.Xr errno 2
217settings in sections 2, 3, 4, and 9.
80387638
SW
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
36342e81
SW
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)
80387638 258.El
36342e81
SW
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
f88b6c16 268.It Sx PD Ta set vertical paragraph distance: Op Ar height
36342e81
SW
269.It Sx \&br Ta force output line break in text mode (no arguments)
270.It Sx \&sp Ta force vertical space: Op Ar height
271.It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
272.It Sx in Ta additional indent: Op Ar width
80387638 273.El
36342e81
SW
274.Ss Physical markup
275.Bl -column "PP, LP, P" description
276.It Sx B Ta boldface font
277.It Sx I Ta italic font
278.It Sx R Ta roman (default) font
279.It Sx SB Ta small boldface font
280.It Sx SM Ta small roman font
281.It Sx BI Ta alternate between boldface and italic fonts
282.It Sx BR Ta alternate between boldface and roman fonts
283.It Sx IB Ta alternate between italic and boldface fonts
284.It Sx IR Ta alternate between italic and roman fonts
285.It Sx RB Ta alternate between roman and boldface fonts
286.It Sx RI Ta alternate between roman and italic fonts
287.El
36342e81 288.Sh MACRO REFERENCE
80387638
SW
289This section is a canonical reference to all macros, arranged
290alphabetically.
291For the scoping of individual macros, see
292.Sx MACRO SYNTAX .
293.Ss \&AT
294Sets the volume for the footer for compatibility with man pages from
070c62a6 295.At
80387638
SW
296releases.
297The optional arguments specify which release it is from.
298.Ss \&B
299Text is rendered in bold face.
300.Pp
301See also
302.Sx \&I
303and
304.Sx \&R .
305.Ss \&BI
306Text is rendered alternately in bold face and italic.
307Thus,
308.Sq .BI this word and that
309causes
310.Sq this
311and
312.Sq and
313to render in bold face, while
314.Sq word
315and
316.Sq that
317render in italics.
318Whitespace between arguments is omitted in output.
319.Pp
320Examples:
321.Pp
322.Dl \&.BI bold italic bold italic
323.Pp
324The output of this example will be emboldened
325.Dq bold
326and italicised
327.Dq italic ,
328with spaces stripped between arguments.
329.Pp
330See also
331.Sx \&IB ,
332.Sx \&BR ,
333.Sx \&RB ,
334.Sx \&RI ,
335and
336.Sx \&IR .
337.Ss \&BR
338Text is rendered alternately in bold face and roman (the default font).
339Whitespace between arguments is omitted in output.
340.Pp
341See
342.Sx \&BI
343for an equivalent example.
344.Pp
345See also
346.Sx \&BI ,
347.Sx \&IB ,
348.Sx \&RB ,
349.Sx \&RI ,
350and
351.Sx \&IR .
352.Ss \&DT
353Has no effect.
354Included for compatibility.
f88b6c16
FF
355.Ss \&EE
356This is a non-standard GNU extension, included only for compatibility.
357In
358.Xr mandoc 1 ,
359it does the same as
360.Sx \&fi .
361.Ss \&EX
362This is a non-standard GNU extension, included only for compatibility.
363In
364.Xr mandoc 1 ,
365it does the same as
366.Sx \&nf .
80387638
SW
367.Ss \&HP
368Begin a paragraph whose initial output line is left-justified, but
369subsequent output lines are indented, with the following syntax:
370.Bd -filled -offset indent
371.Pf \. Sx \&HP
372.Op Cm width
373.Ed
374.Pp
375The
376.Cm width
f88b6c16
FF
377argument is a
378.Xr roff 7
379scaling width.
80387638
SW
380If specified, it's saved for later paragraph left-margins; if unspecified, the
381saved or default width is used.
382.Pp
383See also
384.Sx \&IP ,
385.Sx \&LP ,
386.Sx \&P ,
387.Sx \&PP ,
388and
389.Sx \&TP .
390.Ss \&I
391Text is rendered in italics.
392.Pp
393See also
394.Sx \&B
395and
396.Sx \&R .
397.Ss \&IB
398Text is rendered alternately in italics and bold face.
399Whitespace between arguments is omitted in output.
400.Pp
401See
402.Sx \&BI
403for an equivalent example.
404.Pp
405See also
406.Sx \&BI ,
407.Sx \&BR ,
408.Sx \&RB ,
409.Sx \&RI ,
410and
411.Sx \&IR .
412.Ss \&IP
413Begin an indented paragraph with the following syntax:
414.Bd -filled -offset indent
415.Pf \. Sx \&IP
416.Op Cm head Op Cm width
417.Ed
418.Pp
419The
420.Cm width
f88b6c16
FF
421argument is a
422.Xr roff 7
423scaling width defining the left margin.
80387638
SW
424It's saved for later paragraph left-margins; if unspecified, the saved or
425default width is used.
426.Pp
427The
428.Cm head
429argument is used as a leading term, flushed to the left margin.
430This is useful for bulleted paragraphs and so on.
431.Pp
432See also
433.Sx \&HP ,
434.Sx \&LP ,
435.Sx \&P ,
436.Sx \&PP ,
437and
438.Sx \&TP .
439.Ss \&IR
440Text is rendered alternately in italics and roman (the default font).
441Whitespace between arguments is omitted in output.
442.Pp
443See
444.Sx \&BI
445for an equivalent example.
446.Pp
447See also
448.Sx \&BI ,
449.Sx \&IB ,
450.Sx \&BR ,
451.Sx \&RB ,
452and
453.Sx \&RI .
454.Ss \&LP
455Begin an undecorated paragraph.
456The scope of a paragraph is closed by a subsequent paragraph,
457sub-section, section, or end of file.
458The saved paragraph left-margin width is reset to the default.
459.Pp
460See also
461.Sx \&HP ,
462.Sx \&IP ,
463.Sx \&P ,
464.Sx \&PP ,
465and
466.Sx \&TP .
36342e81
SW
467.Ss \&OP
468Optional command-line argument.
f88b6c16
FF
469This is a non-standard GNU extension, included only for compatibility.
470It has the following syntax:
36342e81
SW
471.Bd -filled -offset indent
472.Pf \. Sx \&OP
473.Cm key Op Cm value
474.Ed
475.Pp
476The
477.Cm key
478is usually a command-line flag and
479.Cm value
480its argument.
80387638
SW
481.Ss \&P
482Synonym for
483.Sx \&LP .
484.Pp
485See also
486.Sx \&HP ,
487.Sx \&IP ,
488.Sx \&LP ,
489.Sx \&PP ,
490and
491.Sx \&TP .
f88b6c16
FF
492.Ss \&PD
493Specify the vertical space to be inserted before each new paragraph.
494.br
495The syntax is as follows:
496.Bd -filled -offset indent
497.Pf \. Sx \&PD
498.Op Cm height
499.Ed
500.Pp
501The
502.Cm height
503argument is a
504.Xr roff 7
505scaling width.
506It defaults to
507.Cm 1v .
508If the unit is omitted,
509.Cm v
510is assumed.
511.Pp
512This macro affects the spacing before any subsequent instances of
513.Sx \&HP ,
514.Sx \&IP ,
515.Sx \&LP ,
516.Sx \&P ,
517.Sx \&PP ,
518.Sx \&SH ,
519.Sx \&SS ,
520and
521.Sx \&TP .
80387638
SW
522.Ss \&PP
523Synonym for
524.Sx \&LP .
525.Pp
526See also
527.Sx \&HP ,
528.Sx \&IP ,
529.Sx \&LP ,
530.Sx \&P ,
531and
532.Sx \&TP .
533.Ss \&R
534Text is rendered in roman (the default font).
535.Pp
536See also
537.Sx \&I
538and
539.Sx \&B .
540.Ss \&RB
541Text is rendered alternately in roman (the default font) and bold face.
542Whitespace between arguments is omitted in output.
543.Pp
544See
545.Sx \&BI
546for an equivalent example.
547.Pp
548See also
549.Sx \&BI ,
550.Sx \&IB ,
551.Sx \&BR ,
552.Sx \&RI ,
553and
554.Sx \&IR .
555.Ss \&RE
556Explicitly close out the scope of a prior
557.Sx \&RS .
36342e81
SW
558The default left margin is restored to the state of the original
559.Sx \&RS
560invocation.
80387638
SW
561.Ss \&RI
562Text is rendered alternately in roman (the default font) and italics.
563Whitespace between arguments is omitted in output.
564.Pp
565See
566.Sx \&BI
567for an equivalent example.
568.Pp
569See also
570.Sx \&BI ,
571.Sx \&IB ,
572.Sx \&BR ,
573.Sx \&RB ,
574and
575.Sx \&IR .
576.Ss \&RS
36342e81 577Temporarily reset the default left margin.
80387638
SW
578This has the following syntax:
579.Bd -filled -offset indent
36342e81 580.Pf \. Sx \&RS
80387638
SW
581.Op Cm width
582.Ed
583.Pp
584The
585.Cm width
f88b6c16
FF
586argument is a
587.Xr roff 7
588scaling width.
80387638 589If not specified, the saved or default width is used.
36342e81
SW
590.Pp
591See also
592.Sx \&RE .
80387638
SW
593.Ss \&SB
594Text is rendered in small size (one point smaller than the default font)
595bold face.
596.Ss \&SH
597Begin a section.
598The scope of a section is only closed by another section or the end of
599file.
600The paragraph left-margin width is reset to the default.
601.Ss \&SM
602Text is rendered in small size (one point smaller than the default
603font).
604.Ss \&SS
605Begin a sub-section.
606The scope of a sub-section is closed by a subsequent sub-section,
607section, or end of file.
608The paragraph left-margin width is reset to the default.
609.Ss \&TH
610Sets the title of the manual page with the following syntax:
611.Bd -filled -offset indent
612.Pf \. Sx \&TH
60e1e752
SW
613.Ar title section date
614.Op Ar source Op Ar volume
80387638
SW
615.Ed
616.Pp
60e1e752
SW
617Conventionally, the document
618.Ar title
619is given in all caps.
620The recommended
621.Ar date
622format is
623.Sy YYYY-MM-DD
624as specified in the ISO-8601 standard;
625if the argument does not conform, it is printed verbatim.
626If the
627.Ar date
628is empty or not specified, the current date is used.
629The optional
630.Ar source
80387638
SW
631string specifies the organisation providing the utility.
632The
60e1e752 633.Ar volume
80387638
SW
634string replaces the default rendered volume, which is dictated by the
635manual section.
636.Pp
637Examples:
638.Pp
639.Dl \&.TH CVS 5 "1992-02-12" GNU
640.Ss \&TP
641Begin a paragraph where the head, if exceeding the indentation width, is
642followed by a newline; if not, the body follows on the same line after a
643buffer to the indentation width.
644Subsequent output lines are indented.
645The syntax is as follows:
646.Bd -filled -offset indent
647.Pf \. Sx \&TP
648.Op Cm width
649.Ed
650.Pp
651The
652.Cm width
f88b6c16
FF
653argument is a
654.Xr roff 7
655scaling width.
80387638
SW
656If specified, it's saved for later paragraph left-margins; if
657unspecified, the saved or default width is used.
658.Pp
659See also
660.Sx \&HP ,
661.Sx \&IP ,
662.Sx \&LP ,
663.Sx \&P ,
664and
665.Sx \&PP .
666.Ss \&UC
667Sets the volume for the footer for compatibility with man pages from
f88b6c16
FF
668.Bx
669releases.
80387638 670The optional first argument specifies which release it is from.
070c62a6
FF
671.Ss \&UE
672End a uniform resource identifier block.
673This is a non-standard GNU extension, included only for compatibility.
674See
675.Sx \&UE .
676.Ss \&UR
677Begin a uniform resource identifier block.
678This is a non-standard GNU extension, included only for compatibility.
679It has the following syntax:
680.Bd -literal -offset indent
681.Pf \. Sx \&UR Ar uri
682link description to be shown
683.Pf \. Sx UE
684.Ed
80387638
SW
685.Ss \&br
686Breaks the current line.
687Consecutive invocations have no further effect.
688.Pp
689See also
690.Sx \&sp .
691.Ss \&fi
692End literal mode begun by
693.Sx \&nf .
80387638
SW
694.Ss \&in
695Indent relative to the current indentation:
696.Pp
697.D1 Pf \. Sx \&in Op Cm width
698.Pp
699If
700.Cm width
701is signed, the new offset is relative.
702Otherwise, it is absolute.
703This value is reset upon the next paragraph, section, or sub-section.
704.Ss \&na
705Don't align to the right margin.
706.Ss \&nf
707Begin literal mode: all subsequent free-form lines have their end of
708line boundaries preserved.
709May be ended by
710.Sx \&fi .
36342e81
SW
711Literal mode is implicitly ended by
712.Sx \&SH
713or
714.Sx \&SS .
80387638
SW
715.Ss \&sp
716Insert vertical spaces into output with the following syntax:
717.Bd -filled -offset indent
718.Pf \. Sx \&sp
719.Op Cm height
720.Ed
721.Pp
f88b6c16 722The
80387638 723.Cm height
f88b6c16
FF
724argument is a scaling width as described in
725.Xr roff 7 .
80387638
SW
726If 0, this is equivalent to the
727.Sx \&br
728macro.
729Defaults to 1, if unspecified.
730.Pp
731See also
732.Sx \&br .
36342e81
SW
733.Sh MACRO SYNTAX
734The
735.Nm
736macros are classified by scope: line scope or block scope.
737Line macros are only scoped to the current line (and, in some
738situations, the subsequent line).
739Block macros are scoped to the current line and subsequent lines until
740closed by another block macro.
741.Ss Line Macros
742Line macros are generally scoped to the current line, with the body
743consisting of zero or more arguments.
744If a macro is scoped to the next line and the line arguments are empty,
745the next line, which must be text, is used instead.
746Thus:
747.Bd -literal -offset indent
748\&.I
749foo
750.Ed
751.Pp
752is equivalent to
753.Sq \&.I foo .
754If next-line macros are invoked consecutively, only the last is used.
755If a next-line macro is followed by a non-next-line macro, an error is
756raised, except for
757.Sx \&br ,
758.Sx \&sp ,
759and
760.Sx \&na .
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 \&
070c62a6
FF
774.It Sx \&EE Ta 0 Ta current Ta compat
775.It Sx \&EX Ta 0 Ta current Ta compat
36342e81
SW
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
070c62a6 780.It Sx \&PD Ta 1 Ta current Ta \&
36342e81
SW
781.It Sx \&R Ta n Ta next-line Ta \&
782.It Sx \&RB Ta n Ta current Ta \&
783.It Sx \&RI Ta n Ta current Ta \&
784.It Sx \&SB Ta n Ta next-line Ta \&
785.It Sx \&SM Ta n Ta next-line Ta \&
786.It Sx \&TH Ta >1, <6 Ta current Ta \&
787.It Sx \&UC Ta <=1 Ta current Ta \&
788.It Sx \&br Ta 0 Ta current Ta compat
789.It Sx \&fi Ta 0 Ta current Ta compat
36342e81
SW
790.It Sx \&in Ta 1 Ta current Ta compat
791.It Sx \&na Ta 0 Ta current Ta compat
792.It Sx \&nf Ta 0 Ta current Ta compat
793.It Sx \&sp Ta 1 Ta current Ta compat
794.El
795.Pp
796Macros marked as
797.Qq compat
798are included for compatibility with the significant corpus of existing
799manuals that mix dialects of roff.
800These macros should not be used for portable
801.Nm
802manuals.
803.Ss Block Macros
804Block macros comprise a head and body.
805As with in-line macros, the head is scoped to the current line and, in
806one circumstance, the next line (the next-line stipulations as in
807.Sx Line Macros
808apply here as well).
809.Pp
810The syntax is as follows:
811.Bd -literal -offset indent
812\&.YO \(lBhead...\(rB
813\(lBhead...\(rB
814\(lBbody...\(rB
815.Ed
816.Pp
817The closure of body scope may be to the section, where a macro is closed
818by
819.Sx \&SH ;
820sub-section, closed by a section or
821.Sx \&SS ;
822part, closed by a section, sub-section, or
823.Sx \&RE ;
824or paragraph, closed by a section, sub-section, part,
825.Sx \&HP ,
826.Sx \&IP ,
827.Sx \&LP ,
828.Sx \&P ,
829.Sx \&PP ,
830or
831.Sx \&TP .
832No closure refers to an explicit block closing macro.
833.Pp
834As a rule, block macros may not be nested; thus, calling a block macro
835while another block macro scope is open, and the open scope is not
836implicitly closed, is syntactically incorrect.
837.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
838.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
839.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
840.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
841.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
842.It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
843.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
844.It Sx \&RE Ta 0 Ta current Ta none Ta compat
845.It Sx \&RS Ta 1 Ta current Ta part Ta compat
846.It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
847.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
848.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
070c62a6
FF
849.It Sx \&UE Ta 0 Ta current Ta none Ta compat
850.It Sx \&UR Ta 1 Ta current Ta part Ta compat
36342e81
SW
851.El
852.Pp
853Macros marked
854.Qq compat
855are as mentioned in
856.Sx Line Macros .
857.Pp
858If a block macro is next-line scoped, it may only be followed by in-line
859macros for decorating text.
860.Ss Font handling
861In
862.Nm
863documents, both
864.Sx Physical markup
865macros and
866.Xr roff 7
867.Ql \ef
868font escape sequences can be used to choose fonts.
869In text lines, the effect of manual font selection by escape sequences
870only lasts until the next macro invocation; in macro lines, it only lasts
871until the end of the macro scope.
872Note that macros like
873.Sx \&BR
874open and close a font scope for each argument.
80387638 875.Sh COMPATIBILITY
070c62a6 876This section mentions some areas of questionable portability between
80387638
SW
877implementations of the
878.Nm
879language.
070c62a6 880More incompatibilities exist.
80387638
SW
881.Pp
882.Bl -dash -compact
883.It
36342e81
SW
884Do not depend on
885.Sx \&SH
886or
887.Sx \&SS
888to close out a literal context opened with
889.Sx \&nf .
890This behaviour may not be portable.
891.It
80387638
SW
892troff suppresses a newline before
893.Sq \(aq
894macro output; in mandoc, it is an alias for the standard
895.Sq \&.
896control character.
897.It
36342e81
SW
898In page header lines, GNU troff versions up to and including 1.21
899only print
900.Ar volume
901names explicitly specified in the
902.Sx \&TH
903macro; mandoc and newer groff print the default volume name
904corresponding to the
905.Ar section
906number when no
907.Ar volume
908is given, like in
909.Xr mdoc 7 .
80387638 910.El
36342e81
SW
911.Pp
912The
070c62a6
FF
913.Sx EE ,
914.Sx EX ,
915.Sx OP ,
916.Sx UE ,
917and
918.Sx UR
919macros are part of the GNU extended
36342e81
SW
920.Nm
921macro set, and may not be portable to non-GNU troff implementations.
80387638
SW
922.Sh SEE ALSO
923.Xr man 1 ,
924.Xr mandoc 1 ,
60e1e752 925.Xr eqn 7 ,
80387638
SW
926.Xr mandoc_char 7 ,
927.Xr mdoc 7 ,
928.Xr roff 7 ,
929.Xr tbl 7
930.Sh HISTORY
931The
932.Nm
933language first appeared as a macro package for the roff typesetting
934system in
935.At v7 .
936It was later rewritten by James Clark as a macro package for groff.
36342e81
SW
937Eric S. Raymond wrote the extended
938.Nm
939macros for groff in 2007.
80387638
SW
940The stand-alone implementation that is part of the
941.Xr mandoc 1
942utility written by Kristaps Dzonsons appeared in
943.Ox 4.6 .
944.Sh AUTHORS
945This
946.Nm
947reference was written by
f88b6c16 948.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
80387638
SW
949.Sh CAVEATS
950Do not use this language.
951Use
952.Xr mdoc 7 ,
953instead.