| blob | 48f35b489efd7d1e481d2e826de090591e331c37 |
1 .\" $Vendor-Id: man.7,v 1.113 2012/01/03 15:16:24 kristaps Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2011 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 January 3, 2012
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 \&br Ta force output line break in text mode (no arguments)
257 .It Sx \&sp Ta force vertical space: Op Ar height
258 .It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
259 .It Sx in Ta additional indent: Op Ar width
260 .El
261 .Ss Physical markup
262 .Bl -column "PP, LP, P" description
263 .It Sx B Ta boldface font
264 .It Sx I Ta italic font
265 .It Sx R Ta roman (default) font
266 .It Sx SB Ta small boldface font
267 .It Sx SM Ta small roman font
268 .It Sx BI Ta alternate between boldface and italic fonts
269 .It Sx BR Ta alternate between boldface and roman fonts
270 .It Sx IB Ta alternate between italic and boldface fonts
271 .It Sx IR Ta alternate between italic and roman fonts
272 .It Sx RB Ta alternate between roman and boldface fonts
273 .It Sx RI Ta alternate between roman and italic fonts
274 .El
275 .Ss Semantic markup
276 .Bl -column "PP, LP, P" description
277 .It Sx OP Ta optional arguments
278 .El
279 .Sh MACRO REFERENCE
280 This section is a canonical reference to all macros, arranged
281 alphabetically.
282 For the scoping of individual macros, see
283 .Sx MACRO SYNTAX .
284 .Ss \&AT
285 Sets the volume for the footer for compatibility with man pages from
286 .Tn AT&T UNIX
287 releases.
288 The optional arguments specify which release it is from.
289 .Ss \&B
290 Text is rendered in bold face.
291 .Pp
292 See also
293 .Sx \&I
294 and
295 .Sx \&R .
296 .Ss \&BI
297 Text is rendered alternately in bold face and italic.
298 Thus,
299 .Sq .BI this word and that
300 causes
301 .Sq this
302 and
303 .Sq and
304 to render in bold face, while
305 .Sq word
306 and
307 .Sq that
308 render in italics.
309 Whitespace between arguments is omitted in output.
310 .Pp
311 Examples:
312 .Pp
313 .Dl \&.BI bold italic bold italic
314 .Pp
315 The output of this example will be emboldened
316 .Dq bold
317 and italicised
318 .Dq italic ,
319 with spaces stripped between arguments.
320 .Pp
321 See also
322 .Sx \&IB ,
323 .Sx \&BR ,
324 .Sx \&RB ,
325 .Sx \&RI ,
326 and
327 .Sx \&IR .
328 .Ss \&BR
329 Text is rendered alternately in bold face and roman (the default font).
330 Whitespace between arguments is omitted in output.
331 .Pp
332 See
333 .Sx \&BI
334 for an equivalent example.
335 .Pp
336 See also
337 .Sx \&BI ,
338 .Sx \&IB ,
339 .Sx \&RB ,
340 .Sx \&RI ,
341 and
342 .Sx \&IR .
343 .Ss \&DT
344 Has no effect.
345 Included for compatibility.
346 .Ss \&HP
347 Begin a paragraph whose initial output line is left-justified, but
348 subsequent output lines are indented, with the following syntax:
349 .Bd -filled -offset indent
350 .Pf \. Sx \&HP
351 .Op Cm width
352 .Ed
353 .Pp
354 The
355 .Cm width
356 argument must conform to
357 .Sx Scaling Widths .
358 If specified, it's saved for later paragraph left-margins; if unspecified, the
359 saved or default width is used.
360 .Pp
361 See also
362 .Sx \&IP ,
363 .Sx \&LP ,
364 .Sx \&P ,
365 .Sx \&PP ,
366 and
367 .Sx \&TP .
368 .Ss \&I
369 Text is rendered in italics.
370 .Pp
371 See also
372 .Sx \&B
373 and
374 .Sx \&R .
375 .Ss \&IB
376 Text is rendered alternately in italics and bold face.
377 Whitespace between arguments is omitted in output.
378 .Pp
379 See
380 .Sx \&BI
381 for an equivalent example.
382 .Pp
383 See also
384 .Sx \&BI ,
385 .Sx \&BR ,
386 .Sx \&RB ,
387 .Sx \&RI ,
388 and
389 .Sx \&IR .
390 .Ss \&IP
391 Begin an indented paragraph with the following syntax:
392 .Bd -filled -offset indent
393 .Pf \. Sx \&IP
394 .Op Cm head Op Cm width
395 .Ed
396 .Pp
397 The
398 .Cm width
399 argument defines the width of the left margin and is defined by
400 .Sx Scaling Widths .
401 It's saved for later paragraph left-margins; if unspecified, the saved or
402 default width is used.
403 .Pp
404 The
405 .Cm head
406 argument is used as a leading term, flushed to the left margin.
407 This is useful for bulleted paragraphs and so on.
408 .Pp
409 See also
410 .Sx \&HP ,
411 .Sx \&LP ,
412 .Sx \&P ,
413 .Sx \&PP ,
414 and
415 .Sx \&TP .
416 .Ss \&IR
417 Text is rendered alternately in italics and roman (the default font).
418 Whitespace between arguments is omitted in output.
419 .Pp
420 See
421 .Sx \&BI
422 for an equivalent example.
423 .Pp
424 See also
425 .Sx \&BI ,
426 .Sx \&IB ,
427 .Sx \&BR ,
428 .Sx \&RB ,
429 and
430 .Sx \&RI .
431 .Ss \&LP
432 Begin an undecorated paragraph.
433 The scope of a paragraph is closed by a subsequent paragraph,
434 sub-section, section, or end of file.
435 The saved paragraph left-margin width is reset to the default.
436 .Pp
437 See also
438 .Sx \&HP ,
439 .Sx \&IP ,
440 .Sx \&P ,
441 .Sx \&PP ,
442 and
443 .Sx \&TP .
444 .Ss \&OP
445 Optional command-line argument.
446 This has the following syntax:
447 .Bd -filled -offset indent
448 .Pf \. Sx \&OP
449 .Cm key Op Cm value
450 .Ed
451 .Pp
452 The
453 .Cm key
454 is usually a command-line flag and
455 .Cm value
456 its argument.
457 .Ss \&P
458 Synonym for
459 .Sx \&LP .
460 .Pp
461 See also
462 .Sx \&HP ,
463 .Sx \&IP ,
464 .Sx \&LP ,
465 .Sx \&PP ,
466 and
467 .Sx \&TP .
468 .Ss \&PP
469 Synonym for
470 .Sx \&LP .
471 .Pp
472 See also
473 .Sx \&HP ,
474 .Sx \&IP ,
475 .Sx \&LP ,
476 .Sx \&P ,
477 and
478 .Sx \&TP .
479 .Ss \&R
480 Text is rendered in roman (the default font).
481 .Pp
482 See also
483 .Sx \&I
484 and
485 .Sx \&B .
486 .Ss \&RB
487 Text is rendered alternately in roman (the default font) and bold face.
488 Whitespace between arguments is omitted in output.
489 .Pp
490 See
491 .Sx \&BI
492 for an equivalent example.
493 .Pp
494 See also
495 .Sx \&BI ,
496 .Sx \&IB ,
497 .Sx \&BR ,
498 .Sx \&RI ,
499 and
500 .Sx \&IR .
501 .Ss \&RE
502 Explicitly close out the scope of a prior
503 .Sx \&RS .
504 The default left margin is restored to the state of the original
505 .Sx \&RS
506 invocation.
507 .Ss \&RI
508 Text is rendered alternately in roman (the default font) and italics.
509 Whitespace between arguments is omitted in output.
510 .Pp
511 See
512 .Sx \&BI
513 for an equivalent example.
514 .Pp
515 See also
516 .Sx \&BI ,
517 .Sx \&IB ,
518 .Sx \&BR ,
519 .Sx \&RB ,
520 and
521 .Sx \&IR .
522 .Ss \&RS
523 Temporarily reset the default left margin.
524 This has the following syntax:
525 .Bd -filled -offset indent
526 .Pf \. Sx \&RS
527 .Op Cm width
528 .Ed
529 .Pp
530 The
531 .Cm width
532 argument must conform to
533 .Sx Scaling Widths .
534 If not specified, the saved or default width is used.
535 .Pp
536 See also
537 .Sx \&RE .
538 .Ss \&SB
539 Text is rendered in small size (one point smaller than the default font)
540 bold face.
541 .Ss \&SH
542 Begin a section.
543 The scope of a section is only closed by another section or the end of
544 file.
545 The paragraph left-margin width is reset to the default.
546 .Ss \&SM
547 Text is rendered in small size (one point smaller than the default
548 font).
549 .Ss \&SS
550 Begin a sub-section.
551 The scope of a sub-section is closed by a subsequent sub-section,
552 section, or end of file.
553 The paragraph left-margin width is reset to the default.
554 .Ss \&TH
555 Sets the title of the manual page with the following syntax:
556 .Bd -filled -offset indent
557 .Pf \. Sx \&TH
558 .Ar title section date
559 .Op Ar source Op Ar volume
560 .Ed
561 .Pp
562 Conventionally, the document
563 .Ar title
564 is given in all caps.
565 The recommended
566 .Ar date
567 format is
568 .Sy YYYY-MM-DD
569 as specified in the ISO-8601 standard;
570 if the argument does not conform, it is printed verbatim.
571 If the
572 .Ar date
573 is empty or not specified, the current date is used.
574 The optional
575 .Ar source
576 string specifies the organisation providing the utility.
577 The
578 .Ar volume
579 string replaces the default rendered volume, which is dictated by the
580 manual section.
581 .Pp
582 Examples:
583 .Pp
584 .Dl \&.TH CVS 5 "1992-02-12" GNU
585 .Ss \&TP
586 Begin a paragraph where the head, if exceeding the indentation width, is
587 followed by a newline; if not, the body follows on the same line after a
588 buffer to the indentation width.
589 Subsequent output lines are indented.
590 The syntax is as follows:
591 .Bd -filled -offset indent
592 .Pf \. Sx \&TP
593 .Op Cm width
594 .Ed
595 .Pp
596 The
597 .Cm width
598 argument must conform to
599 .Sx Scaling Widths .
600 If specified, it's saved for later paragraph left-margins; if
601 unspecified, the saved or default width is used.
602 .Pp
603 See also
604 .Sx \&HP ,
605 .Sx \&IP ,
606 .Sx \&LP ,
607 .Sx \&P ,
608 and
609 .Sx \&PP .
610 .Ss \&UC
611 Sets the volume for the footer for compatibility with man pages from
612 BSD releases.
613 The optional first argument specifies which release it is from.
614 .Ss \&br
615 Breaks the current line.
616 Consecutive invocations have no further effect.
617 .Pp
618 See also
619 .Sx \&sp .
620 .Ss \&fi
621 End literal mode begun by
622 .Sx \&nf .
623 .Ss \&ft
624 Change the current font mode.
625 See
626 .Sx Text Decoration
627 for a listing of available font modes.
628 .Ss \&in
629 Indent relative to the current indentation:
630 .Pp
631 .D1 Pf \. Sx \&in Op Cm width
632 .Pp
633 If
634 .Cm width
635 is signed, the new offset is relative.
636 Otherwise, it is absolute.
637 This value is reset upon the next paragraph, section, or sub-section.
638 .Ss \&na
639 Don't align to the right margin.
640 .Ss \&nf
641 Begin literal mode: all subsequent free-form lines have their end of
642 line boundaries preserved.
643 May be ended by
644 .Sx \&fi .
645 Literal mode is implicitly ended by
646 .Sx \&SH
647 or
648 .Sx \&SS .
649 .Ss \&sp
650 Insert vertical spaces into output with the following syntax:
651 .Bd -filled -offset indent
652 .Pf \. Sx \&sp
653 .Op Cm height
654 .Ed
655 .Pp
656 Insert
657 .Cm height
658 spaces, which must conform to
659 .Sx Scaling Widths .
660 If 0, this is equivalent to the
661 .Sx \&br
662 macro.
663 Defaults to 1, if unspecified.
664 .Pp
665 See also
666 .Sx \&br .
667 .Sh MACRO SYNTAX
668 The
669 .Nm
670 macros are classified by scope: line scope or block scope.
671 Line macros are only scoped to the current line (and, in some
672 situations, the subsequent line).
673 Block macros are scoped to the current line and subsequent lines until
674 closed by another block macro.
675 .Ss Line Macros
676 Line macros are generally scoped to the current line, with the body
677 consisting of zero or more arguments.
678 If a macro is scoped to the next line and the line arguments are empty,
679 the next line, which must be text, is used instead.
680 Thus:
681 .Bd -literal -offset indent
682 \&.I
683 foo
684 .Ed
685 .Pp
686 is equivalent to
687 .Sq \&.I foo .
688 If next-line macros are invoked consecutively, only the last is used.
689 If a next-line macro is followed by a non-next-line macro, an error is
690 raised, except for
691 .Sx \&br ,
692 .Sx \&sp ,
693 and
694 .Sx \&na .
695 .Pp
696 The syntax is as follows:
697 .Bd -literal -offset indent
698 \&.YO \(lBbody...\(rB
699 \(lBbody...\(rB
700 .Ed
701 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
702 .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
703 .It Sx \&AT Ta <=1 Ta current Ta \&
704 .It Sx \&B Ta n Ta next-line Ta \&
705 .It Sx \&BI Ta n Ta current Ta \&
706 .It Sx \&BR Ta n Ta current Ta \&
707 .It Sx \&DT Ta 0 Ta current Ta \&
708 .It Sx \&I Ta n Ta next-line Ta \&
709 .It Sx \&IB Ta n Ta current Ta \&
710 .It Sx \&IR Ta n Ta current Ta \&
711 .It Sx \&OP Ta 0, 1 Ta current Ta compat
712 .It Sx \&R Ta n Ta next-line Ta \&
713 .It Sx \&RB Ta n Ta current Ta \&
714 .It Sx \&RI Ta n Ta current Ta \&
715 .It Sx \&SB Ta n Ta next-line Ta \&
716 .It Sx \&SM Ta n Ta next-line Ta \&
717 .It Sx \&TH Ta >1, <6 Ta current Ta \&
718 .It Sx \&UC Ta <=1 Ta current Ta \&
719 .It Sx \&br Ta 0 Ta current Ta compat
720 .It Sx \&fi Ta 0 Ta current Ta compat
721 .It Sx \&ft Ta 1 Ta current Ta compat
722 .It Sx \&in Ta 1 Ta current Ta compat
723 .It Sx \&na Ta 0 Ta current Ta compat
724 .It Sx \&nf Ta 0 Ta current Ta compat
725 .It Sx \&sp Ta 1 Ta current Ta compat
726 .El
727 .Pp
728 Macros marked as
729 .Qq compat
730 are included for compatibility with the significant corpus of existing
731 manuals that mix dialects of roff.
732 These macros should not be used for portable
733 .Nm
734 manuals.
735 .Ss Block Macros
736 Block macros comprise a head and body.
737 As with in-line macros, the head is scoped to the current line and, in
738 one circumstance, the next line (the next-line stipulations as in
739 .Sx Line Macros
740 apply here as well).
741 .Pp
742 The syntax is as follows:
743 .Bd -literal -offset indent
744 \&.YO \(lBhead...\(rB
745 \(lBhead...\(rB
746 \(lBbody...\(rB
747 .Ed
748 .Pp
749 The closure of body scope may be to the section, where a macro is closed
750 by
751 .Sx \&SH ;
752 sub-section, closed by a section or
753 .Sx \&SS ;
754 part, closed by a section, sub-section, or
755 .Sx \&RE ;
756 or paragraph, closed by a section, sub-section, part,
757 .Sx \&HP ,
758 .Sx \&IP ,
759 .Sx \&LP ,
760 .Sx \&P ,
761 .Sx \&PP ,
762 or
763 .Sx \&TP .
764 No closure refers to an explicit block closing macro.
765 .Pp
766 As a rule, block macros may not be nested; thus, calling a block macro
767 while another block macro scope is open, and the open scope is not
768 implicitly closed, is syntactically incorrect.
769 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
770 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
771 .It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
772 .It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
773 .It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
774 .It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
775 .It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
776 .It Sx \&RE Ta 0 Ta current Ta none Ta compat
777 .It Sx \&RS Ta 1 Ta current Ta part Ta compat
778 .It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
779 .It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
780 .It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
781 .El
782 .Pp
783 Macros marked
784 .Qq compat
785 are as mentioned in
786 .Sx Line Macros .
787 .Pp
788 If a block macro is next-line scoped, it may only be followed by in-line
789 macros for decorating text.
790 .Ss Font handling
791 In
792 .Nm
793 documents, both
794 .Sx Physical markup
795 macros and
796 .Xr roff 7
797 .Ql \ef
798 font escape sequences can be used to choose fonts.
799 In text lines, the effect of manual font selection by escape sequences
800 only lasts until the next macro invocation; in macro lines, it only lasts
801 until the end of the macro scope.
802 Note that macros like
803 .Sx \&BR
804 open and close a font scope for each argument.
805 .Sh COMPATIBILITY
806 This section documents areas of questionable portability between
807 implementations of the
808 .Nm
809 language.
810 .Pp
811 .Bl -dash -compact
812 .It
813 Do not depend on
814 .Sx \&SH
815 or
816 .Sx \&SS
817 to close out a literal context opened with
818 .Sx \&nf .
819 This behaviour may not be portable.
820 .It
821 In quoted literals, GNU troff allowed pair-wise double-quotes to produce
822 a standalone double-quote in formatted output.
823 It is not known whether this behaviour is exhibited by other formatters.
824 .It
825 troff suppresses a newline before
826 .Sq \(aq
827 macro output; in mandoc, it is an alias for the standard
828 .Sq \&.
829 control character.
830 .It
831 The
832 .Sq \eh
833 .Pq horizontal position ,
834 .Sq \ev
835 .Pq vertical position ,
836 .Sq \em
837 .Pq text colour ,
838 .Sq \eM
839 .Pq text filling colour ,
840 .Sq \ez
841 .Pq zero-length character ,
842 .Sq \ew
843 .Pq string length ,
844 .Sq \ek
845 .Pq horizontal position marker ,
846 .Sq \eo
847 .Pq text overstrike ,
848 and
849 .Sq \es
850 .Pq text size
851 escape sequences are all discarded in mandoc.
852 .It
853 The
854 .Sq \ef
855 scaling unit is accepted by mandoc, but rendered as the default unit.
856 .It
857 The
858 .Sx \&sp
859 macro does not accept negative values in mandoc.
860 In GNU troff, this would result in strange behaviour.
861 .It
862 In page header lines, GNU troff versions up to and including 1.21
863 only print
864 .Ar volume
865 names explicitly specified in the
866 .Sx \&TH
867 macro; mandoc and newer groff print the default volume name
868 corresponding to the
869 .Ar section
870 number when no
871 .Ar volume
872 is given, like in
873 .Xr mdoc 7 .
874 .El
875 .Pp
876 The
877 .Sx OP
878 macro is part of the extended
879 .Nm
880 macro set, and may not be portable to non-GNU troff implementations.
881 .Sh SEE ALSO
882 .Xr man 1 ,
883 .Xr mandoc 1 ,
884 .Xr eqn 7 ,
885 .Xr mandoc_char 7 ,
886 .Xr mdoc 7 ,
887 .Xr roff 7 ,
888 .Xr tbl 7
889 .Sh HISTORY
890 The
891 .Nm
892 language first appeared as a macro package for the roff typesetting
893 system in
894 .At v7 .
895 It was later rewritten by James Clark as a macro package for groff.
896 Eric S. Raymond wrote the extended
897 .Nm
898 macros for groff in 2007.
899 The stand-alone implementation that is part of the
900 .Xr mandoc 1
901 utility written by Kristaps Dzonsons appeared in
902 .Ox 4.6 .
903 .Sh AUTHORS
904 This
905 .Nm
906 reference was written by
907 .An Kristaps Dzonsons ,
908 .Mt kristaps@bsd.lv .
909 .Sh CAVEATS
910 Do not use this language.
911 Use
912 .Xr mdoc 7 ,
913 instead.