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

Annotation of mandoc/mdoc.7, Revision 1.40

1.40    ! kristaps    1: .\"    $Id: mdoc.7,v 1.39 2009/07/12 15:32:26 kristaps Exp $
1.1       kristaps    2: .\"
1.23      kristaps    3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1       kristaps    4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
1.22      kristaps    6: .\" purpose with or without fee is hereby granted, provided that the above
                      7: .\" copyright notice and this permission notice appear in all copies.
1.1       kristaps    8: .\"
1.22      kristaps    9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1       kristaps   16: .\"
                     17: .Dd $Mdocdate$
1.20      kristaps   18: .Dt MDOC 7
1.1       kristaps   19: .Os
                     20: .\" SECTION
                     21: .Sh NAME
                     22: .Nm mdoc
1.15      kristaps   23: .Nd mdoc language reference
1.1       kristaps   24: .\" SECTION
                     25: .Sh DESCRIPTION
                     26: The
                     27: .Nm mdoc
                     28: language is used to format
                     29: .Bx
                     30: .Ux
1.33      kristaps   31: manuals.  In this reference document, we describe the syntax and
                     32: structure of the
1.13      kristaps   33: .Nm
1.28      kristaps   34: language.  Our reference implementation is
                     35: .Xr mandoc 1 .
                     36: The
                     37: .Sx COMPATIBILITY
                     38: section describes compatibility with
                     39: .Xr groff 1 .
1.13      kristaps   40: .\" PARAGRAPH
                     41: .Pp
                     42: An
1.1       kristaps   43: .Nm
                     44: document follows simple rules:  lines beginning with the control
1.13      kristaps   45: character
1.1       kristaps   46: .Sq \.
                     47: are parsed for macros.  Other lines are interpreted within the scope of
1.13      kristaps   48: prior macros:
1.39      kristaps   49: .Bd -literal -offset indent
1.13      kristaps   50: \&.Sh Macro lines change control state.
                     51: Other lines are interpreted within the current state.
                     52: .Ed
1.1       kristaps   53: .\" SECTION
1.13      kristaps   54: .Sh INPUT ENCODING
1.1       kristaps   55: .Nm
1.13      kristaps   56: documents may contain only graphable 7-bit ASCII characters, the space
                     57: character
1.1       kristaps   58: .Sq \  ,
                     59: and, in certain circumstances, the tab character
                     60: .Sq \et .
                     61: All manuals must have
                     62: .Sq \en
1.10      kristaps   63: line termination.
                     64: .Pp
                     65: The only time a blank line is acceptable is within
                     66: the context of
1.16      kristaps   67: .Sq \&.Bd \-literal
1.10      kristaps   68: or
1.16      kristaps   69: .Sq \&.Bd \-unfilled .
1.10      kristaps   70: .Pp
                     71: Tab characters
                     72: .Pq \et
                     73: are only acceptable when delimiting
1.16      kristaps   74: .Sq \&.Bl \-column
1.10      kristaps   75: and in
1.16      kristaps   76: .Sq \&.Bd \-literal
1.10      kristaps   77: or
1.16      kristaps   78: .Sq \&.Bd \-unfilled
1.10      kristaps   79: contexts.
1.1       kristaps   80: .\" SUB-SECTION
1.29      kristaps   81: .Ss Comments
                     82: Anything following a
                     83: .Sq \e"
                     84: delimiter is considered a comment (unless the
                     85: .Sq \e
                     86: itself has been escaped) and is ignored to the end of line.
                     87: Furthermore, a macro line with only a control character
                     88: .Sq \. ,
                     89: optionally followed by whitespace, is ignored.
                     90: .\" SUB-SECTION
1.2       kristaps   91: .Ss Reserved Characters
                     92: Within a macro line, the following characters are reserved:
1.39      kristaps   93: .Bl -tag -width Ds -offset indent -compact
1.1       kristaps   94: .It \&.
1.2       kristaps   95: .Pq period
1.1       kristaps   96: .It \&,
1.2       kristaps   97: .Pq comma
1.1       kristaps   98: .It \&:
1.2       kristaps   99: .Pq colon
1.1       kristaps  100: .It \&;
1.2       kristaps  101: .Pq semicolon
1.1       kristaps  102: .It \&(
1.2       kristaps  103: .Pq left-parenthesis
1.1       kristaps  104: .It \&)
1.2       kristaps  105: .Pq right-parenthesis
1.1       kristaps  106: .It \&[
1.2       kristaps  107: .Pq left-bracket
1.1       kristaps  108: .It \&]
1.2       kristaps  109: .Pq right-bracket
1.1       kristaps  110: .It \&?
1.2       kristaps  111: .Pq question
1.1       kristaps  112: .It \&!
1.5       kristaps  113: .Pq exclamation
1.28      kristaps  114: .It \&|
                    115: .Pq vertical bar
