Annotation of mandoc/man.7, Revision 1.147
1.147 ! schwarze 1: .\" $Id: man.7,v 1.146 2020/10/14 14:22:54 schwarze Exp $
1.1 kristaps 2: .\"
1.115 schwarze 3: .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.145 schwarze 4: .\" Copyright (c) 2011-2015, 2017-2020 Ingo Schwarze <schwarze@openbsd.org>
1.139 schwarze 5: .\" Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org>
1.122 schwarze 6: .\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
1.1 kristaps 7: .\"
8: .\" Permission to use, copy, modify, and distribute this software for any
1.10 kristaps 9: .\" purpose with or without fee is hereby granted, provided that the above
10: .\" copyright notice and this permission notice appear in all copies.
11: .\"
12: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
13: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
14: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
15: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
16: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
17: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 kristaps 19: .\"
1.147 ! schwarze 20: .Dd $Mdocdate: October 14 2020 $
1.9 kristaps 21: .Dt MAN 7
1.1 kristaps 22: .Os
23: .Sh NAME
1.32 kristaps 24: .Nm man
1.111 schwarze 25: .Nd legacy formatting language for manual pages
1.1 kristaps 26: .Sh DESCRIPTION
1.140 schwarze 27: The
1.32 kristaps 28: .Nm man
1.140 schwarze 29: language was the standard formatting language for
30: .At
31: manual pages from 1979 to 1989.
32: Do not use it to write new manual pages: it is a purely presentational
33: language and lacks support for semantic markup.
1.19 kristaps 34: Use the
1.32 kristaps 35: .Xr mdoc 7
1.1 kristaps 36: language, instead.
1.32 kristaps 37: .Pp
1.111 schwarze 38: In a
1.32 kristaps 39: .Nm
1.111 schwarze 40: document, lines beginning with the control character
1.32 kristaps 41: .Sq \&.
1.111 schwarze 42: are called
43: .Dq macro lines .
44: The first word is the macro name.
45: It usually consists of two capital letters.
1.140 schwarze 46: For a list of portable macros, see
1.111 schwarze 47: .Sx MACRO OVERVIEW .
48: The words following the macro name are arguments to the macro.
49: .Pp
50: Lines not beginning with the control character are called
51: .Dq text lines .
52: They provide free-form text to be printed; the formatting of the text
53: depends on the respective processing context:
1.32 kristaps 54: .Bd -literal -offset indent
1.1 kristaps 55: \&.SH Macro lines change control state.
1.106 kristaps 56: Text lines are interpreted within the current state.
1.32 kristaps 57: .Ed
1.103 kristaps 58: .Pp
1.111 schwarze 59: Many aspects of the basic syntax of the
1.103 kristaps 60: .Nm
1.111 schwarze 61: language are based on the
62: .Xr roff 7
63: language; see the
64: .Em LANGUAGE SYNTAX
1.106 kristaps 65: and
1.111 schwarze 66: .Em MACRO SYNTAX
67: sections in the
68: .Xr roff 7
69: manual for details, in particular regarding
70: comments, escape sequences, whitespace, and quoting.
1.140 schwarze 71: .Pp
1.16 kristaps 72: Each
1.32 kristaps 73: .Nm
1.140 schwarze 74: document starts with the
1.143 schwarze 75: .Ic TH
1.140 schwarze 76: macro specifying the document's name and section, followed by the
77: .Sx NAME
78: section formatted as follows:
1.32 kristaps 79: .Bd -literal -offset indent
1.140 schwarze 80: \&.TH PROGNAME 1 1979-01-10
1.22 kristaps 81: \&.SH NAME
1.124 schwarze 82: \efBprogname\efR \e(en one line about what it does
1.32 kristaps 83: .Ed
1.110 schwarze 84: .Sh MACRO OVERVIEW
85: This overview is sorted such that macros of similar purpose are listed
1.140 schwarze 86: together.
87: Deprecated and non-portable macros are not included in the overview,
88: but can be found in the alphabetical reference below.
1.110 schwarze 89: .Ss Page header and footer meta-data
1.140 schwarze 90: .Bl -column "RS, RE" description
1.143 schwarze 91: .It Ic TH Ta set the title: Ar name section date Op Ar source Op Ar volume
92: .It Ic AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
93: .It Ic UC Ta display BSD version in the page footer (<= 1 argument)
1.110 schwarze 94: .El
95: .Ss Sections and paragraphs
1.140 schwarze 96: .Bl -column "RS, RE" description
1.143 schwarze 97: .It Ic SH Ta section header (one line)
98: .It Ic SS Ta subsection header (one line)
99: .It Ic PP Ta start an undecorated paragraph (no arguments)
100: .It Ic RS , RE Ta reset the left margin: Op Ar width
101: .It Ic IP Ta indented paragraph: Op Ar head Op Ar width
102: .It Ic TP Ta tagged paragraph: Op Ar width
103: .It Ic PD Ta set vertical paragraph distance: Op Ar height
104: .It Ic in Ta additional indent: Op Ar width
1.110 schwarze 105: .El
106: .Ss Physical markup
1.140 schwarze 107: .Bl -column "RS, RE" description
1.143 schwarze 108: .It Ic B Ta boldface font
109: .It Ic I Ta italic font
110: .It Ic SB Ta small boldface font
111: .It Ic SM Ta small roman font
112: .It Ic BI Ta alternate between boldface and italic fonts
113: .It Ic BR Ta alternate between boldface and roman fonts
114: .It Ic IB Ta alternate between italic and boldface fonts
115: .It Ic IR Ta alternate between italic and roman fonts
116: .It Ic RB Ta alternate between roman and boldface fonts
117: .It Ic RI Ta alternate between roman and italic fonts
1.110 schwarze 118: .El
1.111 schwarze 119: .Sh MACRO REFERENCE
1.22 kristaps 120: This section is a canonical reference to all macros, arranged
1.68 kristaps 121: alphabetically.
122: For the scoping of individual macros, see
1.32 kristaps 123: .Sx MACRO SYNTAX .
1.143 schwarze 124: .Bl -tag -width 3n
125: .It Ic AT
1.72 joerg 126: Sets the volume for the footer for compatibility with man pages from
1.123 schwarze 127: .At
1.72 joerg 128: releases.
129: The optional arguments specify which release it is from.
1.145 schwarze 130: This macro is an extension that first appeared in
131: .Bx 4.3 .
1.143 schwarze 132: .It Ic B
1.22 kristaps 133: Text is rendered in bold face.
1.143 schwarze 134: .It Ic BI
1.68 kristaps 135: Text is rendered alternately in bold face and italic.
136: Thus,
1.32 kristaps 137: .Sq .BI this word and that
1.22 kristaps 138: causes
1.32 kristaps 139: .Sq this
1.22 kristaps 140: and
1.32 kristaps 141: .Sq and
1.55 kristaps 142: to render in bold face, while
1.32 kristaps 143: .Sq word
1.22 kristaps 144: and
1.32 kristaps 145: .Sq that
1.68 kristaps 146: render in italics.
147: Whitespace between arguments is omitted in output.
1.44 kristaps 148: .Pp
1.140 schwarze 149: Example:
1.46 kristaps 150: .Pp
1.93 kristaps 151: .Dl \&.BI bold italic bold italic
1.143 schwarze 152: .It Ic BR
1.22 kristaps 153: Text is rendered alternately in bold face and roman (the default font).
154: Whitespace between arguments is omitted in output.
1.44 kristaps 155: See also
1.143 schwarze 156: .Ic BI .
157: .It Ic DT
1.135 schwarze 158: Restore the default tabulator positions.
159: They are at intervals of 0.5 inches.
160: This has no effect unless the tabulator positions were changed with the
161: .Xr roff 7
1.143 schwarze 162: .Ic ta
1.135 schwarze 163: request.
1.143 schwarze 164: .It Ic EE
1.144 schwarze 165: This is a non-standard Version 9
166: .At
167: extension later adopted by GNU.
1.116 schwarze 168: In
169: .Xr mandoc 1 ,
1.142 schwarze 170: it does the same as the
171: .Xr roff 7
1.143 schwarze 172: .Ic fi
1.142 schwarze 173: request (switch to fill mode).
1.143 schwarze 174: .It Ic EX
1.144 schwarze 175: This is a non-standard Version 9
176: .At
177: extension later adopted by GNU.
1.116 schwarze 178: In
179: .Xr mandoc 1 ,
1.142 schwarze 180: it does the same as the
181: .Xr roff 7
1.143 schwarze 182: .Ic nf
1.142 schwarze 183: request (switch to no-fill mode).
1.143 schwarze 184: .It Ic HP
1.23 kristaps 185: Begin a paragraph whose initial output line is left-justified, but
1.27 kristaps 186: subsequent output lines are indented, with the following syntax:
1.143 schwarze 187: .Pp
188: .D1 Pf . Ic HP Op Ar width
1.44 kristaps 189: .Pp
190: The
1.130 schwarze 191: .Ar width
1.117 schwarze 192: argument is a
193: .Xr roff 7
194: scaling width.
1.141 schwarze 195: If specified, it's saved for later paragraph left margins;
196: if unspecified, the saved or default width is used.
197: .Pp
198: This macro is portable, but deprecated
199: because it has no good representation in HTML output,
200: usually ending up indistinguishable from
1.143 schwarze 201: .Ic PP .
202: .It Ic I
1.22 kristaps 203: Text is rendered in italics.
1.143 schwarze 204: .It Ic IB
1.80 kristaps 205: Text is rendered alternately in italics and bold face.
206: Whitespace between arguments is omitted in output.
1.44 kristaps 207: See also
1.143 schwarze 208: .Ic BI .
209: .It Ic IP
1.44 kristaps 210: Begin an indented paragraph with the following syntax:
1.143 schwarze 211: .Pp
212: .D1 Pf . Ic IP Op Ar head Op Ar width
1.44 kristaps 213: .Pp
214: The
1.130 schwarze 215: .Ar width
1.117 schwarze 216: argument is a
217: .Xr roff 7
218: scaling width defining the left margin.
1.44 kristaps 219: It's saved for later paragraph left-margins; if unspecified, the saved or
220: default width is used.
221: .Pp
222: The
1.130 schwarze 223: .Ar head
1.68 kristaps 224: argument is used as a leading term, flushed to the left margin.
225: This is useful for bulleted paragraphs and so on.
1.143 schwarze 226: .It Ic IR
1.22 kristaps 227: Text is rendered alternately in italics and roman (the default font).
228: Whitespace between arguments is omitted in output.
1.44 kristaps 229: See also
1.143 schwarze 230: .Ic BI .
231: .It Ic LP
1.140 schwarze 232: A synonym for
1.143 schwarze 233: .Ic PP .
234: .It Ic ME
1.140 schwarze 235: End a mailto block started with
1.143 schwarze 236: .Ic MT .
1.140 schwarze 237: This is a non-standard GNU extension.
1.143 schwarze 238: .It Ic MT
1.136 schwarze 239: Begin a mailto block.
1.140 schwarze 240: This is a non-standard GNU extension.
1.136 schwarze 241: It has the following syntax:
1.143 schwarze 242: .Bd -unfilled -offset indent
243: .Pf . Ic MT Ar address
1.136 schwarze 244: link description to be shown
1.143 schwarze 245: .Pf . Ic ME
1.136 schwarze 246: .Ed
1.143 schwarze 247: .It Ic OP
1.113 kristaps 248: Optional command-line argument.
1.140 schwarze 249: This is a non-standard GNU extension.
1.114 schwarze 250: It has the following syntax:
1.143 schwarze 251: .Pp
252: .D1 Pf . Ic OP Ar key Op Ar value
1.113 kristaps 253: .Pp
254: The
1.130 schwarze 255: .Ar key
1.113 kristaps 256: is usually a command-line flag and
1.130 schwarze 257: .Ar value
1.113 kristaps 258: its argument.
1.143 schwarze 259: .It Ic P
1.145 schwarze 260: This synonym for
261: .Ic PP
262: is an
263: .At III
264: extension later adopted by
265: .Bx 4.3 .
1.143 schwarze 266: .It Ic PD
1.118 schwarze 267: Specify the vertical space to be inserted before each new paragraph.
268: .br
269: The syntax is as follows:
1.143 schwarze 270: .Pp
271: .D1 Pf . Ic PD Op Ar height
1.118 schwarze 272: .Pp
273: The
1.130 schwarze 274: .Ar height
1.118 schwarze 275: argument is a
276: .Xr roff 7
277: scaling width.
278: It defaults to
279: .Cm 1v .
280: If the unit is omitted,
281: .Cm v
282: is assumed.
283: .Pp
284: This macro affects the spacing before any subsequent instances of
1.143 schwarze 285: .Ic HP ,
286: .Ic IP ,
287: .Ic LP ,
288: .Ic P ,
289: .Ic PP ,
290: .Ic SH ,
291: .Ic SS ,
292: .Ic SY ,
1.44 kristaps 293: and
1.143 schwarze 294: .Ic TP .
295: .It Ic PP
1.140 schwarze 296: Begin an undecorated paragraph.
297: The scope of a paragraph is closed by a subsequent paragraph,
298: sub-section, section, or end of file.
299: The saved paragraph left-margin width is reset to the default.
1.143 schwarze 300: .It Ic RB
1.22 kristaps 301: Text is rendered alternately in roman (the default font) and bold face.
302: Whitespace between arguments is omitted in output.
1.44 kristaps 303: See also
1.143 schwarze 304: .Ic BI .
305: .It Ic RE
1.30 kristaps 306: Explicitly close out the scope of a prior
1.143 schwarze 307: .Ic RS .
1.129 schwarze 308: The default left margin is restored to the state before that
1.143 schwarze 309: .Ic RS
1.102 kristaps 310: invocation.
1.129 schwarze 311: .Pp
312: The syntax is as follows:
1.143 schwarze 313: .Pp
314: .D1 Pf . Ic RE Op Ar level
1.129 schwarze 315: .Pp
316: Without an argument, the most recent
1.143 schwarze 317: .Ic RS
1.129 schwarze 318: block is closed out.
319: If
320: .Ar level
321: is 1, all open
1.143 schwarze 322: .Ic RS
1.129 schwarze 323: blocks are closed out.
324: Otherwise,
325: .Ar level No \(mi 1
326: nested
1.143 schwarze 327: .Ic RS
1.129 schwarze 328: blocks remain open.
1.143 schwarze 329: .It Ic RI
1.22 kristaps 330: Text is rendered alternately in roman (the default font) and italics.
331: Whitespace between arguments is omitted in output.
1.44 kristaps 332: See also
1.143 schwarze 333: .Ic BI .
334: .It Ic RS
1.102 kristaps 335: Temporarily reset the default left margin.
1.44 kristaps 336: This has the following syntax:
1.143 schwarze 337: .Pp
338: .D1 Pf . Ic RS Op Ar width
1.44 kristaps 339: .Pp
340: The
1.130 schwarze 341: .Ar width
1.117 schwarze 342: argument is a
343: .Xr roff 7
344: scaling width.
1.55 kristaps 345: If not specified, the saved or default width is used.
1.102 kristaps 346: .Pp
347: See also
1.143 schwarze 348: .Ic RE .
349: .It Ic SB
1.22 kristaps 350: Text is rendered in small size (one point smaller than the default font)
351: bold face.
1.145 schwarze 352: This macro is an extension that probably first appeared in SunOS 4.0
353: and was later adopted by GNU and by
354: .Bx 4.4 .
1.143 schwarze 355: .It Ic SH
1.68 kristaps 356: Begin a section.
357: The scope of a section is only closed by another section or the end of
358: file.
1.78 schwarze 359: The paragraph left-margin width is reset to the default.
1.143 schwarze 360: .It Ic SM
1.22 kristaps 361: Text is rendered in small size (one point smaller than the default
362: font).
1.143 schwarze 363: .It Ic SS
1.68 kristaps 364: Begin a sub-section.
365: The scope of a sub-section is closed by a subsequent sub-section,
366: section, or end of file.
1.78 schwarze 367: The paragraph left-margin width is reset to the default.
1.143 schwarze 368: .It Ic SY
1.139 schwarze 369: Begin a synopsis block with the following syntax:
370: .Bd -unfilled -offset indent
1.143 schwarze 371: .Pf . Ic SY Ar command
1.139 schwarze 372: .Ar arguments
1.143 schwarze 373: .Pf . Ic YS
1.139 schwarze 374: .Ed
375: .Pp
376: This is a non-standard GNU extension
377: and very rarely used even in GNU manual pages.
378: Formatting is similar to
1.143 schwarze 379: .Ic IP .
380: .It Ic TH
1.140 schwarze 381: Set the name of the manual page for use in the page header
1.128 schwarze 382: and footer with the following syntax:
1.143 schwarze 383: .Pp
384: .D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume
1.43 kristaps 385: .Pp
1.99 schwarze 386: Conventionally, the document
1.140 schwarze 387: .Ar name
1.99 schwarze 388: is given in all caps.
1.141 schwarze 389: The
390: .Ar section
391: is usually a single digit, in a few cases followed by a letter.
1.99 schwarze 392: The recommended
393: .Ar date
394: format is
395: .Sy YYYY-MM-DD
396: as specified in the ISO-8601 standard;
397: if the argument does not conform, it is printed verbatim.
398: If the
399: .Ar date
400: is empty or not specified, the current date is used.
401: The optional
402: .Ar source
1.68 kristaps 403: string specifies the organisation providing the utility.
1.128 schwarze 404: When unspecified,
405: .Xr mandoc 1
406: uses its
407: .Fl Ios
408: argument.
1.68 kristaps 409: The
1.99 schwarze 410: .Ar volume
1.141 schwarze 411: string replaces the default volume title of the
412: .Ar section .
1.43 kristaps 413: .Pp
414: Examples:
1.46 kristaps 415: .Pp
1.93 kristaps 416: .Dl \&.TH CVS 5 "1992-02-12" GNU
1.143 schwarze 417: .It Ic TP
1.25 kristaps 418: Begin a paragraph where the head, if exceeding the indentation width, is
1.141 schwarze 419: followed by a newline; if not, the body follows on the same line after
420: advancing to the indentation width.
1.68 kristaps 421: Subsequent output lines are indented.
1.44 kristaps 422: The syntax is as follows:
1.141 schwarze 423: .Bd -unfilled -offset indent
1.143 schwarze 424: .Pf . Ic TP Op Ar width
1.141 schwarze 425: .Ar head No \e" one line
426: .Ar body
1.32 kristaps 427: .Ed
428: .Pp
1.44 kristaps 429: The
1.130 schwarze 430: .Ar width
1.117 schwarze 431: argument is a
432: .Xr roff 7
433: scaling width.
1.44 kristaps 434: If specified, it's saved for later paragraph left-margins; if
1.27 kristaps 435: unspecified, the saved or default width is used.
1.143 schwarze 436: .It Ic TQ
1.138 schwarze 437: Like
1.143 schwarze 438: .Ic TP ,
1.138 schwarze 439: except that no vertical spacing is inserted before the paragraph.
1.140 schwarze 440: This is a non-standard GNU extension
441: and very rarely used even in GNU manual pages.
1.143 schwarze 442: .It Ic UC
1.72 joerg 443: Sets the volume for the footer for compatibility with man pages from
1.120 schwarze 444: .Bx
445: releases.
1.72 joerg 446: The optional first argument specifies which release it is from.
1.145 schwarze 447: This macro is an extension that first appeared in
448: .Bx 3 .
1.143 schwarze 449: .It Ic UE
1.140 schwarze 450: End a uniform resource identifier block started with
1.143 schwarze 451: .Ic UR .
1.140 schwarze 452: This is a non-standard GNU extension.
1.143 schwarze 453: .It Ic UR
1.121 schwarze 454: Begin a uniform resource identifier block.
1.140 schwarze 455: This is a non-standard GNU extension.
1.121 schwarze 456: It has the following syntax:
1.143 schwarze 457: .Bd -unfilled -offset indent
458: .Pf . Ic UR Ar uri
1.121 schwarze 459: link description to be shown
1.143 schwarze 460: .Pf . Ic UE
1.121 schwarze 461: .Ed
1.143 schwarze 462: .It Ic YS
1.140 schwarze 463: End a synopsis block started with
1.143 schwarze 464: .Ic SY .
1.139 schwarze 465: This is a non-standard GNU extension.
1.143 schwarze 466: .It Ic in
1.79 kristaps 467: Indent relative to the current indentation:
468: .Pp
1.143 schwarze 469: .D1 Pf . Ic in Op Ar width
1.79 kristaps 470: .Pp
471: If
1.130 schwarze 472: .Ar width
1.79 kristaps 473: is signed, the new offset is relative.
474: Otherwise, it is absolute.
475: This value is reset upon the next paragraph, section, or sub-section.
1.143 schwarze 476: .El
1.111 schwarze 477: .Sh MACRO SYNTAX
478: The
479: .Nm
480: macros are classified by scope: line scope or block scope.
481: Line macros are only scoped to the current line (and, in some
482: situations, the subsequent line).
483: Block macros are scoped to the current line and subsequent lines until
484: closed by another block macro.
485: .Ss Line Macros
486: Line macros are generally scoped to the current line, with the body
487: consisting of zero or more arguments.
488: If a macro is scoped to the next line and the line arguments are empty,
489: the next line, which must be text, is used instead.
490: Thus:
491: .Bd -literal -offset indent
492: \&.I
493: foo
494: .Ed
495: .Pp
496: is equivalent to
1.143 schwarze 497: .Sq .I foo .
1.111 schwarze 498: If next-line macros are invoked consecutively, only the last is used.
499: If a next-line macro is followed by a non-next-line macro, an error is
1.134 schwarze 500: raised.
1.111 schwarze 501: .Pp
502: The syntax is as follows:
503: .Bd -literal -offset indent
504: \&.YO \(lBbody...\(rB
505: \(lBbody...\(rB
506: .Ed
507: .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
508: .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
1.143 schwarze 509: .It Ic AT Ta <=1 Ta current Ta \&
510: .It Ic B Ta n Ta next-line Ta \&
511: .It Ic BI Ta n Ta current Ta \&
512: .It Ic BR Ta n Ta current Ta \&
513: .It Ic DT Ta 0 Ta current Ta \&
1.144 schwarze 514: .It Ic EE Ta 0 Ta current Ta Version 9 At
515: .It Ic EX Ta 0 Ta current Ta Version 9 At
1.143 schwarze 516: .It Ic I Ta n Ta next-line Ta \&
517: .It Ic IB Ta n Ta current Ta \&
518: .It Ic IR Ta n Ta current Ta \&
519: .It Ic OP Ta >=1 Ta current Ta GNU
520: .It Ic PD Ta 1 Ta current Ta \&
521: .It Ic RB Ta n Ta current Ta \&
522: .It Ic RI Ta n Ta current Ta \&
523: .It Ic SB Ta n Ta next-line Ta \&
524: .It Ic SM Ta n Ta next-line Ta \&
525: .It Ic TH Ta >1, <6 Ta current Ta \&
526: .It Ic UC Ta <=1 Ta current Ta \&
527: .It Ic in Ta 1 Ta current Ta Xr roff 7
1.111 schwarze 528: .El
529: .Ss Block Macros
530: Block macros comprise a head and body.
531: As with in-line macros, the head is scoped to the current line and, in
532: one circumstance, the next line (the next-line stipulations as in
533: .Sx Line Macros
534: apply here as well).
535: .Pp
536: The syntax is as follows:
537: .Bd -literal -offset indent
538: \&.YO \(lBhead...\(rB
539: \(lBhead...\(rB
540: \(lBbody...\(rB
541: .Ed
542: .Pp
543: The closure of body scope may be to the section, where a macro is closed
544: by
1.143 schwarze 545: .Ic SH ;
1.111 schwarze 546: sub-section, closed by a section or
1.143 schwarze 547: .Ic SS ;
1.140 schwarze 548: or paragraph, closed by a section, sub-section,
1.143 schwarze 549: .Ic HP ,
550: .Ic IP ,
551: .Ic LP ,
552: .Ic P ,
553: .Ic PP ,
554: .Ic RE ,
555: .Ic SY ,
1.111 schwarze 556: or
1.143 schwarze 557: .Ic TP .
1.111 schwarze 558: No closure refers to an explicit block closing macro.
559: .Pp
560: As a rule, block macros may not be nested; thus, calling a block macro
561: while another block macro scope is open, and the open scope is not
562: implicitly closed, is syntactically incorrect.
563: .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
564: .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
1.143 schwarze 565: .It Ic HP Ta <2 Ta current Ta paragraph Ta \&
566: .It Ic IP Ta <3 Ta current Ta paragraph Ta \&
567: .It Ic LP Ta 0 Ta current Ta paragraph Ta \&
568: .It Ic ME Ta 0 Ta none Ta none Ta GNU
569: .It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU
570: .It Ic P Ta 0 Ta current Ta paragraph Ta \&
571: .It Ic PP Ta 0 Ta current Ta paragraph Ta \&
572: .It Ic RE Ta <=1 Ta current Ta none Ta \&
573: .It Ic RS Ta 1 Ta current Ta to \&RE Ta \&
574: .It Ic SH Ta >0 Ta next-line Ta section Ta \&
575: .It Ic SS Ta >0 Ta next-line Ta sub-section Ta \&
576: .It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU
577: .It Ic TP Ta n Ta next-line Ta paragraph Ta \&
578: .It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU
579: .It Ic UE Ta 0 Ta current Ta none Ta GNU
580: .It Ic UR Ta 1 Ta current Ta part Ta GNU
581: .It Ic YS Ta 0 Ta none Ta none Ta GNU
1.111 schwarze 582: .El
583: .Pp
584: If a block macro is next-line scoped, it may only be followed by in-line
585: macros for decorating text.
586: .Ss Font handling
587: In
588: .Nm
589: documents, both
590: .Sx Physical markup
591: macros and
592: .Xr roff 7
593: .Ql \ef
594: font escape sequences can be used to choose fonts.
595: In text lines, the effect of manual font selection by escape sequences
596: only lasts until the next macro invocation; in macro lines, it only lasts
597: until the end of the macro scope.
598: Note that macros like
1.143 schwarze 599: .Ic BR
1.111 schwarze 600: open and close a font scope for each argument.
1.1 kristaps 601: .Sh SEE ALSO
1.89 schwarze 602: .Xr man 1 ,
1.32 kristaps 603: .Xr mandoc 1 ,
1.98 kristaps 604: .Xr eqn 7 ,
1.89 schwarze 605: .Xr mandoc_char 7 ,
1.94 kristaps 606: .Xr mdoc 7 ,
607: .Xr roff 7 ,
608: .Xr tbl 7
1.78 schwarze 609: .Sh HISTORY
610: The
611: .Nm
612: language first appeared as a macro package for the roff typesetting
613: system in
614: .At v7 .
1.147 ! schwarze 615: .Pp
! 616: The stand-alone implementation that is part of the
! 617: .Xr mandoc 1
! 618: utility first appeared in
! 619: .Ox 4.6 .
! 620: .Sh AUTHORS
! 621: .An -nosplit
! 622: .An Douglas McIlroy Aq Mt m.douglas.mcilroy@dartmouth.edu
! 623: designed and implemented the original version of these macros,
! 624: wrote the original version of this manual page,
! 625: and was the first to use them when he edited volume 1 of the
! 626: .At v7
! 627: manual pages.
! 628: .Pp
1.146 schwarze 629: .An James Clark
1.147 ! schwarze 630: later rewrote the macros for groff.
1.146 schwarze 631: .An Eric S. Raymond Aq Mt esr@thyrsus.com
632: and
633: .An Werner Lemberg Aq Mt wl@gnu.org
1.147 ! schwarze 634: added the extended
1.113 kristaps 635: .Nm
1.147 ! schwarze 636: macros to groff in 2007.
! 637: .Pp
! 638: The
1.78 schwarze 639: .Xr mandoc 1
1.147 ! schwarze 640: program and this
1.32 kristaps 641: .Nm
1.147 ! schwarze 642: reference were written by
1.119 schwarze 643: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb