| blob | 4b64d7f442f43b23edb9bf14fd6e37b30bb7876e |
1 .\" $Id: man.7,v 1.127 2014/06/22 16:39:45 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2011, 2012, 2013 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: June 22 2014 $
20 .Dt MAN 7
21 .Os
22 .Sh NAME
23 .Nm man
24 .Nd legacy formatting language for manual pages
25 .Sh DESCRIPTION
26 Traditionally, the
27 .Nm man
28 language has been used to write
29 .Ux
30 manuals for the
31 .Xr man 1
32 utility.
33 It supports limited control of presentational details like fonts,
34 indentation and spacing.
35 This reference document describes the structure of manual pages
36 and the syntax and usage of the man language.
37 .Pp
38 .Bf -emphasis
39 Do not use
40 .Nm
41 to write your manuals:
42 .Ef
43 It lacks support for semantic markup.
44 Use the
45 .Xr mdoc 7
46 language, instead.
47 .Pp
48 In a
49 .Nm
50 document, lines beginning with the control character
51 .Sq \&.
52 are called
53 .Dq macro lines .
54 The first word is the macro name.
55 It usually consists of two capital letters.
56 For a list of available macros, see
57 .Sx MACRO OVERVIEW .
58 The words following the macro name are arguments to the macro.
59 .Pp
60 Lines not beginning with the control character are called
61 .Dq text lines .
62 They provide free-form text to be printed; the formatting of the text
63 depends on the respective processing context:
64 .Bd -literal -offset indent
65 \&.SH Macro lines change control state.
66 Text lines are interpreted within the current state.
67 .Ed
68 .Pp
69 Many aspects of the basic syntax of the
70 .Nm
71 language are based on the
72 .Xr roff 7
73 language; see the
74 .Em LANGUAGE SYNTAX
75 and
76 .Em MACRO SYNTAX
77 sections in the
78 .Xr roff 7
79 manual for details, in particular regarding
80 comments, escape sequences, whitespace, and quoting.
81 .Sh MANUAL STRUCTURE
82 Each
83 .Nm
84 document must contain the
85 .Sx \&TH
86 macro describing the document's section and title.
87 It may occur anywhere in the document, although conventionally it
88 appears as the first macro.
89 .Pp
90 Beyond
91 .Sx \&TH ,
92 at least one macro or text line must appear in the document.
93 .Pp
94 The following is a well-formed skeleton
95 .Nm
96 file 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
108 The \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
136 The sections in a
137 .Nm
138 document are conventionally ordered as they appear above.
139 Sections should be composed as follows:
140 .Bl -ohang -offset indent
141 .It Em NAME
142 The name(s) and a short description of the documented material.
143 The syntax for this is generally as follows:
144 .Pp
145 .D1 \efBname\efR \e(en description
146 .It Em LIBRARY
147 The name of the library containing the documented material, which is
148 assumed to be a function in a section 2 or 3 manual.
149 For functions in the C library, this may be as follows:
150 .Pp
151 .D1 Standard C Library (libc, -lc)
152 .It Em SYNOPSIS
153 Documents the utility invocation syntax, function call syntax, or device
154 configuration.
155 .Pp
156 For the first, utilities (sections 1, 6, and 8), this is
157 generally structured as follows:
158 .Pp
159 .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
160 .Pp
161 For the second, function calls (sections 2, 3, 9):
162 .Pp
163 .D1 \&.B char *name(char *\efIarg\efR);
164 .Pp
165 And for the third, configurations (section 4):
166 .Pp
167 .D1 \&.B name* at cardbus ? function ?
168 .Pp
169 Manuals not in these sections generally don't need a
170 .Em SYNOPSIS .
171 .It Em DESCRIPTION
172 This expands upon the brief, one-line description in
173 .Em NAME .
174 It usually contains a break-down of the options (if documenting a
175 command).
176 .It Em CONTEXT
177 This section lists the contexts in which functions can be called in section 9.
178 The contexts are autoconf, process, or interrupt.
179 .It Em IMPLEMENTATION NOTES
180 Implementation-specific notes should be kept here.
181 This is useful when implementing standard functions that may have side
182 effects or notable algorithmic implications.
183 .It Em RETURN VALUES
184 This section documents the return values of functions in sections 2, 3, and 9.
185 .It Em ENVIRONMENT
186 Documents any usages of environment variables, e.g.,
187 .Xr environ 7 .
188 .It Em FILES
189 Documents files used.
190 It's helpful to document both the file name and a short description of how
191 the file is used (created, modified, etc.).
192 .It Em EXIT STATUS
193 This section documents the command exit status for
194 section 1, 6, and 8 utilities.
195 Historically, this information was described in
196 .Em DIAGNOSTICS ,
197 a practise that is now discouraged.
198 .It Em EXAMPLES
199 Example usages.
200 This often contains snippets of well-formed,
201 well-tested invocations.
202 Make sure that examples work properly!
203 .It Em DIAGNOSTICS
204 Documents error conditions.
205 In section 4 and 9 manuals, these are usually messages
206 printed by the kernel to the console and to the kernel log.
207 In section 1, 6, 7, and 8, these are usually messages
208 printed by userland programs to the standard error output.
209 .Pp
210 Historically, this section was used in place of
211 .Em EXIT STATUS
212 for manuals in sections 1, 6, and 8; however, this practise is
213 discouraged.
214 .It Em ERRORS
215 Documents
216 .Xr errno 2
217 settings in sections 2, 3, 4, and 9.
218 .It Em SEE ALSO
219 References other manuals with related topics.
220 This section should exist for most manuals.
221 .Pp
222 .D1 \&.BR bar \&( 1 \&),
223 .Pp
224 Cross-references should conventionally be ordered
225 first by section, then alphabetically.
226 .It Em STANDARDS
227 References any standards implemented or used, such as
228 .Pp
229 .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
230 .Pp
231 If not adhering to any standards, the
232 .Em HISTORY
233 section should be used.
234 .It Em HISTORY
235 A brief history of the subject, including where support first appeared.
236 .It Em AUTHORS
237 Credits to the person or persons who wrote the code and/or documentation.
238 Authors should generally be noted by both name and email address.
239 .It Em CAVEATS
240 Common misuses and misunderstandings should be explained
241 in this section.
242 .It Em BUGS
243 Known bugs, limitations, and work-arounds should be described
244 in this section.
245 .It Em SECURITY CONSIDERATIONS
246 Documents any security precautions that operators should consider.
247 .El
248 .Sh MACRO OVERVIEW
249 This overview is sorted such that macros of similar purpose are listed
250 together, to help find the best macro for any given purpose.
251 Deprecated macros are not included in the overview, but can be found
252 in 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 \&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
273 .El
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
288 .Sh MACRO REFERENCE
289 This section is a canonical reference to all macros, arranged
290 alphabetically.
291 For the scoping of individual macros, see
292 .Sx MACRO SYNTAX .
293 .Ss \&AT
294 Sets the volume for the footer for compatibility with man pages from
295 .At
296 releases.
297 The optional arguments specify which release it is from.
298 .Ss \&B
299 Text is rendered in bold face.
300 .Pp
301 See also
302 .Sx \&I
303 and
304 .Sx \&R .
305 .Ss \&BI
306 Text is rendered alternately in bold face and italic.
307 Thus,
308 .Sq .BI this word and that
309 causes
310 .Sq this
311 and
312 .Sq and
313 to render in bold face, while
314 .Sq word
315 and
316 .Sq that
317 render in italics.
318 Whitespace between arguments is omitted in output.
319 .Pp
320 Examples:
321 .Pp
322 .Dl \&.BI bold italic bold italic
323 .Pp
324 The output of this example will be emboldened
325 .Dq bold
326 and italicised
327 .Dq italic ,
328 with spaces stripped between arguments.
329 .Pp
330 See also
331 .Sx \&IB ,
332 .Sx \&BR ,
333 .Sx \&RB ,
334 .Sx \&RI ,
335 and
336 .Sx \&IR .
337 .Ss \&BR
338 Text is rendered alternately in bold face and roman (the default font).
339 Whitespace between arguments is omitted in output.
340 .Pp
341 See
342 .Sx \&BI
343 for an equivalent example.
344 .Pp
345 See also
346 .Sx \&BI ,
347 .Sx \&IB ,
348 .Sx \&RB ,
349 .Sx \&RI ,
350 and
351 .Sx \&IR .
352 .Ss \&DT
353 Has no effect.
354 Included for compatibility.
355 .Ss \&EE
356 This is a non-standard GNU extension, included only for compatibility.
357 In
358 .Xr mandoc 1 ,
359 it does the same as
360 .Sx \&fi .
361 .Ss \&EX
362 This is a non-standard GNU extension, included only for compatibility.
363 In
364 .Xr mandoc 1 ,
365 it does the same as
366 .Sx \&nf .
367 .Ss \&HP
368 Begin a paragraph whose initial output line is left-justified, but
369 subsequent 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
375 The
376 .Cm width
377 argument is a
378 .Xr roff 7
379 scaling width.
380 If specified, it's saved for later paragraph left-margins; if unspecified, the
381 saved or default width is used.
382 .Pp
383 See also
384 .Sx \&IP ,
385 .Sx \&LP ,
386 .Sx \&P ,
387 .Sx \&PP ,
388 and
389 .Sx \&TP .
390 .Ss \&I
391 Text is rendered in italics.
392 .Pp
393 See also
394 .Sx \&B
395 and
396 .Sx \&R .
397 .Ss \&IB
398 Text is rendered alternately in italics and bold face.
399 Whitespace between arguments is omitted in output.
400 .Pp
401 See
402 .Sx \&BI
403 for an equivalent example.
404 .Pp
405 See also
406 .Sx \&BI ,
407 .Sx \&BR ,
408 .Sx \&RB ,
409 .Sx \&RI ,
410 and
411 .Sx \&IR .
412 .Ss \&IP
413 Begin 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
419 The
420 .Cm width
421 argument is a
422 .Xr roff 7
423 scaling width defining the left margin.
424 It's saved for later paragraph left-margins; if unspecified, the saved or
425 default width is used.
426 .Pp
427 The
428 .Cm head
429 argument is used as a leading term, flushed to the left margin.
430 This is useful for bulleted paragraphs and so on.
431 .Pp
432 See also
433 .Sx \&HP ,
434 .Sx \&LP ,
435 .Sx \&P ,
436 .Sx \&PP ,
437 and
438 .Sx \&TP .
439 .Ss \&IR
440 Text is rendered alternately in italics and roman (the default font).
441 Whitespace between arguments is omitted in output.
442 .Pp
443 See
444 .Sx \&BI
445 for an equivalent example.
446 .Pp
447 See also
448 .Sx \&BI ,
449 .Sx \&IB ,
450 .Sx \&BR ,
451 .Sx \&RB ,
452 and
453 .Sx \&RI .
454 .Ss \&LP
455 Begin an undecorated paragraph.
456 The scope of a paragraph is closed by a subsequent paragraph,
457 sub-section, section, or end of file.
458 The saved paragraph left-margin width is reset to the default.
459 .Pp
460 See also
461 .Sx \&HP ,
462 .Sx \&IP ,
463 .Sx \&P ,
464 .Sx \&PP ,
465 and
466 .Sx \&TP .
467 .Ss \&OP
468 Optional command-line argument.
469 This is a non-standard GNU extension, included only for compatibility.
470 It has the following syntax:
471 .Bd -filled -offset indent
472 .Pf \. Sx \&OP
473 .Cm key Op Cm value
474 .Ed
475 .Pp
476 The
477 .Cm key
478 is usually a command-line flag and
479 .Cm value
480 its argument.
481 .Ss \&P
482 Synonym for
483 .Sx \&LP .
484 .Pp
485 See also
486 .Sx \&HP ,
487 .Sx \&IP ,
488 .Sx \&LP ,
489 .Sx \&PP ,
490 and
491 .Sx \&TP .
492 .Ss \&PD
493 Specify the vertical space to be inserted before each new paragraph.
494 .br
495 The syntax is as follows:
496 .Bd -filled -offset indent
497 .Pf \. Sx \&PD
498 .Op Cm height
499 .Ed
500 .Pp
501 The
502 .Cm height
503 argument is a
504 .Xr roff 7
505 scaling width.
506 It defaults to
507 .Cm 1v .
508 If the unit is omitted,
509 .Cm v
510 is assumed.
511 .Pp
512 This 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 ,
520 and
521 .Sx \&TP .
522 .Ss \&PP
523 Synonym for
524 .Sx \&LP .
525 .Pp
526 See also
527 .Sx \&HP ,
528 .Sx \&IP ,
529 .Sx \&LP ,
530 .Sx \&P ,
531 and
532 .Sx \&TP .
533 .Ss \&R
534 Text is rendered in roman (the default font).
535 .Pp
536 See also
537 .Sx \&I
538 and
539 .Sx \&B .
540 .Ss \&RB
541 Text is rendered alternately in roman (the default font) and bold face.
542 Whitespace between arguments is omitted in output.
543 .Pp
544 See
545 .Sx \&BI
546 for an equivalent example.
547 .Pp
548 See also
549 .Sx \&BI ,
550 .Sx \&IB ,
551 .Sx \&BR ,
552 .Sx \&RI ,
553 and
554 .Sx \&IR .
555 .Ss \&RE
556 Explicitly close out the scope of a prior
557 .Sx \&RS .
558 The default left margin is restored to the state of the original
559 .Sx \&RS
560 invocation.
561 .Ss \&RI
562 Text is rendered alternately in roman (the default font) and italics.
563 Whitespace between arguments is omitted in output.
564 .Pp
565 See
566 .Sx \&BI
567 for an equivalent example.
568 .Pp
569 See also
570 .Sx \&BI ,
571 .Sx \&IB ,
572 .Sx \&BR ,
573 .Sx \&RB ,
574 and
575 .Sx \&IR .
576 .Ss \&RS
577 Temporarily reset the default left margin.
578 This has the following syntax:
579 .Bd -filled -offset indent
580 .Pf \. Sx \&RS
581 .Op Cm width
582 .Ed
583 .Pp
584 The
585 .Cm width
586 argument is a
587 .Xr roff 7
588 scaling width.
589 If not specified, the saved or default width is used.
590 .Pp
591 See also
592 .Sx \&RE .
593 .Ss \&SB
594 Text is rendered in small size (one point smaller than the default font)
595 bold face.
596 .Ss \&SH
597 Begin a section.
598 The scope of a section is only closed by another section or the end of
599 file.
600 The paragraph left-margin width is reset to the default.
601 .Ss \&SM
602 Text is rendered in small size (one point smaller than the default
603 font).
604 .Ss \&SS
605 Begin a sub-section.
606 The scope of a sub-section is closed by a subsequent sub-section,
607 section, or end of file.
608 The paragraph left-margin width is reset to the default.
609 .Ss \&TH
610 Sets the title of the manual page with the following syntax:
611 .Bd -filled -offset indent
612 .Pf \. Sx \&TH
613 .Ar title section date
614 .Op Ar source Op Ar volume
615 .Ed
616 .Pp
617 Conventionally, the document
618 .Ar title
619 is given in all caps.
620 The recommended
621 .Ar date
622 format is
623 .Sy YYYY-MM-DD
624 as specified in the ISO-8601 standard;
625 if the argument does not conform, it is printed verbatim.
626 If the
627 .Ar date
628 is empty or not specified, the current date is used.
629 The optional
630 .Ar source
631 string specifies the organisation providing the utility.
632 The
633 .Ar volume
634 string replaces the default rendered volume, which is dictated by the
635 manual section.
636 .Pp
637 Examples:
638 .Pp
639 .Dl \&.TH CVS 5 "1992-02-12" GNU
640 .Ss \&TP
641 Begin a paragraph where the head, if exceeding the indentation width, is
642 followed by a newline; if not, the body follows on the same line after a
643 buffer to the indentation width.
644 Subsequent output lines are indented.
645 The syntax is as follows:
646 .Bd -filled -offset indent
647 .Pf \. Sx \&TP
648 .Op Cm width
649 .Ed
650 .Pp
651 The
652 .Cm width
653 argument is a
654 .Xr roff 7
655 scaling width.
656 If specified, it's saved for later paragraph left-margins; if
657 unspecified, the saved or default width is used.
658 .Pp
659 See also
660 .Sx \&HP ,
661 .Sx \&IP ,
662 .Sx \&LP ,
663 .Sx \&P ,
664 and
665 .Sx \&PP .
666 .Ss \&UC
667 Sets the volume for the footer for compatibility with man pages from
668 .Bx
669 releases.
670 The optional first argument specifies which release it is from.
671 .Ss \&UE
672 End a uniform resource identifier block.
673 This is a non-standard GNU extension, included only for compatibility.
674 See
675 .Sx \&UE .
676 .Ss \&UR
677 Begin a uniform resource identifier block.
678 This is a non-standard GNU extension, included only for compatibility.
679 It has the following syntax:
680 .Bd -literal -offset indent
681 .Pf \. Sx \&UR Ar uri
682 link description to be shown
683 .Pf \. Sx UE
684 .Ed
685 .Ss \&br
686 Breaks the current line.
687 Consecutive invocations have no further effect.
688 .Pp
689 See also
690 .Sx \&sp .
691 .Ss \&fi
692 End literal mode begun by
693 .Sx \&nf .
694 .Ss \&in
695 Indent relative to the current indentation:
696 .Pp
697 .D1 Pf \. Sx \&in Op Cm width
698 .Pp
699 If
700 .Cm width
701 is signed, the new offset is relative.
702 Otherwise, it is absolute.
703 This value is reset upon the next paragraph, section, or sub-section.
704 .Ss \&na
705 Don't align to the right margin.
706 .Ss \&nf
707 Begin literal mode: all subsequent free-form lines have their end of
708 line boundaries preserved.
709 May be ended by
710 .Sx \&fi .
711 Literal mode is implicitly ended by
712 .Sx \&SH
713 or
714 .Sx \&SS .
715 .Ss \&sp
716 Insert 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
722 The
723 .Cm height
724 argument is a scaling width as described in
725 .Xr roff 7 .
726 If 0, this is equivalent to the
727 .Sx \&br
728 macro.
729 Defaults to 1, if unspecified.
730 .Pp
731 See also
732 .Sx \&br .
733 .Sh MACRO SYNTAX
734 The
735 .Nm
736 macros are classified by scope: line scope or block scope.
737 Line macros are only scoped to the current line (and, in some
738 situations, the subsequent line).
739 Block macros are scoped to the current line and subsequent lines until
740 closed by another block macro.
741 .Ss Line Macros
742 Line macros are generally scoped to the current line, with the body
743 consisting of zero or more arguments.
744 If a macro is scoped to the next line and the line arguments are empty,
745 the next line, which must be text, is used instead.
746 Thus:
747 .Bd -literal -offset indent
748 \&.I
749 foo
750 .Ed
751 .Pp
752 is equivalent to
753 .Sq \&.I foo .
754 If next-line macros are invoked consecutively, only the last is used.
755 If a next-line macro is followed by a non-next-line macro, an error is
756 raised, except for
757 .Sx \&br ,
758 .Sx \&sp ,
759 and
760 .Sx \&na .
761 .Pp
762 The 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 \&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
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
796 Macros marked as
797 .Qq compat
798 are included for compatibility with the significant corpus of existing
799 manuals that mix dialects of roff.
800 These macros should not be used for portable
801 .Nm
802 manuals.
803 .Ss Block Macros
804 Block macros comprise a head and body.
805 As with in-line macros, the head is scoped to the current line and, in
806 one circumstance, the next line (the next-line stipulations as in
807 .Sx Line Macros
808 apply here as well).
809 .Pp
810 The syntax is as follows:
811 .Bd -literal -offset indent
812 \&.YO \(lBhead...\(rB
813 \(lBhead...\(rB
814 \(lBbody...\(rB
815 .Ed
816 .Pp
817 The closure of body scope may be to the section, where a macro is closed
818 by
819 .Sx \&SH ;
820 sub-section, closed by a section or
821 .Sx \&SS ;
822 part, closed by a section, sub-section, or
823 .Sx \&RE ;
824 or paragraph, closed by a section, sub-section, part,
825 .Sx \&HP ,
826 .Sx \&IP ,
827 .Sx \&LP ,
828 .Sx \&P ,
829 .Sx \&PP ,
830 or
831 .Sx \&TP .
832 No closure refers to an explicit block closing macro.
833 .Pp
834 As a rule, block macros may not be nested; thus, calling a block macro
835 while another block macro scope is open, and the open scope is not
836 implicitly 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 \&
849 .It Sx \&UE Ta 0 Ta current Ta none Ta compat
850 .It Sx \&UR Ta 1 Ta current Ta part Ta compat
851 .El
852 .Pp
853 Macros marked
854 .Qq compat
855 are as mentioned in
856 .Sx Line Macros .
857 .Pp
858 If a block macro is next-line scoped, it may only be followed by in-line
859 macros for decorating text.
860 .Ss Font handling
861 In
862 .Nm
863 documents, both
864 .Sx Physical markup
865 macros and
866 .Xr roff 7
867 .Ql \ef
868 font escape sequences can be used to choose fonts.
869 In text lines, the effect of manual font selection by escape sequences
870 only lasts until the next macro invocation; in macro lines, it only lasts
871 until the end of the macro scope.
872 Note that macros like
873 .Sx \&BR
874 open and close a font scope for each argument.
875 .Sh COMPATIBILITY
876 This section mentions some areas of questionable portability between
877 implementations of the
878 .Nm
879 language.
880 More incompatibilities exist.
881 .Pp
882 .Bl -dash -compact
883 .It
884 Do not depend on
885 .Sx \&SH
886 or
887 .Sx \&SS
888 to close out a literal context opened with
889 .Sx \&nf .
890 This behaviour may not be portable.
891 .It
892 troff suppresses a newline before
893 .Sq \(aq
894 macro output; in mandoc, it is an alias for the standard
895 .Sq \&.
896 control character.
897 .It
898 In page header lines, GNU troff versions up to and including 1.21
899 only print
900 .Ar volume
901 names explicitly specified in the
902 .Sx \&TH
903 macro; mandoc and newer groff print the default volume name
904 corresponding to the
905 .Ar section
906 number when no
907 .Ar volume
908 is given, like in
909 .Xr mdoc 7 .
910 .El
911 .Pp
912 The
913 .Sx EE ,
914 .Sx EX ,
915 .Sx OP ,
916 .Sx UE ,
917 and
918 .Sx UR
919 macros are part of the GNU extended
920 .Nm
921 macro set, and may not be portable to non-GNU troff implementations.
922 .Sh SEE ALSO
923 .Xr man 1 ,
924 .Xr mandoc 1 ,
925 .Xr eqn 7 ,
926 .Xr mandoc_char 7 ,
927 .Xr mdoc 7 ,
928 .Xr roff 7 ,
929 .Xr tbl 7
930 .Sh HISTORY
931 The
932 .Nm
933 language first appeared as a macro package for the roff typesetting
934 system in
935 .At v7 .
936 It was later rewritten by James Clark as a macro package for groff.
937 Eric S. Raymond wrote the extended
938 .Nm
939 macros for groff in 2007.
940 The stand-alone implementation that is part of the
941 .Xr mandoc 1
942 utility written by Kristaps Dzonsons appeared in
943 .Ox 4.6 .
944 .Sh AUTHORS
945 This
946 .Nm
947 reference was written by
948 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
949 .Sh CAVEATS
950 Do not use this language.
951 Use
952 .Xr mdoc 7 ,
953 instead.