Annotation of mandoc/mdoc.7, Revision 1.1
1.1 ! kristaps 1: .\" $Id: mdoc.3,v 1.16 2009/03/12 23:05:21 kristaps Exp $
! 2: .\"
! 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the
! 7: .\" above copyright notice and this permission notice appear in all
! 8: .\" copies.
! 9: .\"
! 10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
! 11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
! 12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
! 13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
! 14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
! 15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
! 16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
! 17: .\" PERFORMANCE OF THIS SOFTWARE.
! 18: .\"
! 19: .Dd $Mdocdate$
! 20: .Dt mdoc 7
! 21: .Os
! 22: .\" SECTION
! 23: .Sh NAME
! 24: .Nm mdoc
! 25: .Nd mdoc macro reference
! 26: .\" SECTION
! 27: .Sh DESCRIPTION
! 28: The
! 29: .Nm mdoc
! 30: language is used to format
! 31: .Bx
! 32: .Ux
! 33: manuals. An
! 34: .Nm
! 35: document follows simple rules: lines beginning with the control
! 36: character
! 37: .Sq \.
! 38: are parsed for macros. Other lines are interpreted within the scope of
! 39: prior macros. Macros are either two or three characters in length.
! 40: .\" SECTION
! 41: .Sh CHARACTER ENCODING
! 42: .Nm
! 43: documents may contain only printable alphanumeric characters, the space
! 44: character
! 45: .Sq \ ,
! 46: and, in certain circumstances, the tab character
! 47: .Sq \et .
! 48: All manuals must have
! 49: .Sq \en
! 50: line termination.
! 51: .\" SUB-SECTION
! 52: .Ss Special Characters
! 53: Within a macro line, the following characters are special:
! 54: .\" PARAGRAPH
! 55: .Pp
! 56: .Bl -tag -width Ds -offset XXXX -compact
! 57: .It \&.
! 58: period
! 59: .It \&,
! 60: comma
! 61: .It \&:
! 62: colon
! 63: .It \&;
! 64: semicolon
! 65: .It \&(
! 66: left-parenthesis
! 67: .It \&)
! 68: right-parenthesis
! 69: .It \&[
! 70: left-bracket
! 71: .It \&]
! 72: right-bracket
! 73: .It \&?
! 74: question
! 75: .It \&!
! 76: exclmamation
! 77: .El
! 78: .Pp
! 79: Use of these characters must either be escaped with a non-breaking space
! 80: .Pq Sq \e&
! 81: or, if applicable, an appropriate escape-sequence used.
! 82: .\" SUB-SECTION
! 83: .Ss Special Characters
! 84: Special character sequences begin with the escape character
! 85: .Sq \\
! 86: and followed by either an open-parenthesis
! 87: .Sq \&(
! 88: for two-character sequences; an open-bracket
! 89: .Sq \&[
! 90: for n-character sequences (terminated at a close-bracket
! 91: .Sq \&] ) ;
! 92: or a single one-character sequence.
! 93: .Pp
! 94: Characters may alternatively be escaped by a slash-asterisk,
! 95: .Sq \\* ,
! 96: with the same combinations as described above. This form, however, is
! 97: deprecated. The following is a table of all available escapes, arranged
! 98: by classification.
! 99: .Pp
! 100: Grammatic:
! 101: .Pp
! 102: .Bl -tag -width 12n -offset "XXXX" -compact
! 103: .It \\(em
! 104: .Pq em-dash
! 105: .It \\(en
! 106: .Pq en-dash
! 107: .It \e-
! 108: .Pq hyphen
! 109: .It \\\\
! 110: .Pq back-slash
! 111: .It \e'
! 112: .Pq apostrophe
! 113: .It \e`
! 114: .Pq back-tick
! 115: .It \\
! 116: .Pq space
! 117: .It \\.
! 118: .Pq period
! 119: .El
! 120: .\" PARAGRAPH
! 121: .Pp
! 122: Enclosures:
! 123: .Pp
! 124: .Bl -tag -width 12n -offset "XXXX" -compact
! 125: .It \\(rC
! 126: .Pq right brace
! 127: .It \\(lC
! 128: .Pq left brace
! 129: .It \\(ra
! 130: .Pq right angle
! 131: .It \\(la
! 132: .Pq left angle
! 133: .It \\(rB
! 134: .Pq right bracket
! 135: .It \\(lB
! 136: .Pq left bracket
! 137: .It \\q
! 138: .Pq double-quote
! 139: .It \\(lq
! 140: .Pq left double-quote
! 141: .It \\(Lq
! 142: .Pq left double-quote, deprecated
! 143: .It \\(rq
! 144: .Pq right double-quote
! 145: .It \\(Rq
! 146: .Pq right double-quote, deprecated
! 147: .It \\(oq
! 148: .Pq left single-quote
! 149: .It \\(aq
! 150: .Pq right single-quote
! 151: .El
! 152: .\" PARAGRAPH
! 153: .Pp
! 154: Indicatives:
! 155: .Pp
! 156: .Bl -tag -width 12n -offset "XXXX" -compact
! 157: .It \\(<-
! 158: .Pq left arrow
! 159: .It \\(->
! 160: .Pq right arrow
! 161: .It \\(ua
! 162: .Pq up arrow
! 163: .It \\(da
! 164: .Pq down arrow
! 165: .El
! 166: .\" PARAGRAPH
! 167: .Pp
! 168: Mathematical:
! 169: .Pp
! 170: .Bl -tag -width 12n -offset "XXXX" -compact
! 171: .It \\(Gt
! 172: .Pq greater-than, deprecated
! 173: .It \\(Lt
! 174: .Pq less-than, deprecated
! 175: .It \\(<=
! 176: .Pq less-than-equal
! 177: .It \\(Le
! 178: .Pq less-than-equal, deprecated
! 179: .It \\(>=
! 180: .Pq greater-than-equal
! 181: .It \\(Ge
! 182: .Pq greater-than-equal
! 183: .It \\(==
! 184: .Pq equal
! 185: .It \\(!=
! 186: .Pq not equal
! 187: .It \\(Ne
! 188: .Pq not equal, deprecated
! 189: .It \\(if
! 190: .Pq infinity
! 191: .It \\(If
! 192: .Pq infinity, deprecated
! 193: .It \\(na
! 194: .Pq NaN , an extension
! 195: .It \\(Na
! 196: .Pq NaN, deprecated
! 197: .It \\(+-
! 198: .Pq plus-minus
! 199: .It \\(Pm
! 200: .Pq plus-minus, deprecated
! 201: .It \\(**
! 202: .Pq asterisk
! 203: .El
! 204: .\" PARAGRAPH
! 205: .Pp
! 206: Diacritics:
! 207: .Pp
! 208: .Bl -tag -width 12n -offset "XXXX" -compact
! 209: .It \\(ga
! 210: .Pq accent grave
! 211: .It \\(aa
! 212: .Pq accent accute
! 213: .El
! 214: .\" PARAGRAPH
! 215: .Pp
! 216: Special symbols:
! 217: .Pp
! 218: .Bl -tag -width 12n -offset "XXXX" -compact
! 219: .It \\(bu
! 220: .Pq bullet
! 221: .It \\(ba
! 222: .Pq bar
! 223: .It \\(Ba
! 224: .Pq bar, deprecated
! 225: .It \\(co
! 226: .Pq copyright
! 227: .It \\&
! 228: .Pq non-breaking space
! 229: .It \\e
! 230: .Pq escape
! 231: .It \\(Am
! 232: .Pq ampersand, deprecated
! 233: .El
! 234: .\" SECTION
! 235: .Sh CLASSIFICATION
! 236: Macros are classified in an ontology described by scope rules.
! 237: .Bl -tag -width "in-lineX"
! 238: .\" LIST-ITEM
! 239: .It Em Block
! 240: Block macros enclose other block macros, in-line macros or text, and
! 241: may span multiple lines.
! 242: .Qq Implicit
! 243: block scope is closed by a subsequent invocation of the same macro,
! 244: one of a set of corresponding closure macros or end-of-file.
! 245: .Qq Explicit
! 246: block scope is closed by a corresponding closure macro.
! 247: .Bl -tag -width "partial-blockX"
! 248: .\" LIST-ITEM
! 249: .It Em Full-block
! 250: Always spans multiple lines. Consists optionally of one or more
! 251: .Qq heads ,
! 252: subsequent macros or text on the same line following invocation; a
! 253: .Qq body ,
! 254: which spans subsequent lines of text or macros; and an optional
! 255: .Qq tail ,
! 256: macros or text on the same line following closure.
! 257: .\" LIST-ITEM
! 258: .It Em Partial-block
! 259: May span multiple lines. Consists optionally of a
! 260: .Qq head ,
! 261: text immediately following invocation; always a
! 262: .Qq body ,
! 263: text or macros following the head on the same and subsequent lines; and
! 264: optionally a
! 265: .Qq tail ,
! 266: text immediately following closure.
! 267: .El
! 268: .\" LIST-ITEM
! 269: .It Em In-line
! 270: In-line macros may only enclose text and span at most a single line. If
! 271: a macro is parsable, its scope may be closed by subsequent macros or
! 272: delimiting punctuation. In-line macros follow different conventions for
! 273: closure; see
! 274: .Sx MACROS
! 275: for per-macro details.
! 276: .El
! 277: .\" .\" SUB-SECTION
! 278: .\" .Ss Examples
! 279: .\" The following examples illustrate each macro classification.
! 280: .\" .\" PARAGRAPH
! 281: .\" .Pp
! 282: .\" Implicit full-block. Has head, body and no tail. Scope closed by
! 283: .\" second
! 284: .\" .Sq \&Sh
! 285: .\" invocation.
! 286: .\" .Bd -literal -offset XXXX
! 287: .\" \&.Sh SECTION 1
! 288: .\" body...
! 289: .\" \&.Sh SECTION 2
! 290: .\" .Ed
! 291: .\" .\" PARAGRAPH
! 292: .\" .Pp
! 293: .\" Nested implicit full-block, where the subsection
! 294: .\" .Sq \&Ss
! 295: .\" is within the scope of the parent section
! 296: .\" .Sq \&Sh
! 297: .\" and closed along with its parent by the subsequent
! 298: .\" .Sq \&Sh .
! 299: .\" .Bd -literal -offset XXXX
! 300: .\" \&.Sh SECTION 1
! 301: .\" \&.Ss Subsection 1
! 302: .\" body...
! 303: .\" \&.Sh SECTION 2
! 304: .\" .Ed
! 305: .\" .\" PARAGRAPH
! 306: .\" .Pp
! 307: .\" Explicit full-block. Has a head, a body and no tail. Scope closed by
! 308: .\" .Sq \&Ef
! 309: .\" invocation.
! 310: .\" .Bd -literal -offset XXXX
! 311: .\" \&.Bf symbolic
! 312: .\" body...
! 313: .\" \&.Ef
! 314: .\" .Ed
! 315: .\" .\" PARAGRAPH
! 316: .\" .Pp
! 317: .\" Nested explicit/implicit scope.
! 318: .\" .Sq \&It
! 319: .\" macro is an implicit block whose scope is closed by the explicit
! 320: .\" .Sq \&El
! 321: .\" closure.
! 322: .\" .Bd -literal -offset XXXX
! 323: .\" \&.Bl \-bullet
! 324: .\" \&.It head
! 325: .\" body...
! 326: .\" \&.El
! 327: .\" .Ed
! 328: .\" .\" PARAGRAPH
! 329: .\" .Pp
! 330: .\" Explicit partial-block. Has head, body and tail. Scope closed by
! 331: .\" .Sq \&Ec
! 332: .\" invocation.
! 333: .\" .Bd -literal -offset XXX
! 334: .\" \&.Eo head body... \&Ec tail
! 335: .\" .Ed
! 336: .\" .\" PARAGRAPH
! 337: .\" .Pp
! 338: .\" Implicit partial-block. Has only body. Scope is closed by end-of-line.
! 339: .\" .Bd -literal -offset XXX
! 340: .\" \&.Sq body...
! 341: .\" .Ed
! 342: .\" .\" PARAGRAPH
! 343: .\" .Pp
! 344: .\" Explicit partial-block with only body and scope closed by
! 345: .\" .Sq \&Ac
! 346: .\" invocation.
! 347: .\" .Bd -literal -offset XXXX
! 348: .\" \&.Ao body... \&Ac
! 349: .\" .Ed
! 350: .\" .\" PARAGRAPH
! 351: .\" .Pp
! 352: .\" Implicit partial-block enclosing explicit partial-block.
! 353: .\" .Bd -literal -offset XXX
! 354: .\" \&.Sq body... \&Ao body... \&Ac
! 355: .\" .Ed
! 356: .\" .\" PARAGRAPH
! 357: .\" .Pp
! 358: .\" Inline macros, several in sequence. Scope is closed for
! 359: .\" .Sq \&Fl
! 360: .\" by the punctuation delimiter and
! 361: .\" .Sq \&Ar
! 362: .\" by the end-of-line.
! 363: .\" .Bd -literal -offset XXXX
! 364: .\" \&.Fl text0 text1 ; Ar text0 text1
! 365: .\" .Ed
! 366: .\" SECTION
! 367: .Sh MACROS
! 368: This section contains a complete list of all
! 369: .Nm
! 370: macros, arranged ontologically then alphanumerically by macro name. A
! 371: .Qq callable
! 372: macro is may be invoked subsequent to the initial macro-line macro. A
! 373: .Qq parsable
! 374: macro May be followed by further (ostensibly callable) macros.
! 375: .\" SUB-SECTION
! 376: .Ss Block full-implicit
! 377: The head of these macros follows invocation; the body is the content of
! 378: subsequent lines prior to closure. None of these macros have tails;
! 379: some
! 380: .Po
! 381: .Sq \&It \-bullet ,
! 382: .Sq \-hyphen ,
! 383: .Sq \-dash ,
! 384: .Sq \-enum
! 385: .Pc
! 386: don't have heads.
! 387: .Pp
! 388: .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
! 389: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
! 390: .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
! 391: .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
! 392: .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
! 393: .El
! 394: .\" SUB-SECTION
! 395: .Ss Block full-explicit
! 396: None of these macros are callable or parsed. The last column indicates
! 397: the explicit scope rules. All contains bodies, some may contain heads
! 398: .Pq So \&Bf Sc .
! 399: .Pp
! 400: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
! 401: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
! 402: .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
! 403: .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
! 404: .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
! 405: .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
! 406: .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
! 407: .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
! 408: .El
! 409: .\" SUB-SECTION
! 410: .Ss Block partial-implicit
! 411: All of these are callable and parsed for further macros. Their scopes
! 412: close at the invocation's end-of-line.
! 413: .Pp
! 414: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
! 415: .It Em Macro Ta Em Callable Ta Em Parsable
! 416: .It \&.Aq Ta Yes Ta Yes
! 417: .It \&.Op Ta Yes Ta Yes
! 418: .It \&.Bq Ta Yes Ta Yes
! 419: .It \&.Dq Ta Yes Ta Yes
! 420: .It \&.Pq Ta Yes Ta Yes
! 421: .It \&.Qq Ta Yes Ta Yes
! 422: .It \&.Sq Ta Yes Ta Yes
! 423: .It \&.Brq Ta Yes Ta Yes
! 424: .El
! 425: .\" SUB-SECTION
! 426: .Ss Block partial-explicit
! 427: Each of these contains at least a body and, in limited circumstances, a
! 428: head
! 429: .Pq So \&Fo Sc , So \&Eo Sc
! 430: and/or tail
! 431: .Pq So \&Ec Sc .
! 432: .Pp
! 433: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
! 434: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
! 435: .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
! 436: .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
! 437: .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
! 438: .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
! 439: .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
! 440: .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
! 441: .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
! 442: .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
! 443: .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
! 444: .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
! 445: .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
! 446: .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
! 447: .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
! 448: .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
! 449: .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
! 450: .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
! 451: .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
! 452: .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
! 453: .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
! 454: .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
! 455: .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
! 456: .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
! 457: .El
! 458: .\" SUB-SECTION
! 459: .Ss General
! 460: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
! 461: .It Em Macro Ta Em Callable Ta Em Parsable
! 462: .It \&.Dd Ta \& Ta \&
! 463: .It \&.Dt Ta \& Ta \&
! 464: .It \&.Os Ta \& Ta \&
! 465: .It \&.Pp Ta \& Ta \&
! 466: .It \&.D1 Ta \& Ta \&
! 467: .It \&.Dl Ta \& Ta Yes
! 468: .It \&.Ad Ta Yes Ta Yes
! 469: .It \&.An Ta \& Ta Yes
! 470: .It \&.Ar Ta Yes Ta Yes
! 471: .It \&.Cd Ta Yes Ta \&
! 472: .It \&.Cm Ta Yes Ta Yes
! 473: .It \&.Dv Ta Yes Ta Yes
! 474: .It \&.Er Ta Yes Ta Yes
! 475: .It \&.Ev Ta Yes Ta Yes
! 476: .It \&.Ex Ta \& Ta \&
! 477: .It \&.Fa Ta Yes Ta Yes
! 478: .It \&.Fd Ta \& Ta \&
! 479: .It \&.Fl Ta Yes Ta Yes
! 480: .It \&.Fn Ta Yes Ta Yes
! 481: .It \&.Ft Ta \& Ta \&
! 482: .It \&.Ic Ta Yes Ta Yes
! 483: .It \&.In Ta \& Ta \&
! 484: .It \&.Li Ta Yes Ta Yes
! 485: .It \&.Nd Ta \& Ta \&
! 486: .It \&.Nm Ta Yes Ta Yes
! 487: .It \&.Ot Ta \& Ta \&
! 488: .It \&.Pa Ta Yes Ta Yes
! 489: .It \&.Rv Ta \& Ta \&
! 490: .It \&.St Ta Yes Ta \&
! 491: .It \&.Va Ta Yes Ta Yes
! 492: .It \&.Vt Ta Yes Ta Yes
! 493: .It \&.Xr Ta Yes Ta Yes
! 494: .It \&.%A Ta \& Ta \&
! 495: .It \&.%B Ta \& Ta \&
! 496: .It \&.%C Ta \& Ta \&
! 497: .It \&.%D Ta \& Ta \&
! 498: .It \&.%I Ta \& Ta \&
! 499: .It \&.%J Ta \& Ta \&
! 500: .It \&.%N Ta \& Ta \&
! 501: .It \&.%O Ta \& Ta \&
! 502: .It \&.%P Ta \& Ta \&
! 503: .It \&.%R Ta \& Ta \&
! 504: .It \&.%T Ta \& Ta \&
! 505: .It \&.%V Ta \& Ta \&
! 506: .It \&.At Ta Yes Ta Yes
! 507: .It \&.Bsx Ta Yes Ta Yes
! 508: .It \&.Bx Ta Yes Ta Yes
! 509: .It \&.Db Ta \& Ta \&
! 510: .It \&.Em Ta Yes Ta Yes
! 511: .It \&.Fx Ta Yes Ta Yes
! 512: .It \&.Ms Ta \& Ta Yes
! 513: .It \&.No Ta Yes Ta Yes
! 514: .It \&.Ns Ta Yes Ta Yes
! 515: .It \&.Nx Ta Yes Ta Yes
! 516: .It \&.Ox Ta Yes Ta Yes
! 517: .It \&.Pf Ta \& Ta Yes
! 518: .It \&.Ql Ta Yes Ta Yes
! 519: .It \&.Re Ta \& Ta \&
! 520: .It \&.Rs Ta \& Ta \&
! 521: .It \&.Sm Ta \& Ta \&
! 522: .It \&.Sx Ta Yes Ta Yes
! 523: .It \&.Sy Ta Yes Ta Yes
! 524: .It \&.Tn Ta Yes Ta Yes
! 525: .It \&.Ux Ta Yes Ta Yes
! 526: .It \&.Bk Ta \& Ta \&
! 527: .It \&.Ek Ta \& Ta \&
! 528: .It \&.Bt Ta \& Ta \&
! 529: .It \&.Hf Ta \& Ta \&
! 530: .It \&.Fr Ta \& Ta \&
! 531: .It \&.Ud Ta \& Ta \&
! 532: .It \&.Lb Ta \& Ta \&
! 533: .It \&.Ap Ta Yes Ta Yes
! 534: .It \&.Lp Ta \& Ta \&
! 535: .It \&.Lk Ta \& Ta Yes
! 536: .It \&.Mt Ta \& Ta Yes
! 537: .El
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mdoc.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc