Annotation of src/usr.bin/mandoc/mdoc.7, Revision 1.1
1.1 ! kristaps 1: .\" $Id: mdoc.7,v 1.19 2009/03/27 14:56:15 kristaps Exp $
! 2: .\"
! 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
! 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 language reference
! 26: .\" SECTION
! 27: .Sh DESCRIPTION
! 28: The
! 29: .Nm mdoc
! 30: language is used to format
! 31: .Bx
! 32: .Ux
! 33: manuals. In this reference document, we describe the syntax, ontology
! 34: and structure of the
! 35: .Nm
! 36: language.
! 37: .\" PARAGRAPH
! 38: .Pp
! 39: An
! 40: .Nm
! 41: document follows simple rules: lines beginning with the control
! 42: character
! 43: .Sq \.
! 44: are parsed for macros. Other lines are interpreted within the scope of
! 45: prior macros:
! 46: .Bd -literal -offset XXX
! 47: \&.Sh Macro lines change control state.
! 48: Other lines are interpreted within the current state.
! 49: .Ed
! 50: .\" SECTION
! 51: .Sh INPUT ENCODING
! 52: .Nm
! 53: documents may contain only graphable 7-bit ASCII characters, the space
! 54: character
! 55: .Sq \ ,
! 56: and, in certain circumstances, the tab character
! 57: .Sq \et .
! 58: All manuals must have
! 59: .Sq \en
! 60: line termination.
! 61: .Pp
! 62: The only time a blank line is acceptable is within
! 63: the context of
! 64: .Sq \&.Bd \-literal
! 65: or
! 66: .Sq \&.Bd \-unfilled .
! 67: .Pp
! 68: Tab characters
! 69: .Pq \et
! 70: are only acceptable when delimiting
! 71: .Sq \&.Bl \-column
! 72: and in
! 73: .Sq \&.Bd \-literal
! 74: or
! 75: .Sq \&.Bd \-unfilled
! 76: contexts.
! 77: .\" SUB-SECTION
! 78: .Ss Reserved Characters
! 79: Within a macro line, the following characters are reserved:
! 80: .Bl -tag -width 12n -offset XXXX -compact
! 81: .It \&.
! 82: .Pq period
! 83: .It \&,
! 84: .Pq comma
! 85: .It \&:
! 86: .Pq colon
! 87: .It \&;
! 88: .Pq semicolon
! 89: .It \&(
! 90: .Pq left-parenthesis
! 91: .It \&)
! 92: .Pq right-parenthesis
! 93: .It \&[
! 94: .Pq left-bracket
! 95: .It \&]
! 96: .Pq right-bracket
! 97: .It \&?
! 98: .Pq question
! 99: .It \&!
! 100: .Pq exclamation
! 101: .El
! 102: .\" PARAGRAPH
! 103: .Pp
! 104: Use of reserved characters is described in
! 105: .Sx Closure .
! 106: For general non-reserved use, characters must either be escaped with a
! 107: non-breaking space
! 108: .Pq Sq \e&
! 109: or, if applicable, an appropriate escape-sequence used.
! 110: .\" SUB-SECTION
! 111: .Ss Special Characters
! 112: Special character sequences begin with the escape character
! 113: .Sq \e
! 114: followed by either an open-parenthesis
! 115: .Sq \&(
! 116: for two-character sequences; an open-bracket
! 117: .Sq \&[
! 118: for n-character sequences (terminated at a close-bracket
! 119: .Sq \&] ) ;
! 120: or a single one-character sequence.
! 121: .Pp
! 122: Characters may alternatively be escaped by a slash-asterisk,
! 123: .Sq \e* ,
! 124: with the same combinations as described above. This form is deprecated.
! 125: .\" SECTION
! 126: .Sh STRUCTURE
! 127: Macros are classified in an ontology described by their scope rules.
! 128: Some macros are allowed to deviate from their classifications to
! 129: preserve backward-compatibility with old macro combinations still found
! 130: in the manual corpus. These are specifically noted on a per-macro
! 131: basis.
! 132: .\" SUB-SECTION
! 133: .Ss Scope
! 134: .Bl -inset
! 135: .\" LIST-ITEM
! 136: .It Em Block
! 137: macros enclose other block macros, in-line macros or text, and
! 138: may span multiple lines.
! 139: .Bl -inset -offset XXXX
! 140: .\" LIST-ITEM
! 141: .It Em Full-block
! 142: macros always span multiple lines. They consist of zero or
! 143: more
! 144: .Qq heads ,
! 145: subsequent macros or text on the same line following invocation; an
! 146: optional
! 147: .Qq body ,
! 148: which spans subsequent lines of text or macros; and an optional
! 149: .Qq tail ,
! 150: macros or text on the same line following closure.
! 151: .\" LIST-ITEM
! 152: .It Em Partial-block
! 153: macros may span multiple lines. They consists of a optional
! 154: .Qq head ,
! 155: text immediately following invocation; always a
! 156: .Qq body ,
! 157: text or macros following the head on the same and subsequent lines; and
! 158: optionally a
! 159: .Qq tail ,
! 160: text immediately following closure.
! 161: .\" LIST-ITEM
! 162: .It Em In-line
! 163: macros may only enclose text and span at most a single line.
! 164: .El
! 165: .El
! 166: .\" SUB-SECTION
! 167: .Ss Closure
! 168: Closure of a macro's scope depends first on its classification, then
! 169: on whether it's parsable. In this table,
! 170: .Sq BFE
! 171: refers to block full-explicit and so on.
! 172: .\" PARAGRAPH
! 173: .Pp
! 174: .Bl -tag -width 12n -offset XXXX -compact
! 175: .It BPE , BFE
! 176: corresponding explicit closure macro
! 177: .It BFI
! 178: end-of-file or a corresponding implicit closure macro
! 179: .It BPI
! 180: end-of-line (body may be closed by >0 space-separated
! 181: .Sx Reserved Characters ,
! 182: although block scope will still be open)
! 183: .It INL
! 184: end-of-line
! 185: .El
! 186: .\" PARAGRAPH
! 187: .Pp
! 188: If a macro (block or in-line) is parsable, it may also be closed out by
! 189: one of the following scenarios (unless specifically noted otherwise):
! 190: .\" PARAGRAPH
! 191: .Pp
! 192: .Bl -dash -offset XXXX -compact
! 193: .It
! 194: a sequence of >0 space-separated
! 195: .Sx Reserved Characters ,
! 196: .It
! 197: another macro,
! 198: .It
! 199: end-of-line, or
! 200: .It
! 201: completion of a set number of arguments.
! 202: .El
! 203: .\" PARAGRAPH
! 204: .Pp
! 205: If >0 space-separated
! 206: .Sx Reserved Characters
! 207: are followed by non-reserved characters, the behaviour differs per
! 208: macro. In general, scope of the macro is closed and re-opened:
! 209: subsequent tokens are interpreted as if the scope had just been opened.
! 210: In other circumstances, scope is simply closed out.
! 211: .\" SECTION
! 212: .Sh SYNTAX
! 213: Macros are two or three characters in length. The syntax of macro
! 214: invocation depends on its classification.
! 215: .Qq \-arg
! 216: refers to the macro arguments (which may contain zero or more values).
! 217: In these illustrations,
! 218: .Sq \&.Yo
! 219: opens the scope of a macro, and if specified,
! 220: .Sq \&.Yc
! 221: closes it out (closure may be implicit at end-of-line or end-of-file).
! 222: .\" PARAGRAPH
! 223: .Pp
! 224: Block full-explicit (may contain head, body, tail).
! 225: .Bd -literal -offset XXXX
! 226: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
! 227: \(lBbody...\(rB
! 228: \&.Yc \(lBtail...\(rB
! 229: .Ed
! 230: .\" PARAGRAPH
! 231: .Pp
! 232: Block full-implicit (may contain zero or more heads, body, no tail).
! 233: .Bd -literal -offset XXXX
! 234: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
! 235: \(lBbody...\(rB
! 236: \&.Yc
! 237: .Ed
! 238: .\" PARAGRAPH
! 239: .Pp
! 240: Block partial-explicit (may contain head, multi-line body, tail).
! 241: .Bd -literal -offset XXXX
! 242: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
! 243: \(lBbody...\(rB
! 244: \&.Yc \(lBtail...\(rB
! 245:
! 246: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
! 247: \(lBbody...\(rB \&Yc \(lBtail...\(rB
! 248: .Ed
! 249: .\" PARAGRAPH
! 250: .Pp
! 251: Block partial-implicit (no head, body, no tail). Note that the body
! 252: section may be followed by zero or more
! 253: .Sx Reserved Words .
! 254: These are in the block scope, but not in the body scope.
! 255: .Bd -literal -offset XXXX
! 256: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
! 257: .Ed
! 258: .\" PARAGRAPH
! 259: .Pp
! 260: In-lines have \(>=0 scoped arguments.
! 261: .Bd -literal -offset XXX
! 262: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
! 263:
! 264: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
! 265: .Ed
! 266: .\"
! 267: .Sh MACROS
! 268: This section contains a complete list of all
! 269: .Nm
! 270: macros, arranged ontologically. A
! 271: .Qq callable
! 272: macro is invoked subsequent to the initial macro-line macro. A
! 273: .Qq parsable
! 274: macro may be followed by further (ostensibly callable) macros.
! 275: .\" SUB-SECTION
! 276: .Ss Block full-implicit
! 277: The head of these macros follows invocation; the body is the content of
! 278: subsequent lines prior to closure. None of these macros have tails;
! 279: some
! 280: .Po
! 281: .Sq \&.It \-bullet ,
! 282: .Sq \-hyphen ,
! 283: .Sq \-dash ,
! 284: .Sq \-enum ,
! 285: .Sq \-item
! 286: .Pc
! 287: don't have heads.
! 288: .Pp
! 289: .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
! 290: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
! 291: .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
! 292: .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
! 293: .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
! 294: .El
! 295: .\" SUB-SECTION
! 296: .Ss Block full-explicit
! 297: None of these macros are callable or parsed. The last column indicates
! 298: the explicit scope rules. All contains bodies, some may contain heads
! 299: .Pq So \&Bf Sc .
! 300: .Pp
! 301: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
! 302: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
! 303: .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
! 304: .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
! 305: .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
! 306: .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
! 307: .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
! 308: .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
! 309: .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
! 310: .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
! 311: .El
! 312: .\" SUB-SECTION
! 313: .Ss Block partial-implicit
! 314: All of these are callable and parsed for further macros. Their scopes
! 315: close at the invocation's end-of-line.
! 316: .Pp
! 317: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
! 318: .It Em Macro Ta Em Callable Ta Em Parsable
! 319: .It \&.Aq Ta Yes Ta Yes
! 320: .It \&.Op Ta Yes Ta Yes
! 321: .It \&.Bq Ta Yes Ta Yes
! 322: .It \&.Dq Ta Yes Ta Yes
! 323: .It \&.Pq Ta Yes Ta Yes
! 324: .It \&.Qq Ta Yes Ta Yes
! 325: .It \&.Sq Ta Yes Ta Yes
! 326: .It \&.Brq Ta Yes Ta Yes
! 327: .It \&.D1 Ta \&No Ta \&Yes
! 328: .It \&.Dl Ta \&No Ta Yes
! 329: .It \&.Ql Ta Yes Ta Yes
! 330: .El
! 331: .\" PARAGRAPH
! 332: .Pp
! 333: The
! 334: .Sq \&.Op
! 335: may be broken by
! 336: .Sq \&.Oc
! 337: as in the following example:
! 338: .Bd -literal -offset XXXX
! 339: \&.Oo
! 340: \&.Op Fl a Oc
! 341: .Ed
! 342: .Pp
! 343: In the above example, the scope of
! 344: .Sq \&.Op
! 345: is technically broken by
! 346: .Sq \&.Oc ,
! 347: however, due to the overwhelming existence of this sequence, it's
! 348: allowed.
! 349: .\" SUB-SECTION
! 350: .Ss Block partial-explicit
! 351: Each of these contains at least a body and, in limited circumstances, a
! 352: head
! 353: .Pq So \&.Fo Sc , So \&.Eo Sc
! 354: and/or tail
! 355: .Pq So \&.Ec Sc .
! 356: .Pp
! 357: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
! 358: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
! 359: .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
! 360: .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
! 361: .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
! 362: .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
! 363: .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
! 364: .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
! 365: .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
! 366: .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
! 367: .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
! 368: .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
! 369: .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
! 370: .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
! 371: .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
! 372: .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
! 373: .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
! 374: .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
! 375: .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
! 376: .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
! 377: .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
! 378: .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
! 379: .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
! 380: .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
! 381: .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
! 382: .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
! 383: .El
! 384: .\" SUB-SECTION
! 385: .Ss In-line
! 386: In-line macros have only text children. If a number (or inequality) of
! 387: arguments is
! 388: .Pq n ,
! 389: then the macro accepts an arbitrary number of arguments.
! 390: .Pp
! 391: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
! 392: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
! 393: .It \&.Dd Ta \&No Ta \&No Ta >0
! 394: .It \&.Dt Ta \&No Ta \&No Ta n
! 395: .It \&.Os Ta \&No Ta \&No Ta n
! 396: .It \&.Pp Ta \&No Ta \&No Ta 0
! 397: .It \&.Ad Ta Yes Ta Yes Ta n
! 398: .It \&.An Ta \&No Ta Yes Ta n
! 399: .It \&.Ar Ta Yes Ta Yes Ta n
! 400: .It \&.Cd Ta Yes Ta \&No Ta >0
! 401: .It \&.Cm Ta Yes Ta Yes Ta n
! 402: .It \&.Dv Ta Yes Ta Yes Ta n
! 403: .It \&.Er Ta Yes Ta Yes Ta >0
! 404: .It \&.Ev Ta Yes Ta Yes Ta n
! 405: .It \&.Ex Ta \&No Ta \&No Ta 0
! 406: .It \&.Fa Ta Yes Ta Yes Ta n
! 407: .It \&.Fd Ta \&No Ta \&No Ta >0
! 408: .It \&.Fl Ta Yes Ta Yes Ta n
! 409: .It \&.Fn Ta Yes Ta Yes Ta >0
! 410: .It \&.Ft Ta \&No Ta Yes Ta n
! 411: .It \&.Ic Ta Yes Ta Yes Ta >0
! 412: .It \&.In Ta \&No Ta \&No Ta n
! 413: .It \&.Li Ta Yes Ta Yes Ta n
! 414: .It \&.Nd Ta \&No Ta \&No Ta n
! 415: .It \&.Nm Ta Yes Ta Yes Ta n
! 416: .It \&.Ot Ta \&No Ta \&No Ta n
! 417: .It \&.Pa Ta Yes Ta Yes Ta n
! 418: .It \&.Rv Ta \&No Ta \&No Ta 0
! 419: .It \&.St Ta \&No Ta Yes Ta 1
! 420: .It \&.Va Ta Yes Ta Yes Ta n
! 421: .It \&.Vt Ta Yes Ta Yes Ta >0
! 422: .It \&.Xr Ta Yes Ta Yes Ta >0, <3
! 423: .It \&.%A Ta \&No Ta \&No Ta >0
! 424: .It \&.%B Ta \&No Ta \&No Ta >0
! 425: .It \&.%C Ta \&No Ta \&No Ta >0
! 426: .It \&.%D Ta \&No Ta \&No Ta >0
! 427: .It \&.%I Ta \&No Ta \&No Ta >0
! 428: .It \&.%J Ta \&No Ta \&No Ta >0
! 429: .It \&.%N Ta \&No Ta \&No Ta >0
! 430: .It \&.%O Ta \&No Ta \&No Ta >0
! 431: .It \&.%P Ta \&No Ta \&No Ta >0
! 432: .It \&.%R Ta \&No Ta \&No Ta >0
! 433: .It \&.%T Ta \&No Ta \&No Ta >0
! 434: .It \&.%V Ta \&No Ta \&No Ta >0
! 435: .It \&.At Ta Yes Ta Yes Ta 1
! 436: .It \&.Bsx Ta Yes Ta Yes Ta n
! 437: .It \&.Bx Ta Yes Ta Yes Ta n
! 438: .It \&.Db Ta \&No Ta \&No Ta 1
! 439: .It \&.Em Ta Yes Ta Yes Ta >0
! 440: .It \&.Fx Ta Yes Ta Yes Ta n
! 441: .It \&.Ms Ta \&No Ta Yes Ta >0
! 442: .It \&.No Ta Yes Ta Yes Ta 0
! 443: .It \&.Ns Ta Yes Ta Yes Ta 0
! 444: .It \&.Nx Ta Yes Ta Yes Ta n
! 445: .It \&.Ox Ta Yes Ta Yes Ta n
! 446: .It \&.Pf Ta \&No Ta Yes Ta 1
! 447: .It \&.Sm Ta \&No Ta \&No Ta 1
! 448: .It \&.Sx Ta Yes Ta Yes Ta >0
! 449: .It \&.Sy Ta Yes Ta Yes Ta >0
! 450: .It \&.Tn Ta Yes Ta Yes Ta >0
! 451: .It \&.Ux Ta Yes Ta Yes Ta n
! 452: .It \&.Dx Ta Yes Ta Yes Ta n
! 453: .It \&.Bt Ta \&No Ta \&No Ta 0
! 454: .It \&.Hf Ta \&No Ta \&No Ta n
! 455: .It \&.Fr Ta \&No Ta \&No Ta n
! 456: .It \&.Ud Ta \&No Ta \&No Ta 0
! 457: .It \&.Lb Ta \&No Ta \&No Ta 1
! 458: .It \&.Ap Ta Yes Ta Yes Ta 0
! 459: .It \&.Lp Ta \&No Ta \&No Ta 0
! 460: .It \&.Lk Ta \&No Ta Yes Ta >0
! 461: .It \&.Mt Ta \&No Ta Yes Ta >0
! 462: .It \&.Es Ta \&No Ta \&No Ta 0
! 463: .It \&.En Ta \&No Ta \&No Ta 0
! 464: .El
! 465: .Pp
! 466: The
! 467: .Sq \&.Ot ,
! 468: .Sq \&.Fr ,
! 469: .Sq \&.Es
! 470: and
! 471: .Sq \&.En ,
! 472: macros are obsolete.
! 473: .\" SECTION
! 474: .Sh COMPATIBILITY
! 475: The mdoc language was traditionally a
! 476: .Qq roff
! 477: macro package; most existing manuals were written with mdoc syntax
! 478: dictated by system-dependent roff installations. This section documents
! 479: compatibility with these systems.
! 480: .Pp
! 481: .Bl -dash -compact
! 482: .\" LIST-ITEM
! 483: .It
! 484: .Sq \&.Fo
! 485: and
! 486: .Sq \&.St
! 487: historically weren't always callable. Both are now correctly callable.
! 488: .\" LIST-ITEM
! 489: .It
! 490: .Sq \&.It \-nested
! 491: is assumed for all lists: any list may be nested and
! 492: .Sq \-enum
! 493: lists will restart the sequence only for the sub-list.
! 494: .\" LIST-ITEM
! 495: .It
! 496: .Sq \&.It \-column
! 497: syntax where column widths may be preceeded by other arguments (instead
! 498: of proceeded) is not supported.
! 499: .\" LIST-ITEM
! 500: .It
! 501: The
! 502: .Sq \&.At
! 503: macro only accepts a single parameter.
! 504: .\" LIST-ITEM
! 505: .It
! 506: The system-name macros (
! 507: .Ns Sq \&.At ,
! 508: .Sq \&.Bsx ,
! 509: .Sq \&.Bx ,
! 510: .Sq \&.Fx ,
! 511: .Sq \&.Nx ,
! 512: .Sq \&.Ox ,
! 513: and
! 514: .Sq \&.Ux )
! 515: are callable.
! 516: .\" LIST-ITEM
! 517: .It
! 518: Some manuals use
! 519: .Sq \&.Li
! 520: incorrectly by following it with a reserved character and expecting the
! 521: delimiter to render. This is not supported.
! 522: .\" LIST-ITEM
! 523: .It
! 524: .Sq \&.Cd
! 525: is callable.
! 526: .El
! 527: .\" SECTION
! 528: .Sh SEE ALSO
! 529: .Xr mandoc 1 ,
! 530: .Xr mandoc_char 7
! 531: .\" SECTION
! 532: .Sh AUTHORS
! 533: The
! 534: .Nm
! 535: utility was written by
! 536: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
! 537: .\" SECTION
! 538: .Sh CAVEATS
! 539: There are several ambiguous parts of mdoc.
! 540: .Pp
! 541: .Bl -dash -compact
! 542: .\" LIST-ITEM
! 543: .It
! 544: .Sq \&.Fa
! 545: should be
! 546: .Sq \&.Va
! 547: as function arguments are variables.
! 548: .\" LIST-ITEM
! 549: .It
! 550: .Sq \&.Ft
! 551: should be
! 552: .Sq \&.Vt
! 553: as function return types are still types. Furthermore, the
! 554: .Sq \&.Ft
! 555: should be removed and
! 556: .Sq \&.Fo ,
! 557: which ostensibly follows it, should follow the same convention as
! 558: .Sq \&.Va .
! 559: .\" LIST-ITEM
! 560: .It
! 561: .Sq \&.Va
! 562: should formalise that only one or two arguments are acceptable: a
! 563: variable name and optional, preceeding type.
! 564: .\" LIST-ITEM
! 565: .It
! 566: .Sq \&.Fd
! 567: is ambiguous. It's commonly used to indicate an include file in the
! 568: synopsis section.
! 569: .Sq \&.In
! 570: should be used, instead.
! 571: .\" LIST-ITEM
! 572: .It
! 573: Only the
! 574: .Sq \-literal
! 575: argument to
! 576: .Sq \&.Bd
! 577: makes sense. The remaining ones should be removed.
! 578: .\" LIST-ITEM
! 579: .It
! 580: The
! 581: .Sq \&.Xo
! 582: and
! 583: .Sq \&.Xc
! 584: macros should be deprecated.
! 585: .\" LIST-ITEM
! 586: .It
! 587: The
! 588: .Sq \&.Dt
! 589: macro lacks clarity. It should be absolutely clear which title will
! 590: render when formatting the manual page.
! 591: .\" LIST-ITEM
! 592: .It
! 593: A
! 594: .Sq \&.Lx
! 595: should be provided for Linux (\(`a la
! 596: .Sq \&.Ox ,
! 597: .Sq \&.Nx
! 598: etc.).
! 599: .\" LIST-ITEM
! 600: .It
! 601: There's no way to refer to references in
! 602: .Sq \&.Rs/.Re
! 603: blocks.
! 604: .El
![[BACK]](/icons/back.gif){kind=icon}
Return to mdoc.7 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc