[BACK]Return to mdoc.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mdoc.7, Revision 1.19

1.19    ! kristaps    1: .\" $Id: mdoc.7,v 1.18 2009/03/27 13:44:24 kristaps Exp $
1.1       kristaps    2: .\"
1.6       kristaps    3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
1.1       kristaps    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
1.15      kristaps   25: .Nd mdoc language reference
1.1       kristaps   26: .\" SECTION
                     27: .Sh DESCRIPTION
                     28: The
                     29: .Nm mdoc
                     30: language is used to format
                     31: .Bx
                     32: .Ux
1.13      kristaps   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
1.1       kristaps   40: .Nm
                     41: document follows simple rules:  lines beginning with the control
1.13      kristaps   42: character
1.1       kristaps   43: .Sq \.
                     44: are parsed for macros.  Other lines are interpreted within the scope of
1.13      kristaps   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
1.1       kristaps   50: .\" SECTION
1.13      kristaps   51: .Sh INPUT ENCODING
1.1       kristaps   52: .Nm
1.13      kristaps   53: documents may contain only graphable 7-bit ASCII characters, the space
                     54: character
1.1       kristaps   55: .Sq \  ,
                     56: and, in certain circumstances, the tab character
                     57: .Sq \et .
                     58: All manuals must have
                     59: .Sq \en
1.10      kristaps   60: line termination.
                     61: .Pp
                     62: The only time a blank line is acceptable is within
                     63: the context of
1.16      kristaps   64: .Sq \&.Bd \-literal
1.10      kristaps   65: or
1.16      kristaps   66: .Sq \&.Bd \-unfilled .
1.10      kristaps   67: .Pp
                     68: Tab characters
                     69: .Pq \et
                     70: are only acceptable when delimiting
1.16      kristaps   71: .Sq \&.Bl \-column
1.10      kristaps   72: and in
1.16      kristaps   73: .Sq \&.Bd \-literal
1.10      kristaps   74: or
1.16      kristaps   75: .Sq \&.Bd \-unfilled
1.10      kristaps   76: contexts.
1.1       kristaps   77: .\" SUB-SECTION
1.2       kristaps   78: .Ss Reserved Characters
                     79: Within a macro line, the following characters are reserved:
                     80: .Bl -tag -width 12n -offset XXXX -compact
1.1       kristaps   81: .It \&.
1.2       kristaps   82: .Pq period
1.1       kristaps   83: .It \&,
1.2       kristaps   84: .Pq comma
1.1       kristaps   85: .It \&:
1.2       kristaps   86: .Pq colon
1.1       kristaps   87: .It \&;
1.2       kristaps   88: .Pq semicolon
1.1       kristaps   89: .It \&(
1.2       kristaps   90: .Pq left-parenthesis
1.1       kristaps   91: .It \&)
1.2       kristaps   92: .Pq right-parenthesis
1.1       kristaps   93: .It \&[
1.2       kristaps   94: .Pq left-bracket
1.1       kristaps   95: .It \&]
1.2       kristaps   96: .Pq right-bracket
1.1       kristaps   97: .It \&?
1.2       kristaps   98: .Pq question
1.1       kristaps   99: .It \&!
1.5       kristaps  100: .Pq exclamation
1.1       kristaps  101: .El
1.5       kristaps  102: .\" PARAGRAPH
1.1       kristaps  103: .Pp
1.5       kristaps  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
1.1       kristaps  108: .Pq Sq \e&
1.5       kristaps  109: or, if applicable, an appropriate escape-sequence used.
1.1       kristaps  110: .\" SUB-SECTION
                    111: .Ss Special Characters
                    112: Special character sequences begin with the escape character
1.16      kristaps  113: .Sq \e
1.4       kristaps  114: followed by either an open-parenthesis
1.1       kristaps  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,
1.16      kristaps  123: .Sq \e* ,
1.4       kristaps  124: with the same combinations as described above.  This form is deprecated.
1.1       kristaps  125: .\" SECTION
1.17      kristaps  126: .Sh STRUCTURE
1.13      kristaps  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.
1.4       kristaps  132: .\" SUB-SECTION
                    133: .Ss Scope