1.1       kristaps  116: .El
1.5       kristaps  117: .\" PARAGRAPH
1.1       kristaps  118: .Pp
1.5       kristaps  119: Use of reserved characters is described in
                    120: .Sx Closure .
                    121: For general non-reserved use, characters must either be escaped with a
                    122: non-breaking space
1.1       kristaps  123: .Pq Sq \e&
1.5       kristaps  124: or, if applicable, an appropriate escape-sequence used.
1.1       kristaps  125: .\" SUB-SECTION
                    126: .Ss Special Characters
                    127: Special character sequences begin with the escape character
1.16      kristaps  128: .Sq \e
1.4       kristaps  129: followed by either an open-parenthesis
1.1       kristaps  130: .Sq \&(
                    131: for two-character sequences; an open-bracket
                    132: .Sq \&[
                    133: for n-character sequences (terminated at a close-bracket
                    134: .Sq \&] ) ;
                    135: or a single one-character sequence.
                    136: .Pp
                    137: Characters may alternatively be escaped by a slash-asterisk,
1.16      kristaps  138: .Sq \e* ,
1.35      kristaps  139: with the same combinations as described above.
                    140: .Pp
                    141: Terms may also be text-decorated using the
                    142: .Sq \ef
                    143: escape followed by a text-decoration letter: B (bold), I, (italic), or P
                    144: and R (Roman, or reset).  This form is not recommended.
1.34      kristaps  145: .\" SUB-SECTION
                    146: .Ss Whitespace
                    147: Unless in literal mode or specifically escaped, consecutive blocks of
                    148: whitespace are pruned from input.  These are later re-added, if
                    149: applicable, by a front-end utility such as
                    150: .Xr mandoc 1 .
1.1       kristaps  151: .\" SECTION
1.17      kristaps  152: .Sh STRUCTURE
1.33      kristaps  153: Each
                    154: .Nm
                    155: document must begin with the document prologue, containing, in order,
                    156: .Sq \&.Dd ,
                    157: .Sq \&.Dt ,
                    158: and
                    159: .Sq \&.Os .
                    160: Following these, the document body must begin with the NAME section
                    161: containing at least one
                    162: .Sq \&.Nm
                    163: followed by a
                    164: .Sq \&.Nd
                    165: macro.
                    166: .Pp
                    167: At least one free-form or macro line must follow this prologue.
                    168: .\"
                    169: .Ss Classification
                    170: Macros are classified by their scope rules.  Some macros are allowed to
                    171: deviate from their classifications to preserve backward-compatibility
                    172: with old macro combinations still found in the manual corpus.  These are
                    173: specifically noted on a per-macro basis.
1.4       kristaps  174: .\" SUB-SECTION
                    175: .Ss Scope
1.2       kristaps  176: .Bl -inset
1.1       kristaps  177: .\" LIST-ITEM
                    178: .It Em Block
1.2       kristaps  179: macros enclose other block macros, in-line macros or text, and
1.4       kristaps  180: may span multiple lines.
1.39      kristaps  181: .Bl -inset -offset indent
1.1       kristaps  182: .\" LIST-ITEM
                    183: .It Em Full-block
1.5       kristaps  184: macros always span multiple lines.  They consist of zero or
1.2       kristaps  185: more
1.1       kristaps  186: .Qq heads ,
1.5       kristaps  187: subsequent macros or text on the same line following invocation; an
                    188: optional
1.1       kristaps  189: .Qq body ,
                    190: which spans subsequent lines of text or macros; and an optional
                    191: .Qq tail ,
                    192: macros or text on the same line following closure.
                    193: .\" LIST-ITEM
                    194: .It Em Partial-block
1.5       kristaps  195: macros may span multiple lines.  They consists of a optional
1.1       kristaps  196: .Qq head ,
                    197: text immediately following invocation; always a
                    198: .Qq body ,
                    199: text or macros following the head on the same and subsequent lines; and
                    200: optionally a
                    201: .Qq tail ,
                    202: text immediately following closure.
                    203: .\" LIST-ITEM
                    204: .It Em In-line
1.4       kristaps  205: macros may only enclose text and span at most a single line.
                    206: .El
                    207: .El
                    208: .\" SUB-SECTION
                    209: .Ss Closure
                    210: Closure of a macro's scope depends first on its classification, then
                    211: on whether it's parsable.  In this table,
                    212: .Sq BFE
                    213: refers to block full-explicit and so on.
                    214: .\" PARAGRAPH
                    215: .Pp
1.39      kristaps  216: .Bl -tag -width 12n -offset indent -compact
1.4       kristaps  217: .It BPE , BFE
                    218: corresponding explicit closure macro
                    219: .It BFI
                    220: end-of-file or a corresponding implicit closure macro
                    221: .It BPI
                    222: end-of-line (body may be closed by >0 space-separated
                    223: .Sx Reserved Characters ,
                    224: although block scope will still be open)
                    225: .It INL
                    226: end-of-line
1.1       kristaps  227: .El
1.4       kristaps  228: .\" PARAGRAPH
                    229: .Pp
                    230: If a macro (block or in-line) is parsable, it may also be closed out by
                    231: one of the following scenarios (unless specifically noted otherwise):
                    232: .\" PARAGRAPH
                    233: .Pp
1.39      kristaps  234: .Bl -dash -offset indent -compact
1.4       kristaps  235: .It
                    236: a sequence of >0 space-separated
                    237: .Sx Reserved Characters ,
                    238: .It
                    239: another macro,
                    240: .It
                    241: end-of-line, or
                    242: .It
                    243: completion of a set number of arguments.
                    244: .El
                    245: .\" PARAGRAPH
                    246: .Pp
                    247: If >0 space-separated
                    248: .Sx Reserved Characters
                    249: are followed by non-reserved characters, the behaviour differs per
                    250: macro.  In general, scope of the macro is closed and re-opened:
                    251: subsequent tokens are interpreted as if the scope had just been opened.
                    252: In other circumstances, scope is simply closed out.
1.1       kristaps  253: .\" SECTION
1.2       kristaps  254: .Sh SYNTAX
1.17      kristaps  255: Macros are two or three characters in length.  The syntax of macro
                    256: invocation depends on its classification.
1.2       kristaps  257: .Qq \-arg
                    258: refers to the macro arguments (which may contain zero or more values).
                    259: In these illustrations,
                    260: .Sq \&.Yo
                    261: opens the scope of a macro, and if specified,
                    262: .Sq \&.Yc
                    263: closes it out (closure may be implicit at end-of-line or end-of-file).
1.4       kristaps  264: .\" PARAGRAPH
1.2       kristaps  265: .Pp
1.4       kristaps  266: Block full-explicit (may contain head, body, tail).
1.39      kristaps  267: .Bd -literal -offset indent
1.4       kristaps  268: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
                    269: \(lBbody...\(rB
                    270: \&.Yc \(lBtail...\(rB
1.2       kristaps  271: .Ed
1.4       kristaps  272: .\" PARAGRAPH
1.2       kristaps  273: .Pp
1.4       kristaps  274: Block full-implicit (may contain zero or more heads, body, no tail).
1.39      kristaps  275: .Bd -literal -offset indent
1.4       kristaps  276: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
                    277: \(lBbody...\(rB
1.2       kristaps  278: \&.Yc
                    279: .Ed
1.4       kristaps  280: .\" PARAGRAPH
1.2       kristaps  281: .Pp
1.4       kristaps  282: Block partial-explicit (may contain head, multi-line body, tail).
1.39      kristaps  283: .Bd -literal -offset indent
1.2       kristaps  284: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
1.4       kristaps  285: \(lBbody...\(rB
                    286: \&.Yc \(lBtail...\(rB
1.2       kristaps  287:
                    288: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
1.4       kristaps  289: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2       kristaps  290: .Ed
1.4       kristaps  291: .\" PARAGRAPH
1.2       kristaps  292: .Pp
1.4       kristaps  293: Block partial-implicit (no head, body, no tail).  Note that the body
                    294: section may be followed by zero or more
                    295: .Sx Reserved Words .
                    296: These are in the block scope, but not in the body scope.
1.39      kristaps  297: .Bd -literal -offset indent
1.4       kristaps  298: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
1.2       kristaps  299: .Ed
1.4       kristaps  300: .\" PARAGRAPH
1.2       kristaps  301: .Pp
1.4       kristaps  302: In-lines have \(>=0 scoped arguments.
1.39      kristaps  303: .Bd -literal -offset indent
1.4       kristaps  304: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
1.2       kristaps  305:
                    306: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
                    307: .Ed
1.32      kristaps  308: .\" SECTION
1.1       kristaps  309: .Sh MACROS
                    310: This section contains a complete list of all
                    311: .Nm
1.33      kristaps  312: macros, arranged by classification.  A
1.1       kristaps  313: .Qq callable
1.17      kristaps  314: macro is invoked subsequent to the initial macro-line macro.  A
1.1       kristaps  315: .Qq parsable
1.2       kristaps  316: macro may be followed by further (ostensibly callable) macros.
1.1       kristaps  317: .\" SUB-SECTION
                    318: .Ss Block full-implicit
                    319: The head of these macros follows invocation; the body is the content of
                    320: subsequent lines prior to closure.  None of these macros have tails;
                    321: some
                    322: .Po
1.16      kristaps  323: .Sq \&.It \-bullet ,
1.1       kristaps  324: .Sq \-hyphen ,
                    325: .Sq \-dash ,
1.2       kristaps  326: .Sq \-enum ,
                    327: .Sq \-item
1.1       kristaps  328: .Pc
                    329: don't have heads.
                    330: .Pp
1.39      kristaps  331: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "Closing"
1.1       kristaps  332: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
1.40    ! kristaps  333: .It \&.Nd    Ta    \&No    Ta    \&No    Ta    \&.Sh
1.1       kristaps  334: .It \&.Sh    Ta    \&No    Ta    \&No    Ta    \&.Sh
                    335: .It \&.Ss    Ta    \&No    Ta    \&No    Ta    \&.Sh, \&.Ss
                    336: .It \&.It    Ta    \&No    Ta    Yes     Ta    \&.It, \&.El
                    337: .El
                    338: .\" SUB-SECTION
                    339: .Ss Block full-explicit
                    340: None of these macros are callable or parsed.  The last column indicates
                    341: the explicit scope rules.  All contains bodies, some may contain heads
                    342: .Pq So \&Bf Sc .
                    343: .Pp
1.39      kristaps  344: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
1.1       kristaps  345: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    346: .It \&.Bd    Ta    \&No    Ta    \&No    Ta    closed by \&.Ed
                    347: .It \&.Ed    Ta    \&No    Ta    \&No    Ta    opened by \&.Bd
                    348: .It \&.Bl    Ta    \&No    Ta    \&No    Ta    closed by \&.El
                    349: .It \&.El    Ta    \&No    Ta    \&No    Ta    opened by \&.Bl
                    350: .It \&.Bf    Ta    \&No    Ta    \&No    Ta    closed by \&.Ef
                    351: .It \&.Ef    Ta    \&No    Ta    \&No    Ta    opened by \&.Bf
1.2       kristaps  352: .It \&.Bk    Ta    \&No    Ta    \&No    Ta    closed by \&.Ek
                    353: .It \&.Ek    Ta    \&No    Ta    \&No    Ta    opened by \&.Bk
1.1       kristaps  354: .El
                    355: .\" SUB-SECTION
                    356: .Ss Block partial-implicit
                    357: All of these are callable and parsed for further macros.  Their scopes
                    358: close at the invocation's end-of-line.
                    359: .Pp
1.39      kristaps  360: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
1.1       kristaps  361: .It Em Macro Ta Em Callable Ta Em Parsable
                    362: .It \&.Aq    Ta    Yes   Ta    Yes
                    363: .It \&.Op    Ta    Yes   Ta    Yes
                    364: .It \&.Bq    Ta    Yes   Ta    Yes
                    365: .It \&.Dq    Ta    Yes   Ta    Yes
                    366: .It \&.Pq    Ta    Yes   Ta    Yes
                    367: .It \&.Qq    Ta    Yes   Ta    Yes
                    368: .It \&.Sq    Ta    Yes   Ta    Yes
                    369: .It \&.Brq   Ta    Yes   Ta    Yes
1.2       kristaps  370: .It \&.D1    Ta    \&No  Ta    \&Yes
                    371: .It \&.Dl    Ta    \&No  Ta    Yes
                    372: .It \&.Ql    Ta    Yes   Ta    Yes
1.1       kristaps  373: .El
1.13      kristaps  374: .\" PARAGRAPH
                    375: .Pp
                    376: The
1.16      kristaps  377: .Sq \&.Op
                    378: may be broken by
                    379: .Sq \&.Oc
                    380: as in the following example:
1.39      kristaps  381: .Bd -literal -offset indent
1.13      kristaps  382: \&.Oo
                    383: \&.Op Fl a Oc
                    384: .Ed
                    385: .Pp
                    386: In the above example, the scope of
1.16      kristaps  387: .Sq \&.Op
1.13      kristaps  388: is technically broken by
1.16      kristaps  389: .Sq \&.Oc ,
1.13      kristaps  390: however, due to the overwhelming existence of this sequence, it's
                    391: allowed.
1.1       kristaps  392: .\" SUB-SECTION
                    393: .Ss Block partial-explicit
                    394: Each of these contains at least a body and, in limited circumstances, a
                    395: head
1.16      kristaps  396: .Pq So \&.Fo Sc , So \&.Eo Sc
1.1       kristaps  397: and/or tail
1.16      kristaps  398: .Pq So \&.Ec Sc .
1.1       kristaps  399: .Pp
1.39      kristaps  400: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
1.1       kristaps  401: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    402: .It \&.Ao    Ta    Yes   Ta    Yes    Ta    closed by \&.Ac
                    403: .It \&.Ac    Ta    Yes   Ta    Yes    Ta    opened by \&.Ao
                    404: .It \&.Bc    Ta    Yes   Ta    Yes    Ta    closed by \&.Bo
                    405: .It \&.Bo    Ta    Yes   Ta    Yes    Ta    opened by \&.Bc
                    406: .It \&.Pc    Ta    Yes   Ta    Yes    Ta    closed by \&.Po
                    407: .It \&.Po    Ta    Yes   Ta    Yes    Ta    opened by \&.Pc
                    408: .It \&.Do    Ta    Yes   Ta    Yes    Ta    closed by \&.Dc
                    409: .It \&.Dc    Ta    Yes   Ta    Yes    Ta    opened by \&.Do
                    410: .It \&.Xo    Ta    Yes   Ta    Yes    Ta    closed by \&.Xc
                    411: .It \&.Xc    Ta    Yes   Ta    Yes    Ta    opened by \&.Xo
                    412: .It \&.Bro   Ta    Yes   Ta    Yes    Ta    closed by \&.Brc
                    413: .It \&.Brc   Ta    Yes   Ta    Yes    Ta    opened by \&.Bro
                    414: .It \&.Oc    Ta    Yes   Ta    Yes    Ta    closed by \&.Oo
                    415: .It \&.Oo    Ta    Yes   Ta    Yes    Ta    opened by \&.Oc
                    416: .It \&.So    Ta    Yes   Ta    Yes    Ta    closed by \&.Sc
                    417: .It \&.Sc    Ta    Yes   Ta    Yes    Ta    opened by \&.So
                    418: .It \&.Fc    Ta    Yes   Ta    Yes    Ta    opened by \&.Fo
                    419: .It \&.Fo    Ta    \&No  Ta    \&No   Ta    closed by \&.Fc
                    420: .It \&.Ec    Ta    Yes   Ta    Yes    Ta    opened by \&.Eo
                    421: .It \&.Eo    Ta    Yes   Ta    Yes    Ta    closed by \&.Ec
                    422: .It \&.Qc    Ta    Yes   Ta    Yes    Ta    opened by \&.Oo
                    423: .It \&.Qo    Ta    Yes   Ta    Yes    Ta    closed by \&.Oc
1.2       kristaps  424: .It \&.Re    Ta    \&No  Ta    \&No   Ta    opened by \&.Rs
                    425: .It \&.Rs    Ta    \&No  Ta    \&No   Ta    closed by \&.Re
1.1       kristaps  426: .El
                    427: .\" SUB-SECTION
1.2       kristaps  428: .Ss In-line
1.3       kristaps  429: In-line macros have only text children.  If a number (or inequality) of
                    430: arguments is
                    431: .Pq n ,
                    432: then the macro accepts an arbitrary number of arguments.
1.2       kristaps  433: .Pp
1.39      kristaps  434: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
1.2       kristaps  435: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.3       kristaps  436: .It \&.Dd    Ta    \&No  Ta    \&No    Ta    >0
                    437: .It \&.Dt    Ta    \&No  Ta    \&No    Ta    n
                    438: .It \&.Os    Ta    \&No  Ta    \&No    Ta    n
1.2       kristaps  439: .It \&.Pp    Ta    \&No  Ta    \&No    Ta    0
1.3       kristaps  440: .It \&.Ad    Ta    Yes   Ta    Yes     Ta    n
1.25      kristaps  441: .It \&.An    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  442: .It \&.Ar    Ta    Yes   Ta    Yes     Ta    n
                    443: .It \&.Cd    Ta    Yes   Ta    \&No    Ta    >0
                    444: .It \&.Cm    Ta    Yes   Ta    Yes     Ta    n
1.11      kristaps  445: .It \&.Dv    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  446: .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0
1.11      kristaps  447: .It \&.Ev    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  448: .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0
1.12      kristaps  449: .It \&.Fa    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  450: .It \&.Fd    Ta    \&No  Ta    \&No    Ta    >0
                    451: .It \&.Fl    Ta    Yes   Ta    Yes     Ta    n
                    452: .It \&.Fn    Ta    Yes   Ta    Yes     Ta    >0
1.26      kristaps  453: .It \&.Ft    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  454: .It \&.Ic    Ta    Yes   Ta    Yes     Ta    >0
                    455: .It \&.In    Ta    \&No  Ta    \&No    Ta    n
1.11      kristaps  456: .It \&.Li    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  457: .It \&.Nm    Ta    Yes   Ta    Yes     Ta    n
                    458: .It \&.Ot    Ta    \&No  Ta    \&No    Ta    n
                    459: .It \&.Pa    Ta    Yes   Ta    Yes     Ta    n
                    460: .It \&.Rv    Ta    \&No  Ta    \&No    Ta    0
                    461: .It \&.St    Ta    \&No  Ta    Yes     Ta    1
1.11      kristaps  462: .It \&.Va    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  463: .It \&.Vt    Ta    Yes   Ta    Yes     Ta    >0
                    464: .It \&.Xr    Ta    Yes   Ta    Yes     Ta    >0, <3
                    465: .It \&.%A    Ta    \&No  Ta    \&No    Ta    >0
                    466: .It \&.%B    Ta    \&No  Ta    \&No    Ta    >0
                    467: .It \&.%C    Ta    \&No  Ta    \&No    Ta    >0
                    468: .It \&.%D    Ta    \&No  Ta    \&No    Ta    >0
                    469: .It \&.%I    Ta    \&No  Ta    \&No    Ta    >0
                    470: .It \&.%J    Ta    \&No  Ta    \&No    Ta    >0
                    471: .It \&.%N    Ta    \&No  Ta    \&No    Ta    >0
                    472: .It \&.%O    Ta    \&No  Ta    \&No    Ta    >0
                    473: .It \&.%P    Ta    \&No  Ta    \&No    Ta    >0
                    474: .It \&.%R    Ta    \&No  Ta    \&No    Ta    >0
                    475: .It \&.%T    Ta    \&No  Ta    \&No    Ta    >0
                    476: .It \&.%V    Ta    \&No  Ta    \&No    Ta    >0
                    477: .It \&.At    Ta    Yes   Ta    Yes     Ta    1
                    478: .It \&.Bsx   Ta    Yes   Ta    Yes     Ta    n
                    479: .It \&.Bx    Ta    Yes   Ta    Yes     Ta    n
                    480: .It \&.Db    Ta    \&No  Ta    \&No    Ta    1
1.19      kristaps  481: .It \&.Em    Ta    Yes   Ta    Yes     Ta    >0
1.3       kristaps  482: .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n
1.26      kristaps  483: .It \&.Ms    Ta    Yes   Ta    Yes     Ta    >0
1.3       kristaps  484: .It \&.No    Ta    Yes   Ta    Yes     Ta    0
                    485: .It \&.Ns    Ta    Yes   Ta    Yes     Ta    0
                    486: .It \&.Nx    Ta    Yes   Ta    Yes     Ta    n
                    487: .It \&.Ox    Ta    Yes   Ta    Yes     Ta    n
                    488: .It \&.Pf    Ta    \&No  Ta    Yes     Ta    1
                    489: .It \&.Sm    Ta    \&No  Ta    \&No    Ta    1
                    490: .It \&.Sx    Ta    Yes   Ta    Yes     Ta    >0
                    491: .It \&.Sy    Ta    Yes   Ta    Yes     Ta    >0
                    492: .It \&.Tn    Ta    Yes   Ta    Yes     Ta    >0
                    493: .It \&.Ux    Ta    Yes   Ta    Yes     Ta    n
1.6       kristaps  494: .It \&.Dx    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  495: .It \&.Bt    Ta    \&No  Ta    \&No    Ta    0
                    496: .It \&.Hf    Ta    \&No  Ta    \&No    Ta    n
                    497: .It \&.Fr    Ta    \&No  Ta    \&No    Ta    n
                    498: .It \&.Ud    Ta    \&No  Ta    \&No    Ta    0
                    499: .It \&.Lb    Ta    \&No  Ta    \&No    Ta    1
                    500: .It \&.Ap    Ta    Yes   Ta    Yes     Ta    0
                    501: .It \&.Lp    Ta    \&No  Ta    \&No    Ta    0
1.27      kristaps  502: .It \&.Lk    Ta    Yes   Ta    Yes     Ta    n
                    503: .It \&.Mt    Ta    Yes   Ta    Yes     Ta    >0
1.6       kristaps  504: .It \&.Es    Ta    \&No  Ta    \&No    Ta    0
                    505: .It \&.En    Ta    \&No  Ta    \&No    Ta    0
1.1       kristaps  506: .El
1.6       kristaps  507: .Pp
                    508: The
1.16      kristaps  509: .Sq \&.Ot ,
                    510: .Sq \&.Fr ,
                    511: .Sq \&.Es
1.6       kristaps  512: and
1.16      kristaps  513: .Sq \&.En ,
1.6       kristaps  514: macros are obsolete.
1.2       kristaps  515: .\" SECTION
1.4       kristaps  516: .Sh COMPATIBILITY
1.28      kristaps  517: This section documents compatibility with other roff implementations, at
                    518: this time limited to
                    519: .Xr groff 1 .
                    520: The term
                    521: .Qq historic groff
                    522: refers to those versions before the
                    523: .Pa doc.tmac
                    524: file re-write
                    525: .Pq somewhere between 1.15 and 1.19 .
1.4       kristaps  526: .Pp
                    527: .Bl -dash -compact
                    528: .\" LIST-ITEM
                    529: .It
1.35      kristaps  530: Some character sequences in groff are not handled depending on escape
                    531: style, e.g.,
                    532: .Sq \e(ba
                    533: and
                    534: .Sq \e*(Ba
                    535: may not be interchanged.  This is no longer the case: all character
                    536: sequences resolve to the same symbol, regardless the escape style.
                    537: .\" LIST-ITEM
                    538: .It
                    539: Blocks of whitespace are stripped from both macro and free-form text
                    540: lines (except when in literal mode), while groff would retain whitespace
                    541: in free-form text lines.
                    542: .\" LIST-ITEM
                    543: .It
1.28      kristaps  544: Historic groff has many un-callable macros.  Most of these (excluding
                    545: some block-level macros) are now callable, conforming to the
                    546: non-historic groff version.
                    547: .\" LIST-ITEM
                    548: .It
                    549: The vertical bar
1.35      kristaps  550: .Sq \(ba
1.28      kristaps  551: made historic groff
                    552: .Qq go orbital
                    553: but is a proper delimiter in this implementation.
1.5       kristaps  554: .\" LIST-ITEM
                    555: .It
1.16      kristaps  556: .Sq \&.It \-nested
1.28      kristaps  557: is assumed for all lists (it wasn't in historic groff): any list may be
                    558: nested and
1.4       kristaps  559: .Sq \-enum
                    560: lists will restart the sequence only for the sub-list.
                    561: .\" LIST-ITEM
                    562: .It
1.16      kristaps  563: .Sq \&.It \-column
1.21      kristaps  564: syntax where column widths may be preceded by other arguments (instead
1.4       kristaps  565: of proceeded) is not supported.
                    566: .\" LIST-ITEM
                    567: .It
                    568: The
1.16      kristaps  569: .Sq \&.At
1.4       kristaps  570: macro only accepts a single parameter.
                    571: .\" LIST-ITEM
                    572: .It
                    573: Some manuals use
1.16      kristaps  574: .Sq \&.Li
1.4       kristaps  575: incorrectly by following it with a reserved character and expecting the
                    576: delimiter to render.  This is not supported.
                    577: .\" LIST-ITEM
                    578: .It
1.35      kristaps  579: If an special-character control character is escaped
                    580: .Sq \e\e ,
                    581: it will obviously not render the subsequent sequence.  Even newer
                    582: versions of groff seem to dither on this.
1.4       kristaps  583: .El
                    584: .\" SECTION
1.2       kristaps  585: .Sh SEE ALSO
1.19      kristaps  586: .Xr mandoc 1 ,
                    587: .Xr mandoc_char 7
1.2       kristaps  588: .\" SECTION
                    589: .Sh AUTHORS
                    590: The
                    591: .Nm
                    592: utility was written by
1.24      kristaps  593: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.5       kristaps  594: .\" SECTION
                    595: .Sh CAVEATS
1.28      kristaps  596: There are many ambiguous parts of mdoc.
1.5       kristaps  597: .Pp
                    598: .Bl -dash -compact
                    599: .\" LIST-ITEM
                    600: .It
1.16      kristaps  601: .Sq \&.Fa
1.5       kristaps  602: should be
1.16      kristaps  603: .Sq \&.Va
1.5       kristaps  604: as function arguments are variables.
                    605: .\" LIST-ITEM
                    606: .It
1.16      kristaps  607: .Sq \&.Ft
1.5       kristaps  608: should be
1.16      kristaps  609: .Sq \&.Vt
1.5       kristaps  610: as function return types are still types.  Furthermore, the
1.16      kristaps  611: .Sq \&.Ft
1.5       kristaps  612: should be removed and
1.16      kristaps  613: .Sq \&.Fo ,
1.5       kristaps  614: which ostensibly follows it, should follow the same convention as
1.16      kristaps  615: .Sq \&.Va .
1.5       kristaps  616: .\" LIST-ITEM
                    617: .It
1.16      kristaps  618: .Sq \&.Va
1.5       kristaps  619: should formalise that only one or two arguments are acceptable: a
1.21      kristaps  620: variable name and optional, preceding type.
1.5       kristaps  621: .\" LIST-ITEM
                    622: .It
1.16      kristaps  623: .Sq \&.Fd
1.5       kristaps  624: is ambiguous.  It's commonly used to indicate an include file in the
                    625: synopsis section.
1.16      kristaps  626: .Sq \&.In
1.5       kristaps  627: should be used, instead.
                    628: .\" LIST-ITEM
                    629: .It
                    630: Only the
                    631: .Sq \-literal
                    632: argument to
1.16      kristaps  633: .Sq \&.Bd
1.5       kristaps  634: makes sense.  The remaining ones should be removed.
                    635: .\" LIST-ITEM
                    636: .It
                    637: The
1.16      kristaps  638: .Sq \&.Xo
1.5       kristaps  639: and
1.16      kristaps  640: .Sq \&.Xc
1.5       kristaps  641: macros should be deprecated.
                    642: .\" LIST-ITEM
                    643: .It
                    644: The
1.16      kristaps  645: .Sq \&.Dt
1.5       kristaps  646: macro lacks clarity.  It should be absolutely clear which title will
                    647: render when formatting the manual page.
1.6       kristaps  648: .\" LIST-ITEM
                    649: .It
                    650: A
1.16      kristaps  651: .Sq \&.Lx
1.6       kristaps  652: should be provided for Linux (\(`a la
1.16      kristaps  653: .Sq \&.Ox ,
                    654: .Sq \&.Nx
1.6       kristaps  655: etc.).
1.14      kristaps  656: .\" LIST-ITEM
                    657: .It
                    658: There's no way to refer to references in
1.16      kristaps  659: .Sq \&.Rs/.Re
1.14      kristaps  660: blocks.
1.31      kristaps  661: .\" LIST-ITEM
                    662: .It
                    663: The \-split and \-nosplit arguments to
                    664: .Sq \&.An
                    665: are inane.
1.38      kristaps  666: .\" LIST-ITEM
                    667: .It
                    668: The end-of-line whitespace warnings are superfluous holdovers from
                    669: historic groff.
1.5       kristaps  670: .El

CVSweb