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

Annotation of mandoc/mdoc.7, Revision 1.55

1.55    ! kristaps    1: .\"    $Id: mdoc.7,v 1.54 2009/07/27 12:35:54 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.50      kristaps   16: .\"
1.1       kristaps   17: .Dd $Mdocdate$
1.20      kristaps   18: .Dt MDOC 7
1.1       kristaps   19: .Os
1.43      kristaps   20: .\" SECTION---------------------------------------------
1.1       kristaps   21: .Sh NAME
                     22: .Nm mdoc
1.15      kristaps   23: .Nd mdoc language reference
1.43      kristaps   24: .\" SECTION---------------------------------------------
1.1       kristaps   25: .Sh DESCRIPTION
                     26: The
                     27: .Nm mdoc
1.50      kristaps   28: language is used to format
                     29: .Bx
1.1       kristaps   30: .Ux
1.43      kristaps   31: manuals.  In this reference document, we describe its syntax, structure,
                     32: and usage.  Our reference implementation is
1.28      kristaps   33: .Xr mandoc 1 .
                     34: The
                     35: .Sx COMPATIBILITY
1.50      kristaps   36: section describes compatibility with
1.28      kristaps   37: .Xr groff 1 .
1.43      kristaps   38: .\" PARAGRAPH------------
1.13      kristaps   39: .Pp
                     40: An
1.1       kristaps   41: .Nm
                     42: document follows simple rules:  lines beginning with the control
1.50      kristaps   43: character
1.1       kristaps   44: .Sq \.
                     45: are parsed for macros.  Other lines are interpreted within the scope of
1.13      kristaps   46: prior macros:
1.39      kristaps   47: .Bd -literal -offset indent
1.13      kristaps   48: \&.Sh Macro lines change control state.
                     49: Other lines are interpreted within the current state.
                     50: .Ed
1.43      kristaps   51: .\" SECTION---------------------------------------------
1.46      kristaps   52: .Sh LANGUAGE SYNTAX
1.1       kristaps   53: .Nm
1.13      kristaps   54: documents may contain only graphable 7-bit ASCII characters, the space
1.43      kristaps   55: character, and, in certain circumstances, the tab character.  All
                     56: manuals must have
                     57: .Ux
1.50      kristaps   58: line terminators.
1.43      kristaps   59: .\" SUB-SECTION----------------------
1.29      kristaps   60: .Ss Comments
1.43      kristaps   61: Text following a
                     62: .Sq \e" ,
                     63: whether in a macro or free-form text line, is ignored to the end of
                     64: line.  A macro line with only a control character and comment escape,
                     65: .Sq \&.\e" ,
                     66: is also ignored.
                     67: .\" SUB-SECTION----------------------
1.2       kristaps   68: .Ss Reserved Characters
                     69: Within a macro line, the following characters are reserved:
1.39      kristaps   70: .Bl -tag -width Ds -offset indent -compact
1.1       kristaps   71: .It \&.
1.2       kristaps   72: .Pq period
1.1       kristaps   73: .It \&,
1.2       kristaps   74: .Pq comma
1.1       kristaps   75: .It \&:
1.2       kristaps   76: .Pq colon
1.1       kristaps   77: .It \&;
1.2       kristaps   78: .Pq semicolon
1.1       kristaps   79: .It \&(
1.2       kristaps   80: .Pq left-parenthesis
1.1       kristaps   81: .It \&)
1.2       kristaps   82: .Pq right-parenthesis
1.1       kristaps   83: .It \&[
1.2       kristaps   84: .Pq left-bracket
1.1       kristaps   85: .It \&]
1.2       kristaps   86: .Pq right-bracket
1.1       kristaps   87: .It \&?
1.2       kristaps   88: .Pq question
1.1       kristaps   89: .It \&!
1.50      kristaps   90: .Pq exclamation
1.28      kristaps   91: .It \&|
1.50      kristaps   92: .Pq vertical bar
1.1       kristaps   93: .El
1.43      kristaps   94: .\" PARAGRAPH------------
1.1       kristaps   95: .Pp
1.5       kristaps   96: Use of reserved characters is described in
1.43      kristaps   97: .Sx MACRO SYNTAX .
                     98: For general use in macro lines, these characters must either be escaped
                     99: with a non-breaking space
