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