| blob | d418b9ee76caf7db211526043b0a652c7938c66a |
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
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 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
286 This section is a canonical reference to all macros, arranged
287 alphabetically.
288 For the scoping of individual macros, see
289 .Sx MACRO SYNTAX .
290 .Ss \&AT
291 Sets the volume for the footer for compatibility with man pages from
292 .At
293 releases.
294 The optional arguments specify which release it is from.
295 .Ss \&B
296 Text is rendered in bold face.
297 .Pp
298 See also
299 .Sx \&I .
300 .Ss \&BI
301 Text is rendered alternately in bold face and italic.
302 Thus,
303 .Sq .BI this word and that
304 causes
305 .Sq this
306 and
307 .Sq and
308 to render in bold face, while
309 .Sq word
310 and
311 .Sq that
312 render in italics.
313 Whitespace between arguments is omitted in output.
314 .Pp
315 Examples:
316 .Pp
317 .Dl \&.BI bold italic bold italic
318 .Pp
319 The output of this example will be emboldened
320 .Dq bold
321 and italicised
322 .Dq italic ,
323 with spaces stripped between arguments.
324 .Pp
325 See also
326 .Sx \&IB ,
327 .Sx \&BR ,
328 .Sx \&RB ,
329 .Sx \&RI ,
330 and
331 .Sx \&IR .
332 .Ss \&BR
333 Text is rendered alternately in bold face and roman (the default font).
334 Whitespace between arguments is omitted in output.
335 .Pp
336 See
337 .Sx \&BI
338 for an equivalent example.
339 .Pp
340 See also
341 .Sx \&BI ,
342 .Sx \&IB ,
343 .Sx \&RB ,
344 .Sx \&RI ,
345 and
346 .Sx \&IR .
347 .Ss \&DT
348 Restore the default tabulator positions.
349 They are at intervals of 0.5 inches.
350 This has no effect unless the tabulator positions were changed with the
351 .Xr roff 7
352 .Ic \&ta
353 request.
354 .Ss \&EE
355 This is a non-standard GNU extension, included only for compatibility.
356 In
357 .Xr mandoc 1 ,
358 it does the same as
359 .Sx \&fi .
360 .Ss \&EX
361 This is a non-standard GNU extension, included only for compatibility.
362 In
363 .Xr mandoc 1 ,
364 it does the same as
365 .Sx \&nf .
366 .Ss \&HP
367 Begin a paragraph whose initial output line is left-justified, but
368 subsequent 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
374 The
375 .Ar width
376 argument is a
377 .Xr roff 7
378 scaling width.
379 If specified, it's saved for later paragraph left-margins; if unspecified, the
380 saved or default width is used.
381 .Pp
382 See also
383 .Sx \&IP ,
384 .Sx \&LP ,
385 .Sx \&P ,
386 .Sx \&PP ,
387 and
388 .Sx \&TP .
389 .Ss \&I
390 Text is rendered in italics.
391 .Pp
392 See also
393 .Sx \&B .
394 .Ss \&IB
395 Text is rendered alternately in italics and bold face.
396 Whitespace between arguments is omitted in output.
397 .Pp
398 See
399 .Sx \&BI
400 for an equivalent example.
401 .Pp
402 See also
403 .Sx \&BI ,
404 .Sx \&BR ,
405 .Sx \&RB ,
406 .Sx \&RI ,
407 and
408 .Sx \&IR .
409 .Ss \&IP
410 Begin 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
416 The
417 .Ar width
418 argument is a
419 .Xr roff 7
420 scaling width defining the left margin.
421 It's saved for later paragraph left-margins; if unspecified, the saved or
422 default width is used.
423 .Pp
424 The
425 .Ar head
426 argument is used as a leading term, flushed to the left margin.
427 This is useful for bulleted paragraphs and so on.
428 .Pp
429 See also
430 .Sx \&HP ,
431 .Sx \&LP ,
432 .Sx \&P ,
433 .Sx \&PP ,
434 and
435 .Sx \&TP .
436 .Ss \&IR
437 Text is rendered alternately in italics and roman (the default font).
438 Whitespace between arguments is omitted in output.
439 .Pp
440 See
441 .Sx \&BI
442 for an equivalent example.
443 .Pp
444 See also
445 .Sx \&BI ,
446 .Sx \&IB ,
447 .Sx \&BR ,
448 .Sx \&RB ,
449 and
450 .Sx \&RI .
451 .Ss \&LP
452 Begin an undecorated paragraph.
453 The scope of a paragraph is closed by a subsequent paragraph,
454 sub-section, section, or end of file.
455 The saved paragraph left-margin width is reset to the default.
456 .Pp
457 See also
458 .Sx \&HP ,
459 .Sx \&IP ,
460 .Sx \&P ,
461 .Sx \&PP ,
462 and
463 .Sx \&TP .
464 .Ss \&ME
465 End a mailto block.
466 This is a non-standard GNU extension, included only for compatibility.
467 See
468 .Sx \&MT .
469 .Ss \&MT
470 Begin a mailto block.
471 This is a non-standard GNU extension, included only for compatibility.
472 It has the following syntax:
473 .Bd -literal -offset indent
474 .Pf \. Sx \&MT Ar address
475 link description to be shown
476 .Pf \. Sx ME
477 .Ed
478 .Ss \&OP
479 Optional command-line argument.
480 This is a non-standard GNU extension, included only for compatibility.
481 It has the following syntax:
482 .Bd -filled -offset indent
483 .Pf \. Sx \&OP
484 .Ar key Op Ar value
485 .Ed
486 .Pp
487 The
488 .Ar key
489 is usually a command-line flag and
490 .Ar value
491 its argument.
492 .Ss \&P
493 Synonym for
494 .Sx \&LP .
495 .Pp
496 See also
497 .Sx \&HP ,
498 .Sx \&IP ,
499 .Sx \&LP ,
500 .Sx \&PP ,
501 and
502 .Sx \&TP .
503 .Ss \&PD
504 Specify the vertical space to be inserted before each new paragraph.
505 .br
506 The syntax is as follows:
507 .Bd -filled -offset indent
508 .Pf \. Sx \&PD
509 .Op Ar height
510 .Ed
511 .Pp
512 The
513 .Ar height
514 argument is a
515 .Xr roff 7
516 scaling width.
517 It defaults to
518 .Cm 1v .
519 If the unit is omitted,
520 .Cm v
521 is assumed.
522 .Pp
523 This 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 ,
531 and
532 .Sx \&TP .
533 .Ss \&PP
534 Synonym for
535 .Sx \&LP .
536 .Pp
537 See also
538 .Sx \&HP ,
539 .Sx \&IP ,
540 .Sx \&LP ,
541 .Sx \&P ,
542 and
543 .Sx \&TP .
544 .Ss \&RB
545 Text is rendered alternately in roman (the default font) and bold face.
546 Whitespace between arguments is omitted in output.
547 .Pp
548 See
549 .Sx \&BI
550 for an equivalent example.
551 .Pp
552 See also
553 .Sx \&BI ,
554 .Sx \&IB ,
555 .Sx \&BR ,
556 .Sx \&RI ,
557 and
558 .Sx \&IR .
559 .Ss \&RE
560 Explicitly close out the scope of a prior
561 .Sx \&RS .
562 The default left margin is restored to the state before that
563 .Sx \&RS
564 invocation.
565 .Pp
566 The syntax is as follows:
567 .Bd -filled -offset indent
568 .Pf \. Sx \&RE
569 .Op Ar level
570 .Ed
571 .Pp
572 Without an argument, the most recent
573 .Sx \&RS
574 block is closed out.
575 If
576 .Ar level
577 is 1, all open
578 .Sx \&RS
579 blocks are closed out.
580 Otherwise,
581 .Ar level No \(mi 1
582 nested
583 .Sx \&RS
584 blocks remain open.
585 .Ss \&RI
586 Text is rendered alternately in roman (the default font) and italics.
587 Whitespace between arguments is omitted in output.
588 .Pp
589 See
590 .Sx \&BI
591 for an equivalent example.
592 .Pp
593 See also
594 .Sx \&BI ,
595 .Sx \&IB ,
596 .Sx \&BR ,
597 .Sx \&RB ,
598 and
599 .Sx \&IR .
600 .Ss \&RS
601 Temporarily reset the default left margin.
602 This has the following syntax:
603 .Bd -filled -offset indent
604 .Pf \. Sx \&RS
605 .Op Ar width
606 .Ed
607 .Pp
608 The
609 .Ar width
610 argument is a
611 .Xr roff 7
612 scaling width.
613 If not specified, the saved or default width is used.
614 .Pp
615 See also
616 .Sx \&RE .
617 .Ss \&SB
618 Text is rendered in small size (one point smaller than the default font)
619 bold face.
620 .Ss \&SH
621 Begin a section.
622 The scope of a section is only closed by another section or the end of
623 file.
624 The paragraph left-margin width is reset to the default.
625 .Ss \&SM
626 Text is rendered in small size (one point smaller than the default
627 font).
628 .Ss \&SS
629 Begin a sub-section.
630 The scope of a sub-section is closed by a subsequent sub-section,
631 section, or end of file.
632 The paragraph left-margin width is reset to the default.
633 .Ss \&TH
634 Sets the title of the manual page for use in the page header
635 and 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
642 Conventionally, the document
643 .Ar title
644 is given in all caps.
645 The recommended
646 .Ar date
647 format is
648 .Sy YYYY-MM-DD
649 as specified in the ISO-8601 standard;
650 if the argument does not conform, it is printed verbatim.
651 If the
652 .Ar date
653 is empty or not specified, the current date is used.
654 The optional
655 .Ar source
656 string specifies the organisation providing the utility.
657 When unspecified,
658 .Xr mandoc 1
659 uses its
660 .Fl Ios
661 argument.
662 The
663 .Ar volume
664 string replaces the default rendered volume, which is dictated by the
665 manual section.
666 .Pp
667 Examples:
668 .Pp
669 .Dl \&.TH CVS 5 "1992-02-12" GNU
670 .Ss \&TP
671 Begin a paragraph where the head, if exceeding the indentation width, is
672 followed by a newline; if not, the body follows on the same line after a
673 buffer to the indentation width.
674 Subsequent output lines are indented.
675 The syntax is as follows:
676 .Bd -filled -offset indent
677 .Pf \. Sx \&TP
678 .Op Ar width
679 .Ed
680 .Pp
681 The
682 .Ar width
683 argument is a
684 .Xr roff 7
685 scaling width.
686 If specified, it's saved for later paragraph left-margins; if
687 unspecified, the saved or default width is used.
688 .Pp
689 See also
690 .Sx \&HP ,
691 .Sx \&IP ,
692 .Sx \&LP ,
693 .Sx \&P ,
694 and
695 .Sx \&PP .
696 .Ss \&UC
697 Sets the volume for the footer for compatibility with man pages from
698 .Bx
699 releases.
700 The optional first argument specifies which release it is from.
701 .Ss \&UE
702 End a uniform resource identifier block.
703 This is a non-standard GNU extension, included only for compatibility.
704 See
705 .Sx \&UE .
706 .Ss \&UR
707 Begin a uniform resource identifier block.
708 This is a non-standard GNU extension, included only for compatibility.
709 It has the following syntax:
710 .Bd -literal -offset indent
711 .Pf \. Sx \&UR Ar uri
712 link description to be shown
713 .Pf \. Sx UE
714 .Ed
715 .Ss \&fi
716 End literal mode begun by
717 .Sx \&nf .
718 .Ss \&in
719 Indent relative to the current indentation:
720 .Pp
721 .D1 Pf \. Sx \&in Op Ar width
722 .Pp
723 If
724 .Ar width
725 is signed, the new offset is relative.
726 Otherwise, it is absolute.
727 This value is reset upon the next paragraph, section, or sub-section.
728 .Ss \&nf
729 Begin literal mode: all subsequent free-form lines have their end of
730 line boundaries preserved.
731 May be ended by
732 .Sx \&fi .
733 Literal mode is implicitly ended by
734 .Sx \&SH
735 or
736 .Sx \&SS .
737 .Sh MACRO SYNTAX
738 The
739 .Nm
740 macros are classified by scope: line scope or block scope.
741 Line macros are only scoped to the current line (and, in some
742 situations, the subsequent line).
743 Block macros are scoped to the current line and subsequent lines until
744 closed by another block macro.
745 .Ss Line Macros
746 Line macros are generally scoped to the current line, with the body
747 consisting of zero or more arguments.
748 If a macro is scoped to the next line and the line arguments are empty,
749 the next line, which must be text, is used instead.
750 Thus:
751 .Bd -literal -offset indent
752 \&.I
753 foo
754 .Ed
755 .Pp
756 is equivalent to
757 .Sq \&.I foo .
758 If next-line macros are invoked consecutively, only the last is used.
759 If a next-line macro is followed by a non-next-line macro, an error is
760 raised.
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 \&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
792 Macros marked as
793 .Qq compat
794 are included for compatibility with the significant corpus of existing
795 manuals that mix dialects of roff.
796 These macros should not be used for portable
797 .Nm
798 manuals.
799 .Ss Block Macros
800 Block macros comprise a head and body.
801 As with in-line macros, the head is scoped to the current line and, in
802 one circumstance, the next line (the next-line stipulations as in
803 .Sx Line Macros
804 apply here as well).
805 .Pp
806 The syntax is as follows:
807 .Bd -literal -offset indent
808 \&.YO \(lBhead...\(rB
809 \(lBhead...\(rB
810 \(lBbody...\(rB
811 .Ed
812 .Pp
813 The closure of body scope may be to the section, where a macro is closed
814 by
815 .Sx \&SH ;
816 sub-section, closed by a section or
817 .Sx \&SS ;
818 part, closed by a section, sub-section, or
819 .Sx \&RE ;
820 or paragraph, closed by a section, sub-section, part,
821 .Sx \&HP ,
822 .Sx \&IP ,
823 .Sx \&LP ,
824 .Sx \&P ,
825 .Sx \&PP ,
826 or
827 .Sx \&TP .
828 No closure refers to an explicit block closing macro.
829 .Pp
830 As a rule, block macros may not be nested; thus, calling a block macro
831 while another block macro scope is open, and the open scope is not
832 implicitly 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
849 Macros marked
850 .Qq compat
851 are as mentioned in
852 .Sx Line Macros .
853 .Pp
854 If a block macro is next-line scoped, it may only be followed by in-line
855 macros for decorating text.
856 .Ss Font handling
857 In
858 .Nm
859 documents, both
860 .Sx Physical markup
861 macros and
862 .Xr roff 7
863 .Ql \ef
864 font escape sequences can be used to choose fonts.
865 In text lines, the effect of manual font selection by escape sequences
866 only lasts until the next macro invocation; in macro lines, it only lasts
867 until the end of the macro scope.
868 Note that macros like
869 .Sx \&BR
870 open 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
880 The
881 .Nm
882 language first appeared as a macro package for the roff typesetting
883 system in
884 .At v7 .
885 It was later rewritten by James Clark as a macro package for groff.
886 Eric S. Raymond wrote the extended
887 .Nm
888 macros for groff in 2007.
889 The stand-alone implementation that is part of the
890 .Xr mandoc 1
891 utility written by Kristaps Dzonsons appeared in
892 .Ox 4.6 .
893 .Sh AUTHORS
894 This
895 .Nm
896 reference was written by
897 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
898 .Sh CAVEATS
899 Do not use this language.
900 Use
901 .Xr mdoc 7 ,
902 instead.