1.2       kristaps  134: .Bl -inset
1.1       kristaps  135: .\" LIST-ITEM
                    136: .It Em Block
1.2       kristaps  137: macros enclose other block macros, in-line macros or text, and
1.4       kristaps  138: may span multiple lines.
1.2       kristaps  139: .Bl -inset -offset XXXX
1.1       kristaps  140: .\" LIST-ITEM
                    141: .It Em Full-block
1.5       kristaps  142: macros always span multiple lines.  They consist of zero or
1.2       kristaps  143: more
1.1       kristaps  144: .Qq heads ,
1.5       kristaps  145: subsequent macros or text on the same line following invocation; an
                    146: optional
1.1       kristaps  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
1.5       kristaps  153: macros may span multiple lines.  They consists of a optional
1.1       kristaps  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
1.4       kristaps  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
1.1       kristaps  185: .El
1.4       kristaps  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.
1.1       kristaps  211: .\" SECTION
1.2       kristaps  212: .Sh SYNTAX
1.17      kristaps  213: Macros are two or three characters in length.  The syntax of macro
                    214: invocation depends on its classification.
1.2       kristaps  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).
1.4       kristaps  222: .\" PARAGRAPH
1.2       kristaps  223: .Pp
1.4       kristaps  224: Block full-explicit (may contain head, body, tail).
1.2       kristaps  225: .Bd -literal -offset XXXX
1.4       kristaps  226: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
                    227: \(lBbody...\(rB
                    228: \&.Yc \(lBtail...\(rB
1.2       kristaps  229: .Ed
1.4       kristaps  230: .\" PARAGRAPH
1.2       kristaps  231: .Pp
1.4       kristaps  232: Block full-implicit (may contain zero or more heads, body, no tail).
1.2       kristaps  233: .Bd -literal -offset XXXX
1.4       kristaps  234: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
                    235: \(lBbody...\(rB
1.2       kristaps  236: \&.Yc
                    237: .Ed
1.4       kristaps  238: .\" PARAGRAPH
1.2       kristaps  239: .Pp
1.4       kristaps  240: Block partial-explicit (may contain head, multi-line body, tail).
1.2       kristaps  241: .Bd -literal -offset XXXX
                    242: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
1.4       kristaps  243: \(lBbody...\(rB
                    244: \&.Yc \(lBtail...\(rB
1.2       kristaps  245:
                    246: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
1.4       kristaps  247: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2       kristaps  248: .Ed
1.4       kristaps  249: .\" PARAGRAPH
1.2       kristaps  250: .Pp
1.4       kristaps  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.
1.2       kristaps  255: .Bd -literal -offset XXXX
1.4       kristaps  256: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
1.2       kristaps  257: .Ed
1.4       kristaps  258: .\" PARAGRAPH
1.2       kristaps  259: .Pp
1.4       kristaps  260: In-lines have \(>=0 scoped arguments.
1.2       kristaps  261: .Bd -literal -offset XXX
1.4       kristaps  262: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
1.2       kristaps  263:
                    264: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
                    265: .Ed
                    266: .\"
1.1       kristaps  267: .Sh MACROS
                    268: This section contains a complete list of all
                    269: .Nm
1.2       kristaps  270: macros, arranged ontologically.  A
1.1       kristaps  271: .Qq callable
1.17      kristaps  272: macro is invoked subsequent to the initial macro-line macro.  A
1.1       kristaps  273: .Qq parsable
1.2       kristaps  274: macro may be followed by further (ostensibly callable) macros.
1.1       kristaps  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
1.16      kristaps  281: .Sq \&.It \-bullet ,
1.1       kristaps  282: .Sq \-hyphen ,
                    283: .Sq \-dash ,
1.2       kristaps  284: .Sq \-enum ,
                    285: .Sq \-item
1.1       kristaps  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
1.2       kristaps  309: .It \&.Bk    Ta    \&No    Ta    \&No    Ta    closed by \&.Ek
                    310: .It \&.Ek    Ta    \&No    Ta    \&No    Ta    opened by \&.Bk
1.1       kristaps  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
1.2       kristaps  327: .It \&.D1    Ta    \&No  Ta    \&Yes
                    328: .It \&.Dl    Ta    \&No  Ta    Yes
                    329: .It \&.Ql    Ta    Yes   Ta    Yes
1.1       kristaps  330: .El
1.13      kristaps  331: .\" PARAGRAPH
                    332: .Pp
                    333: The
1.16      kristaps  334: .Sq \&.Op
                    335: may be broken by
                    336: .Sq \&.Oc
                    337: as in the following example:
1.13      kristaps  338: .Bd -literal -offset XXXX
                    339: \&.Oo
                    340: \&.Op Fl a Oc
                    341: .Ed
                    342: .Pp
                    343: In the above example, the scope of
1.16      kristaps  344: .Sq \&.Op
1.13      kristaps  345: is technically broken by
1.16      kristaps  346: .Sq \&.Oc ,
1.13      kristaps  347: however, due to the overwhelming existence of this sequence, it's
                    348: allowed.
1.1       kristaps  349: .\" SUB-SECTION
                    350: .Ss Block partial-explicit
                    351: Each of these contains at least a body and, in limited circumstances, a
                    352: head
1.16      kristaps  353: .Pq So \&.Fo Sc , So \&.Eo Sc
1.1       kristaps  354: and/or tail
1.16      kristaps  355: .Pq So \&.Ec Sc .
1.1       kristaps  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
1.2       kristaps  381: .It \&.Re    Ta    \&No  Ta    \&No   Ta    opened by \&.Rs
                    382: .It \&.Rs    Ta    \&No  Ta    \&No   Ta    closed by \&.Re
1.1       kristaps  383: .El
                    384: .\" SUB-SECTION
1.2       kristaps  385: .Ss In-line
1.3       kristaps  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.
1.2       kristaps  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
1.3       kristaps  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
1.2       kristaps  396: .It \&.Pp    Ta    \&No  Ta    \&No    Ta    0
1.3       kristaps  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
1.11      kristaps  402: .It \&.Dv    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  403: .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0
1.11      kristaps  404: .It \&.Ev    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  405: .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0
1.12      kristaps  406: .It \&.Fa    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  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
1.11      kristaps  413: .It \&.Li    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  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
1.11      kristaps  420: .It \&.Va    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  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
1.19    ! kristaps  439: .It \&.Em    Ta    Yes   Ta    Yes     Ta    >0
1.3       kristaps  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
1.6       kristaps  452: .It \&.Dx    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  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
1.6       kristaps  462: .It \&.Es    Ta    \&No  Ta    \&No    Ta    0
                    463: .It \&.En    Ta    \&No  Ta    \&No    Ta    0
1.1       kristaps  464: .El
1.6       kristaps  465: .Pp
                    466: The
1.16      kristaps  467: .Sq \&.Ot ,
                    468: .Sq \&.Fr ,
                    469: .Sq \&.Es
1.6       kristaps  470: and
1.16      kristaps  471: .Sq \&.En ,
1.6       kristaps  472: macros are obsolete.
1.2       kristaps  473: .\" SECTION
1.4       kristaps  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
1.16      kristaps  484: .Sq \&.Fo
1.5       kristaps  485: and
1.16      kristaps  486: .Sq \&.St
1.5       kristaps  487: historically weren't always callable.  Both are now correctly callable.
                    488: .\" LIST-ITEM
                    489: .It
1.16      kristaps  490: .Sq \&.It \-nested
1.4       kristaps  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
1.16      kristaps  496: .Sq \&.It \-column
1.4       kristaps  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
1.16      kristaps  502: .Sq \&.At
1.4       kristaps  503: macro only accepts a single parameter.
                    504: .\" LIST-ITEM
                    505: .It
                    506: The system-name macros (
1.16      kristaps  507: .Ns Sq \&.At ,
                    508: .Sq \&.Bsx ,
                    509: .Sq \&.Bx ,
                    510: .Sq \&.Fx ,
                    511: .Sq \&.Nx ,
                    512: .Sq \&.Ox ,
1.4       kristaps  513: and
1.16      kristaps  514: .Sq \&.Ux )
1.4       kristaps  515: are callable.
                    516: .\" LIST-ITEM
                    517: .It
                    518: Some manuals use
1.16      kristaps  519: .Sq \&.Li
1.4       kristaps  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
1.16      kristaps  524: .Sq \&.Cd
1.4       kristaps  525: is callable.
                    526: .El
                    527: .\" SECTION
1.2       kristaps  528: .Sh SEE ALSO
1.19    ! kristaps  529: .Xr mandoc 1 ,
        !           530: .Xr mandoc_char 7
1.2       kristaps  531: .\" SECTION
                    532: .Sh AUTHORS
                    533: The
                    534: .Nm
                    535: utility was written by
1.6       kristaps  536: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
1.5       kristaps  537: .\" SECTION
                    538: .Sh CAVEATS
                    539: There are several ambiguous parts of mdoc.
                    540: .Pp
                    541: .Bl -dash -compact
                    542: .\" LIST-ITEM
                    543: .It
1.16      kristaps  544: .Sq \&.Fa
1.5       kristaps  545: should be
1.16      kristaps  546: .Sq \&.Va
1.5       kristaps  547: as function arguments are variables.
                    548: .\" LIST-ITEM
                    549: .It
1.16      kristaps  550: .Sq \&.Ft
1.5       kristaps  551: should be
1.16      kristaps  552: .Sq \&.Vt
1.5       kristaps  553: as function return types are still types.  Furthermore, the
1.16      kristaps  554: .Sq \&.Ft
1.5       kristaps  555: should be removed and
1.16      kristaps  556: .Sq \&.Fo ,
1.5       kristaps  557: which ostensibly follows it, should follow the same convention as
1.16      kristaps  558: .Sq \&.Va .
1.5       kristaps  559: .\" LIST-ITEM
                    560: .It
1.16      kristaps  561: .Sq \&.Va
1.5       kristaps  562: should formalise that only one or two arguments are acceptable: a
                    563: variable name and optional, preceeding type.
                    564: .\" LIST-ITEM
                    565: .It
1.16      kristaps  566: .Sq \&.Fd
1.5       kristaps  567: is ambiguous.  It's commonly used to indicate an include file in the
                    568: synopsis section.
1.16      kristaps  569: .Sq \&.In
1.5       kristaps  570: should be used, instead.
                    571: .\" LIST-ITEM
                    572: .It
                    573: Only the
                    574: .Sq \-literal
                    575: argument to
1.16      kristaps  576: .Sq \&.Bd
1.5       kristaps  577: makes sense.  The remaining ones should be removed.
                    578: .\" LIST-ITEM
                    579: .It
                    580: The
1.16      kristaps  581: .Sq \&.Xo
1.5       kristaps  582: and
1.16      kristaps  583: .Sq \&.Xc
1.5       kristaps  584: macros should be deprecated.
                    585: .\" LIST-ITEM
                    586: .It
                    587: The
1.16      kristaps  588: .Sq \&.Dt
1.5       kristaps  589: macro lacks clarity.  It should be absolutely clear which title will
                    590: render when formatting the manual page.
1.6       kristaps  591: .\" LIST-ITEM
                    592: .It
                    593: A
1.16      kristaps  594: .Sq \&.Lx
1.6       kristaps  595: should be provided for Linux (\(`a la
1.16      kristaps  596: .Sq \&.Ox ,
                    597: .Sq \&.Nx
1.6       kristaps  598: etc.).
1.14      kristaps  599: .\" LIST-ITEM
                    600: .It
                    601: There's no way to refer to references in
1.16      kristaps  602: .Sq \&.Rs/.Re
1.14      kristaps  603: blocks.
1.5       kristaps  604: .El

CVSweb