1.1       kristaps  100: .Pq Sq \e&
1.50      kristaps  101: or, if applicable, an appropriate escape sequence used.
1.43      kristaps  102: .\" SUB-SECTION----------------------
1.1       kristaps  103: .Ss Special Characters
1.43      kristaps  104: Special characters may occur in both macro and free-form lines.
                    105: Sequences begin with the escape character
1.16      kristaps  106: .Sq \e
1.50      kristaps  107: followed by either an open-parenthesis
1.1       kristaps  108: .Sq \&(
                    109: for two-character sequences; an open-bracket
                    110: .Sq \&[
                    111: for n-character sequences (terminated at a close-bracket
                    112: .Sq \&] ) ;
1.43      kristaps  113: or a single one-character sequence.  See
1.54      kristaps  114: .Xr mandoc_char 7
1.50      kristaps  115: for a complete list.  Examples include
                    116: .Sq \e(em
                    117: .Pq em-dash
                    118: and
1.43      kristaps  119: .Sq \ee
                    120: .Pq back-slash .
1.54      kristaps  121: .\" SUB-SECTION----------------------
                    122: .Ss Text Decoration
                    123: Terms may be text-decorated using the
1.35      kristaps  124: .Sq \ef
1.43      kristaps  125: escape followed by an indicator: B (bold), I, (italic), or P and R
1.54      kristaps  126: (Roman, or reset).  This form is not recommended for
                    127: .Nm ,
                    128: which encourages semantic, not presentation, annotation.
                    129: .\" SUB-SECTION----------------------
                    130: .Ss Predefined Strings
                    131: Historically,
                    132: .Xr groff 1
                    133: also defined a set of package-specific
                    134: .Dq predefined strings ,
                    135: which, like
                    136: .Sx Special Characters ,
                    137: demark special output characters and strings by way of input codes.
                    138: Predefined strings are escaped with the slash-asterisk,
                    139: .Sq \e* :
                    140: single-character
                    141: .Sq \e*X ,
                    142: two-character
                    143: .Sq \e*(XX ,
                    144: and N-character
                    145: .Sq \e*[N] .
                    146: See
                    147: .Xr mandoc_char 7
                    148: for a complete list.  Examples include
                    149: .Sq \e*(Am
                    150: .Pq ampersand
                    151: and
                    152: .Sq \e*(Ba
                    153: .Pq vertical bar .
1.43      kristaps  154: .\" SUB-SECTION----------------------
1.34      kristaps  155: .Ss Whitespace
1.46      kristaps  156: In non-literal free-form lines, consecutive blocks of whitespace are
                    157: pruned from input and added later in the output filter, if applicable:
                    158: .Bd -literal -offset indent
                    159: These     spaces   are    pruned       from    input.
1.50      kristaps  160: \&.Bd \-literal
1.46      kristaps  161: These         are              not.
                    162: \&.Ed
                    163: .Ed
                    164: .\" PARAGRAPH------------
                    165: .Pp
                    166: In macro lines, whitespace delimits arguments and is discarded.  If
1.47      kristaps  167: arguments are quoted, whitespace within the quotes is retained.
1.43      kristaps  168: .\" PARAGRAPH------------
                    169: .Pp
1.46      kristaps  170: Blank lines are only permitted within literal contexts, as are lines
                    171: containing only whitespace.  Tab characters are only acceptable when
1.50      kristaps  172: delimiting
1.43      kristaps  173: .Sq \&Bl \-column
1.46      kristaps  174: or when in a literal context.
                    175: .\" SUB-SECTION----------------------
                    176: .Ss Quotation
                    177: Macro arguments may be quoted with a double-quote to group
                    178: space-delimited terms or to retain blocks of whitespace.  A quoted
                    179: argument begins with a double-quote preceded by whitespace.  The next
1.48      kristaps  180: double-quote not pair-wise adjacent to another double-quote terminates
1.50      kristaps  181: the literal, regardless of surrounding whitespace.
1.47      kristaps  182: .\" PARAGRAPH------------
                    183: .Pp
1.50      kristaps  184: This produces tokens
1.47      kristaps  185: .Sq a" ,
                    186: .Sq b c ,
                    187: .Sq de ,
                    188: and
                    189: .Sq fg" .
                    190: Note that any quoted term, be it argument or macro, is indiscriminately
1.50      kristaps  191: considered literal text.  Thus, the following produces
1.47      kristaps  192: .Sq \&Em a :
                    193: .Bd -literal -offset indent
                    194: \&.Em "Em a"
                    195: .Ed
1.46      kristaps  196: .\" PARAGRAPH------------
                    197: .Pp
                    198: In free-form mode, quotes are regarded as opaque text.
1.43      kristaps  199: .\" SECTION---------------------------------------------
                    200: .Sh MANUAL STRUCTURE
1.33      kristaps  201: Each
                    202: .Nm
1.50      kristaps  203: document must begin with a document prologue, containing, in order,
1.43      kristaps  204: .Sq \&Dd ,
                    205: .Sq \&Dt ,
1.33      kristaps  206: and
1.46      kristaps  207: .Sq \&Os ,
                    208: then the NAME section containing at least one
                    209: .Sq \&Nm
1.50      kristaps  210: followed by
1.46      kristaps  211: .Sq \&Nd :
1.43      kristaps  212: .Bd -literal -offset indent
                    213: \&.Dd $\&Mdocdate$
                    214: \&.Dt mdoc 7
                    215: \&.Os
                    216: \&.Sh NAME
                    217: \&.Nm mdoc
                    218: \&.Nd mdoc language reference
                    219: .Ed
                    220: .\" PARAGRAPH------------
                    221: .Pp
                    222: Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
1.50      kristaps  223: but non-compulsory.
1.43      kristaps  224: .\" SECTION---------------------------------------------
                    225: .Sh MACRO SYNTAX
1.50      kristaps  226: Every line beginning with the control character
1.43      kristaps  227: .Sq \.
1.46      kristaps  228: is processed for macros, two- or three-character sequences.
1.43      kristaps  229: .\" PARAGRAPH------------
1.4       kristaps  230: .Pp
1.46      kristaps  231: The syntax of a macro depends on its classification.  In this section,
1.50      kristaps  232: .Sq \-arg
1.43      kristaps  233: refers to macro arguments, which may be followed by zero or more
                    234: .Sq parm
                    235: parameters;
                    236: .Sq \&Yo
                    237: opens the scope of a macro; and if specified,
                    238: .Sq \&Yc
                    239: closes it out.
                    240: .\" PARAGRAPH------------
1.2       kristaps  241: .Pp
1.43      kristaps  242: The
                    243: .Em Callable
                    244: column indicates that the macro may be called subsequent to the initial
1.55    ! kristaps  245: line-macro.  If a macro is not callable, then its invocation after the
        !           246: initial line macro is interpreted as opaque text, such that
        !           247: .Sq \&.Fl Sh
        !           248: produces
        !           249: .Sq Fl Sh .
        !           250: .\" PARAGRAPH------------
        !           251: .Pp
        !           252: The
1.46      kristaps  253: .Em Parsable
1.43      kristaps  254: column indicates whether the macro may be followed by further
1.55    ! kristaps  255: (ostensibly callable) macros.  If a macro is not parsable, subsequent
        !           256: macro invocations on the line will be interpreted as opaque text.
        !           257: .\" PARAGRAPH------------
        !           258: .Pp
        !           259: The
1.43      kristaps  260: .Em Scope
                    261: column, if applicable, describes closure rules.
                    262: .\" SUB-SECTION----------------------
                    263: .Ss Block full-explicit
                    264: Multi-line scope closed by an explicit closing macro.  All macros
                    265: contains bodies; only
                    266: .Pq Sq \&Bf
                    267: contains a head.
1.39      kristaps  268: .Bd -literal -offset indent
1.50      kristaps  269: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
                    270: \(lBbody...\(rB
1.43      kristaps  271: \&.Yc
1.2       kristaps  272: .Ed
1.43      kristaps  273: .\" PARAGRAPH------------
1.2       kristaps  274: .Pp
1.43      kristaps  275: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
                    276: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    277: .It \&Bd     Ta    \&No     Ta    \&No     Ta    closed by \&Ed
1.44      kristaps  278: .It \&Bf     Ta    \&No     Ta    \&No     Ta    closed by \&Ef
                    279: .It \&Bk     Ta    \&No     Ta    \&No     Ta    closed by \&Ek
                    280: .It \&Bl     Ta    \&No     Ta    \&No     Ta    closed by \&El
1.43      kristaps  281: .It \&Ed     Ta    \&No     Ta    \&No     Ta    opened by \&Bd
                    282: .It \&Ef     Ta    \&No     Ta    \&No     Ta    opened by \&Bf
                    283: .It \&Ek     Ta    \&No     Ta    \&No     Ta    opened by \&Bk
1.44      kristaps  284: .It \&El     Ta    \&No     Ta    \&No     Ta    opened by \&Bl
1.43      kristaps  285: .El
                    286: .\" SUB-SECTION----------------------
                    287: .Ss Block full-implicit
                    288: Multi-line scope closed by end-of-file or implicitly by another macro.
1.50      kristaps  289: All macros have bodies; some
1.43      kristaps  290: .Po
1.50      kristaps  291: .Sq \&It \-bullet ,
                    292: .Sq \-hyphen ,
1.43      kristaps  293: .Sq \-dash ,
                    294: .Sq \-enum ,
1.50      kristaps  295: .Sq \-item
1.43      kristaps  296: .Pc
1.50      kristaps  297: don't have heads, while
1.43      kristaps  298: .Sq \&It \-column
                    299: may have multiple heads.
1.39      kristaps  300: .Bd -literal -offset indent
1.50      kristaps  301: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
                    302: \(lBbody...\(rB
1.2       kristaps  303: .Ed
1.43      kristaps  304: .\" PARAGRAPH------------
1.2       kristaps  305: .Pp
1.43      kristaps  306: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
                    307: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.44      kristaps  308: .It \&It     Ta    \&No     Ta    Yes      Ta    closed by \&It, \&El
1.43      kristaps  309: .It \&Nd     Ta    \&No     Ta    \&No     Ta    closed by \&Sh
                    310: .It \&Sh     Ta    \&No     Ta    \&No     Ta    closed by \&Sh
                    311: .It \&Ss     Ta    \&No     Ta    \&No     Ta    closed by \&Sh, \&Ss
                    312: .El
                    313: .\" SUB-SECTION----------------------
                    314: .Ss Block partial-explicit
                    315: Like block full-explicit, but also with single-line scope.  Each
1.50      kristaps  316: has at least a body and, in limited circumstances, a head
1.43      kristaps  317: .Pq So \&Fo Sc , So \&Eo Sc
1.50      kristaps  318: and/or tail
1.43      kristaps  319: .Pq So \&Ec Sc .
1.39      kristaps  320: .Bd -literal -offset indent
1.50      kristaps  321: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
                    322: \(lBbody...\(rB
                    323: \&.Yc \(lBtail...\(rB
1.2       kristaps  324:
1.43      kristaps  325: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
1.50      kristaps  326: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2       kristaps  327: .Ed
1.43      kristaps  328: .\" PARAGRAPH------------
1.2       kristaps  329: .Pp
1.43      kristaps  330: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
1.1       kristaps  331: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.44      kristaps  332: .It \&Ac     Ta    Yes      Ta    Yes      Ta    opened by \&Ao
1.43      kristaps  333: .It \&Ao     Ta    Yes      Ta    Yes      Ta    closed by \&Ac
                    334: .It \&Bc     Ta    Yes      Ta    Yes      Ta    closed by \&Bo
                    335: .It \&Bo     Ta    Yes      Ta    Yes      Ta    opened by \&Bc
1.44      kristaps  336: .It \&Brc    Ta    Yes      Ta    Yes      Ta    opened by \&Bro
                    337: .It \&Bro    Ta    Yes      Ta    Yes      Ta    closed by \&Brc
                    338: .It \&Dc     Ta    Yes      Ta    Yes      Ta    opened by \&Do
1.43      kristaps  339: .It \&Do     Ta    Yes      Ta    Yes      Ta    closed by \&Dc
1.44      kristaps  340: .It \&Ec     Ta    Yes      Ta    Yes      Ta    opened by \&Eo
                    341: .It \&Eo     Ta    Yes      Ta    Yes      Ta    closed by \&Ec
                    342: .It \&Fc     Ta    Yes      Ta    Yes      Ta    opened by \&Fo
                    343: .It \&Fo     Ta    \&No     Ta    \&No     Ta    closed by \&Fc
1.43      kristaps  344: .It \&Oc     Ta    Yes      Ta    Yes      Ta    closed by \&Oo
                    345: .It \&Oo     Ta    Yes      Ta    Yes      Ta    opened by \&Oc
1.44      kristaps  346: .It \&Pc     Ta    Yes      Ta    Yes      Ta    closed by \&Po
                    347: .It \&Po     Ta    Yes      Ta    Yes      Ta    opened by \&Pc
1.43      kristaps  348: .It \&Qc     Ta    Yes      Ta    Yes      Ta    opened by \&Oo
                    349: .It \&Qo     Ta    Yes      Ta    Yes      Ta    closed by \&Oc
                    350: .It \&Re     Ta    \&No     Ta    \&No     Ta    opened by \&Rs
                    351: .It \&Rs     Ta    \&No     Ta    \&No     Ta    closed by \&Re
1.44      kristaps  352: .It \&Sc     Ta    Yes      Ta    Yes      Ta    opened by \&So
                    353: .It \&So     Ta    Yes      Ta    Yes      Ta    closed by \&Sc
                    354: .It \&Xc     Ta    Yes      Ta    Yes      Ta    opened by \&Xo
                    355: .It \&Xo     Ta    Yes      Ta    Yes      Ta    closed by \&Xc
1.1       kristaps  356: .El
1.43      kristaps  357: .\" SUB-SECTION----------------------
1.1       kristaps  358: .Ss Block partial-implicit
1.50      kristaps  359: Like block full-implicit, but with single-line scope closed by
                    360: .Sx Reserved Characters
1.43      kristaps  361: or end of line.
                    362: .Bd -literal -offset indent
                    363: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
                    364: .Ed
                    365: .\" PARAGRAPH------------
1.1       kristaps  366: .Pp
1.39      kristaps  367: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
1.1       kristaps  368: .It Em Macro Ta Em Callable Ta Em Parsable
1.43      kristaps  369: .It \&Aq     Ta    Yes      Ta    Yes
                    370: .It \&Bq     Ta    Yes      Ta    Yes
1.44      kristaps  371: .It \&Brq    Ta    Yes      Ta    Yes
                    372: .It \&D1     Ta    \&No     Ta    \&Yes
                    373: .It \&Dl     Ta    \&No     Ta    Yes
1.43      kristaps  374: .It \&Dq     Ta    Yes      Ta    Yes
1.44      kristaps  375: .It \&Op     Ta    Yes      Ta    Yes
1.43      kristaps  376: .It \&Pq     Ta    Yes      Ta    Yes
1.44      kristaps  377: .It \&Ql     Ta    Yes      Ta    Yes
1.43      kristaps  378: .It \&Qq     Ta    Yes      Ta    Yes
                    379: .It \&Sq     Ta    Yes      Ta    Yes
                    380: .El
                    381: .\" SUB-SECTION----------------------
                    382: .Ss In-line
1.50      kristaps  383: Closed by
1.43      kristaps  384: .Sx Reserved Characters ,
                    385: end of line, fixed argument lengths, and/or subsequent macros.  In-line
                    386: macros have only text children.  If a number (or inequality) of
1.3       kristaps  387: arguments is
1.50      kristaps  388: .Pq n ,
1.3       kristaps  389: then the macro accepts an arbitrary number of arguments.
1.43      kristaps  390: .Bd -literal -offset indent
                    391: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
                    392:
                    393: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
                    394:
                    395: \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
                    396: .Ed
                    397: .\" PARAGRAPH------------
1.2       kristaps  398: .Pp
1.39      kristaps  399: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
1.2       kristaps  400: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.43      kristaps  401: .It \&%A     Ta    \&No     Ta    \&No     Ta    >0
                    402: .It \&%B     Ta    \&No     Ta    \&No     Ta    >0
                    403: .It \&%C     Ta    \&No     Ta    \&No     Ta    >0
                    404: .It \&%D     Ta    \&No     Ta    \&No     Ta    >0
                    405: .It \&%I     Ta    \&No     Ta    \&No     Ta    >0
                    406: .It \&%J     Ta    \&No     Ta    \&No     Ta    >0
                    407: .It \&%N     Ta    \&No     Ta    \&No     Ta    >0
                    408: .It \&%O     Ta    \&No     Ta    \&No     Ta    >0
                    409: .It \&%P     Ta    \&No     Ta    \&No     Ta    >0
                    410: .It \&%R     Ta    \&No     Ta    \&No     Ta    >0
                    411: .It \&%T     Ta    \&No     Ta    \&No     Ta    >0
                    412: .It \&%V     Ta    \&No     Ta    \&No     Ta    >0
1.44      kristaps  413: .It \&Ad     Ta    Yes      Ta    Yes      Ta    n
                    414: .It \&An     Ta    Yes      Ta    Yes      Ta    n
                    415: .It \&Ap     Ta    Yes      Ta    Yes      Ta    0
                    416: .It \&Ar     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  417: .It \&At     Ta    Yes      Ta    Yes      Ta    1
                    418: .It \&Bsx    Ta    Yes      Ta    Yes      Ta    n
1.44      kristaps  419: .It \&Bt     Ta    \&No     Ta    \&No     Ta    0
1.43      kristaps  420: .It \&Bx     Ta    Yes      Ta    Yes      Ta    n
1.49      kristaps  421: .It \&Cd     Ta    Yes      Ta    Yes      Ta    >0
1.44      kristaps  422: .It \&Cm     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  423: .It \&Db     Ta    \&No     Ta    \&No     Ta    1
1.44      kristaps  424: .It \&Dd     Ta    \&No     Ta    \&No     Ta    >0
                    425: .It \&Dt     Ta    \&No     Ta    \&No     Ta    n
                    426: .It \&Dv     Ta    Yes      Ta    Yes      Ta    n
                    427: .It \&Dx     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  428: .It \&Em     Ta    Yes      Ta    Yes      Ta    >0
1.44      kristaps  429: .It \&En     Ta    \&No     Ta    \&No     Ta    0
                    430: .It \&Er     Ta    Yes      Ta    Yes      Ta    >0
                    431: .It \&Es     Ta    \&No     Ta    \&No     Ta    0
                    432: .It \&Ev     Ta    Yes      Ta    Yes      Ta    n
                    433: .It \&Ex     Ta    \&No     Ta    \&No     Ta    0
                    434: .It \&Fa     Ta    Yes      Ta    Yes      Ta    n
                    435: .It \&Fd     Ta    \&No     Ta    \&No     Ta    >0
                    436: .It \&Fl     Ta    Yes      Ta    Yes      Ta    n
                    437: .It \&Fn     Ta    Yes      Ta    Yes      Ta    >0
                    438: .It \&Fr     Ta    \&No     Ta    \&No     Ta    n
                    439: .It \&Ft     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  440: .It \&Fx     Ta    Yes      Ta    Yes      Ta    n
1.44      kristaps  441: .It \&Hf     Ta    \&No     Ta    \&No     Ta    n
                    442: .It \&Ic     Ta    Yes      Ta    Yes      Ta    >0
                    443: .It \&In     Ta    \&No     Ta    \&No     Ta    n
                    444: .It \&Lb     Ta    \&No     Ta    \&No     Ta    1
                    445: .It \&Li     Ta    Yes      Ta    Yes      Ta    n
                    446: .It \&Lk     Ta    Yes      Ta    Yes      Ta    n
                    447: .It \&Lp     Ta    \&No     Ta    \&No     Ta    0
1.43      kristaps  448: .It \&Ms     Ta    Yes      Ta    Yes      Ta    >0
1.44      kristaps  449: .It \&Mt     Ta    Yes      Ta    Yes      Ta    >0
                    450: .It \&Nm     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  451: .It \&No     Ta    Yes      Ta    Yes      Ta    0
                    452: .It \&Ns     Ta    Yes      Ta    Yes      Ta    0
                    453: .It \&Nx     Ta    Yes      Ta    Yes      Ta    n
1.44      kristaps  454: .It \&Os     Ta    \&No     Ta    \&No     Ta    n
                    455: .It \&Ot     Ta    \&No     Ta    \&No     Ta    n
1.43      kristaps  456: .It \&Ox     Ta    Yes      Ta    Yes      Ta    n
1.44      kristaps  457: .It \&Pa     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  458: .It \&Pf     Ta    \&No     Ta    Yes      Ta    1
1.44      kristaps  459: .It \&Pp     Ta    \&No     Ta    \&No     Ta    0
                    460: .It \&Rv     Ta    \&No     Ta    \&No     Ta    0
1.43      kristaps  461: .It \&Sm     Ta    \&No     Ta    \&No     Ta    1
1.44      kristaps  462: .It \&St     Ta    \&No     Ta    Yes      Ta    1
1.43      kristaps  463: .It \&Sx     Ta    Yes      Ta    Yes      Ta    >0
                    464: .It \&Sy     Ta    Yes      Ta    Yes      Ta    >0
                    465: .It \&Tn     Ta    Yes      Ta    Yes      Ta    >0
1.44      kristaps  466: .It \&Ud     Ta    \&No     Ta    \&No     Ta    0
1.43      kristaps  467: .It \&Ux     Ta    Yes      Ta    Yes      Ta    n
1.44      kristaps  468: .It \&Va     Ta    Yes      Ta    Yes      Ta    n
                    469: .It \&Vt     Ta    Yes      Ta    Yes      Ta    >0
                    470: .It \&Xr     Ta    Yes      Ta    Yes      Ta    >0, <3
                    471: .It \&br     Ta    \&No     Ta    \&No     Ta    0
1.45      kristaps  472: .It \&sp     Ta    \&No     Ta    \&No     Ta    1
1.1       kristaps  473: .El
1.43      kristaps  474: .\" SECTION---------------------------------------------
1.4       kristaps  475: .Sh COMPATIBILITY
1.28      kristaps  476: This section documents compatibility with other roff implementations, at
1.50      kristaps  477: this time limited to
1.28      kristaps  478: .Xr groff 1 .
1.50      kristaps  479: The term
1.28      kristaps  480: .Qq historic groff
1.50      kristaps  481: refers to those versions before the
1.28      kristaps  482: .Pa doc.tmac
1.50      kristaps  483: file re-write
1.28      kristaps  484: .Pq somewhere between 1.15 and 1.19 .
1.43      kristaps  485: .\" PARAGRAPH------------
1.4       kristaps  486: .Pp
                    487: .Bl -dash -compact
                    488: .\" LIST-ITEM
                    489: .It
1.51      kristaps  490: The
                    491: .Sq \-split
                    492: or
                    493: .Sq \-nosplit
                    494: argument to
                    495: .Sq \&An
                    496: applies to the whole document, not just to the current section as it
                    497: does in groff.
                    498: .\" LIST-ITEM
                    499: .It
1.48      kristaps  500: In quoted literals, groff allowed pair-wise double-quotes to produce a
                    501: standalone double-quote in formatted output.  This idiosyncratic
                    502: behaviour is no longer applicable.
                    503: .\" LIST-ITEM
                    504: .It
1.50      kristaps  505: The
1.45      kristaps  506: .Sq \&sp
                    507: macro does not accept negative numbers.
                    508: .\" LIST-ITEM
                    509: .It
1.35      kristaps  510: Blocks of whitespace are stripped from both macro and free-form text
                    511: lines (except when in literal mode), while groff would retain whitespace
                    512: in free-form text lines.
                    513: .\" LIST-ITEM
                    514: .It
1.28      kristaps  515: Historic groff has many un-callable macros.  Most of these (excluding
                    516: some block-level macros) are now callable, conforming to the
                    517: non-historic groff version.
                    518: .\" LIST-ITEM
                    519: .It
1.50      kristaps  520: The vertical bar
1.35      kristaps  521: .Sq \(ba
1.28      kristaps  522: made historic groff
                    523: .Qq go orbital
                    524: but is a proper delimiter in this implementation.
1.5       kristaps  525: .\" LIST-ITEM
                    526: .It
1.45      kristaps  527: .Sq \&It \-nested
1.28      kristaps  528: is assumed for all lists (it wasn't in historic groff): any list may be
                    529: nested and
1.4       kristaps  530: .Sq \-enum
                    531: lists will restart the sequence only for the sub-list.
                    532: .\" LIST-ITEM
                    533: .It
1.45      kristaps  534: .Sq \&It \-column
1.21      kristaps  535: syntax where column widths may be preceded by other arguments (instead
1.4       kristaps  536: of proceeded) is not supported.
                    537: .\" LIST-ITEM
                    538: .It
1.50      kristaps  539: The
1.45      kristaps  540: .Sq \&At
1.4       kristaps  541: macro only accepts a single parameter.
                    542: .\" LIST-ITEM
                    543: .It
                    544: Some manuals use
1.45      kristaps  545: .Sq \&Li
1.4       kristaps  546: incorrectly by following it with a reserved character and expecting the
                    547: delimiter to render.  This is not supported.
                    548: .\" LIST-ITEM
                    549: .It
1.50      kristaps  550: In groff, the
1.45      kristaps  551: .Sq \&Fo
1.41      kristaps  552: macro only produces the first parameter.  This is no longer the case.
1.4       kristaps  553: .El
1.43      kristaps  554: .\" SECTION---------------------------------------------
1.2       kristaps  555: .Sh SEE ALSO
1.19      kristaps  556: .Xr mandoc 1 ,
                    557: .Xr mandoc_char 7
1.43      kristaps  558: .\" SECTION---------------------------------------------
1.2       kristaps  559: .Sh AUTHORS
                    560: The
                    561: .Nm
1.50      kristaps  562: reference was written by
1.24      kristaps  563: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.43      kristaps  564: .\" SECTION---------------------------------------------
1.5       kristaps  565: .Sh CAVEATS
1.28      kristaps  566: There are many ambiguous parts of mdoc.
1.43      kristaps  567: .\" PARAGRAPH------------
1.5       kristaps  568: .Pp
                    569: .Bl -dash -compact
                    570: .\" LIST-ITEM
                    571: .It
1.45      kristaps  572: .Sq \&Fa
1.50      kristaps  573: should be
1.45      kristaps  574: .Sq \&Va
1.5       kristaps  575: as function arguments are variables.
                    576: .\" LIST-ITEM
                    577: .It
1.45      kristaps  578: .Sq \&Ft
1.5       kristaps  579: should be
1.45      kristaps  580: .Sq \&Vt
1.5       kristaps  581: as function return types are still types.  Furthermore, the
1.45      kristaps  582: .Sq \&Ft
1.5       kristaps  583: should be removed and
1.45      kristaps  584: .Sq \&Fo ,
1.5       kristaps  585: which ostensibly follows it, should follow the same convention as
1.45      kristaps  586: .Sq \&Va .
1.5       kristaps  587: .\" LIST-ITEM
                    588: .It
1.45      kristaps  589: .Sq \&Va
1.5       kristaps  590: should formalise that only one or two arguments are acceptable: a
1.21      kristaps  591: variable name and optional, preceding type.
1.5       kristaps  592: .\" LIST-ITEM
                    593: .It
1.45      kristaps  594: .Sq \&Fd
1.5       kristaps  595: is ambiguous.  It's commonly used to indicate an include file in the
1.50      kristaps  596: synopsis section.
1.45      kristaps  597: .Sq \&In
1.5       kristaps  598: should be used, instead.
                    599: .\" LIST-ITEM
                    600: .It
                    601: Only the
                    602: .Sq \-literal
                    603: argument to
1.45      kristaps  604: .Sq \&Bd
1.5       kristaps  605: makes sense.  The remaining ones should be removed.
                    606: .\" LIST-ITEM
                    607: .It
1.50      kristaps  608: The
1.45      kristaps  609: .Sq \&Xo
1.5       kristaps  610: and
1.45      kristaps  611: .Sq \&Xc
1.5       kristaps  612: macros should be deprecated.
                    613: .\" LIST-ITEM
                    614: .It
                    615: The
1.45      kristaps  616: .Sq \&Dt
1.5       kristaps  617: macro lacks clarity.  It should be absolutely clear which title will
                    618: render when formatting the manual page.
1.6       kristaps  619: .\" LIST-ITEM
                    620: .It
                    621: A
1.45      kristaps  622: .Sq \&Lx
1.50      kristaps  623: should be provided for Linux (\(`a la
1.45      kristaps  624: .Sq \&Ox ,
1.50      kristaps  625: .Sq \&Nx
1.6       kristaps  626: etc.).
1.14      kristaps  627: .\" LIST-ITEM
                    628: .It
                    629: There's no way to refer to references in
1.45      kristaps  630: .Sq \&Rs/Re
1.14      kristaps  631: blocks.
1.31      kristaps  632: .\" LIST-ITEM
                    633: .It
1.54      kristaps  634: The \-split and \-nosplit dictates via
1.45      kristaps  635: .Sq \&An
1.54      kristaps  636: are re-set when entering and leaving the AUTHORS section.
1.5       kristaps  637: .El

CVSweb