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

Annotation of mandoc/mdoc.7, Revision 1.44

1.44    ! kristaps    1: .\"    $Id: mdoc.7,v 1.43 2009/07/14 15:57:08 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
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
                     28: language is used to format
                     29: .Bx
                     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
                     36: section describes compatibility with
                     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.13      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.13      kristaps   52: .Sh INPUT ENCODING
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.10      kristaps   58: line termination.
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.5       kristaps   90: .Pq exclamation
1.28      kristaps   91: .It \&|
                     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.43      kristaps  101: or, if applicable, an appropriate escape sequence used.
                    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.4       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
                    114: .Xr mandoc_char 1
                    115: for a complete list.  Examples include
                    116: .Sq \e(em
                    117: .Pq em-dash
                    118: and
                    119: .Sq \ee
                    120: .Pq back-slash .
                    121: .\" PARAGRAPH------------
1.1       kristaps  122: .Pp
1.43      kristaps  123: An alternative escape sequence is
                    124: the slash-asterisk,
1.16      kristaps  125: .Sq \e* ,
1.43      kristaps  126: but this method is discouraged for compatibility reasons.
                    127: .\" PARAGRAPH------------
1.35      kristaps  128: .Pp
1.43      kristaps  129: Terms may
                    130: also be text-decorated using the
1.35      kristaps  131: .Sq \ef
1.43      kristaps  132: escape followed by an indicator: B (bold), I, (italic), or P and R
                    133: (Roman, or reset).  This form is not recommended.
                    134: .\" SUB-SECTION----------------------
1.34      kristaps  135: .Ss Whitespace
1.43      kristaps  136: In general, consecutive blocks of whitespace are pruned from input.
                    137: These are later re-added, when applicable, by
1.34      kristaps  138: .Xr mandoc 1 .
1.43      kristaps  139: .\" PARAGRAPH------------
                    140: .Pp
                    141: Blank lines are permitted within
                    142: .Sq \&Bd \-literal
                    143: or
                    144: .Sq \&Bd \-unfilled
                    145: contexts.  Tab characters are only acceptable when delimiting
                    146: .Sq \&Bl \-column
                    147: and in
                    148: .Sq \&Bd \-literal
                    149: or
                    150: .Sq \&Bd \-unfilled
                    151: contexts.
                    152: .\" SECTION---------------------------------------------
                    153: .Sh MANUAL STRUCTURE
1.33      kristaps  154: Each
                    155: .Nm
1.43      kristaps  156: document must begin with a document prologue, containing, in order,
                    157: .Sq \&Dd ,
                    158: .Sq \&Dt ,
1.33      kristaps  159: and
1.43      kristaps  160: .Sq \&Os
                    161: (using this manual as an example):
                    162: .Bd -literal -offset indent
                    163: \&.Dd $\&Mdocdate$
                    164: \&.Dt mdoc 7
                    165: \&.Os
                    166: \&.Sh NAME
                    167: \&.Nm mdoc
                    168: \&.Nd mdoc language reference
                    169: .Ed
                    170: .Pp
1.33      kristaps  171: Following these, the document body must begin with the NAME section
                    172: containing at least one
1.43      kristaps  173: .Sq \&Nm
                    174: followed by
                    175: .Sq \&Nd .
                    176: .\" PARAGRAPH------------
                    177: .Pp
                    178: Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
                    179: but non-compulsory.
                    180: .\" SECTION---------------------------------------------
                    181: .Sh MACRO SYNTAX
                    182: Every line beginning with the control character
                    183: .Sq \.
                    184: is processed for macros, two- or three-character semantic annotations.
                    185: .\" PARAGRAPH------------
1.4       kristaps  186: .Pp
1.43      kristaps  187: The syntax of macro depends on its classification.  In this section,
                    188: .Sq \-arg
                    189: refers to macro arguments, which may be followed by zero or more
                    190: .Sq parm
                    191: parameters;
                    192: .Sq \&Yo
                    193: opens the scope of a macro; and if specified,
                    194: .Sq \&Yc
                    195: closes it out.
                    196: .\" PARAGRAPH------------
1.2       kristaps  197: .Pp
1.43      kristaps  198: The
                    199: .Em Callable
                    200: column indicates that the macro may be called subsequent to the initial
                    201: line-macro.  The
                    202: .Qq Parsable
                    203: column indicates whether the macro may be followed by further
                    204: (ostensibly callable) macros.  The
                    205: .Em Scope
                    206: column, if applicable, describes closure rules.
                    207: .\" SUB-SECTION----------------------
                    208: .Ss Block full-explicit
                    209: Multi-line scope closed by an explicit closing macro.  All macros
                    210: contains bodies; only
                    211: .Pq Sq \&Bf
                    212: contains a head.
1.39      kristaps  213: .Bd -literal -offset indent
1.43      kristaps  214: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
1.4       kristaps  215: \(lBbody...\(rB
1.43      kristaps  216: \&.Yc
1.2       kristaps  217: .Ed
1.43      kristaps  218: .\" PARAGRAPH------------
1.2       kristaps  219: .Pp
1.43      kristaps  220: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
                    221: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    222: .It \&Bd     Ta    \&No     Ta    \&No     Ta    closed by \&Ed
1.44    ! kristaps  223: .It \&Bf     Ta    \&No     Ta    \&No     Ta    closed by \&Ef
        !           224: .It \&Bk     Ta    \&No     Ta    \&No     Ta    closed by \&Ek
        !           225: .It \&Bl     Ta    \&No     Ta    \&No     Ta    closed by \&El
1.43      kristaps  226: .It \&Ed     Ta    \&No     Ta    \&No     Ta    opened by \&Bd
                    227: .It \&Ef     Ta    \&No     Ta    \&No     Ta    opened by \&Bf
                    228: .It \&Ek     Ta    \&No     Ta    \&No     Ta    opened by \&Bk
1.44    ! kristaps  229: .It \&El     Ta    \&No     Ta    \&No     Ta    opened by \&Bl
1.43      kristaps  230: .El
                    231: .\" SUB-SECTION----------------------
                    232: .Ss Block full-implicit
                    233: Multi-line scope closed by end-of-file or implicitly by another macro.
                    234: All macros have bodies; some
                    235: .Po
                    236: .Sq \&It \-bullet ,
                    237: .Sq \-hyphen ,
                    238: .Sq \-dash ,
                    239: .Sq \-enum ,
                    240: .Sq \-item
                    241: .Pc
                    242: don't have heads, while
                    243: .Sq \&It \-column
                    244: may have multiple heads.
1.39      kristaps  245: .Bd -literal -offset indent
1.43      kristaps  246: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
1.4       kristaps  247: \(lBbody...\(rB
1.2       kristaps  248: .Ed
1.43      kristaps  249: .\" PARAGRAPH------------
1.2       kristaps  250: .Pp
1.43      kristaps  251: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
                    252: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.44    ! kristaps  253: .It \&It     Ta    \&No     Ta    Yes      Ta    closed by \&It, \&El
1.43      kristaps  254: .It \&Nd     Ta    \&No     Ta    \&No     Ta    closed by \&Sh
                    255: .It \&Sh     Ta    \&No     Ta    \&No     Ta    closed by \&Sh
                    256: .It \&Ss     Ta    \&No     Ta    \&No     Ta    closed by \&Sh, \&Ss
                    257: .El
                    258: .\" SUB-SECTION----------------------
                    259: .Ss Block partial-explicit
                    260: Like block full-explicit, but also with single-line scope.  Each
                    261: has at least a body and, in limited circumstances, a head
                    262: .Pq So \&Fo Sc , So \&Eo Sc
                    263: and/or tail
                    264: .Pq So \&Ec Sc .
1.39      kristaps  265: .Bd -literal -offset indent
1.43      kristaps  266: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
1.4       kristaps  267: \(lBbody...\(rB
                    268: \&.Yc \(lBtail...\(rB
1.2       kristaps  269:
1.43      kristaps  270: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
1.4       kristaps  271: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2       kristaps  272: .Ed
1.43      kristaps  273: .\" PARAGRAPH------------
1.2       kristaps  274: .Pp
1.43      kristaps  275: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
1.1       kristaps  276: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.44    ! kristaps  277: .It \&Ac     Ta    Yes      Ta    Yes      Ta    opened by \&Ao
1.43      kristaps  278: .It \&Ao     Ta    Yes      Ta    Yes      Ta    closed by \&Ac
                    279: .It \&Bc     Ta    Yes      Ta    Yes      Ta    closed by \&Bo
                    280: .It \&Bo     Ta    Yes      Ta    Yes      Ta    opened by \&Bc
1.44    ! kristaps  281: .It \&Brc    Ta    Yes      Ta    Yes      Ta    opened by \&Bro
        !           282: .It \&Bro    Ta    Yes      Ta    Yes      Ta    closed by \&Brc
        !           283: .It \&Dc     Ta    Yes      Ta    Yes      Ta    opened by \&Do
1.43      kristaps  284: .It \&Do     Ta    Yes      Ta    Yes      Ta    closed by \&Dc
1.44    ! kristaps  285: .It \&Ec     Ta    Yes      Ta    Yes      Ta    opened by \&Eo
        !           286: .It \&Eo     Ta    Yes      Ta    Yes      Ta    closed by \&Ec
        !           287: .It \&Fc     Ta    Yes      Ta    Yes      Ta    opened by \&Fo
        !           288: .It \&Fo     Ta    \&No     Ta    \&No     Ta    closed by \&Fc
1.43      kristaps  289: .It \&Oc     Ta    Yes      Ta    Yes      Ta    closed by \&Oo
                    290: .It \&Oo     Ta    Yes      Ta    Yes      Ta    opened by \&Oc
1.44    ! kristaps  291: .It \&Pc     Ta    Yes      Ta    Yes      Ta    closed by \&Po
        !           292: .It \&Po     Ta    Yes      Ta    Yes      Ta    opened by \&Pc
1.43      kristaps  293: .It \&Qc     Ta    Yes      Ta    Yes      Ta    opened by \&Oo
                    294: .It \&Qo     Ta    Yes      Ta    Yes      Ta    closed by \&Oc
                    295: .It \&Re     Ta    \&No     Ta    \&No     Ta    opened by \&Rs
                    296: .It \&Rs     Ta    \&No     Ta    \&No     Ta    closed by \&Re
1.44    ! kristaps  297: .It \&Sc     Ta    Yes      Ta    Yes      Ta    opened by \&So
        !           298: .It \&So     Ta    Yes      Ta    Yes      Ta    closed by \&Sc
        !           299: .It \&Xc     Ta    Yes      Ta    Yes      Ta    opened by \&Xo
        !           300: .It \&Xo     Ta    Yes      Ta    Yes      Ta    closed by \&Xc
1.1       kristaps  301: .El
1.43      kristaps  302: .\" SUB-SECTION----------------------
1.1       kristaps  303: .Ss Block partial-implicit
1.43      kristaps  304: Like block full-implicit, but with single-line scope closed by
                    305: .Sx Reserved Characters
                    306: or end of line.
                    307: .Bd -literal -offset indent
                    308: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
                    309: .Ed
                    310: .\" PARAGRAPH------------
1.1       kristaps  311: .Pp
1.39      kristaps  312: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
1.1       kristaps  313: .It Em Macro Ta Em Callable Ta Em Parsable
1.43      kristaps  314: .It \&Aq     Ta    Yes      Ta    Yes
                    315: .It \&Bq     Ta    Yes      Ta    Yes
1.44    ! kristaps  316: .It \&Brq    Ta    Yes      Ta    Yes
        !           317: .It \&D1     Ta    \&No     Ta    \&Yes
        !           318: .It \&Dl     Ta    \&No     Ta    Yes
1.43      kristaps  319: .It \&Dq     Ta    Yes      Ta    Yes
1.44    ! kristaps  320: .It \&Op     Ta    Yes      Ta    Yes
1.43      kristaps  321: .It \&Pq     Ta    Yes      Ta    Yes
1.44    ! kristaps  322: .It \&Ql     Ta    Yes      Ta    Yes
1.43      kristaps  323: .It \&Qq     Ta    Yes      Ta    Yes
                    324: .It \&Sq     Ta    Yes      Ta    Yes
                    325: .El
                    326: .\" SUB-SECTION----------------------
                    327: .Ss In-line
                    328: Closed by
                    329: .Sx Reserved Characters ,
                    330: end of line, fixed argument lengths, and/or subsequent macros.  In-line
                    331: macros have only text children.  If a number (or inequality) of
1.3       kristaps  332: arguments is
                    333: .Pq n ,
                    334: then the macro accepts an arbitrary number of arguments.
1.43      kristaps  335: .Bd -literal -offset indent
                    336: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
                    337:
                    338: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
                    339:
                    340: \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
                    341: .Ed
                    342: .\" PARAGRAPH------------
1.2       kristaps  343: .Pp
1.39      kristaps  344: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
1.2       kristaps  345: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.43      kristaps  346: .It \&%A     Ta    \&No     Ta    \&No     Ta    >0
                    347: .It \&%B     Ta    \&No     Ta    \&No     Ta    >0
                    348: .It \&%C     Ta    \&No     Ta    \&No     Ta    >0
                    349: .It \&%D     Ta    \&No     Ta    \&No     Ta    >0
                    350: .It \&%I     Ta    \&No     Ta    \&No     Ta    >0
                    351: .It \&%J     Ta    \&No     Ta    \&No     Ta    >0
                    352: .It \&%N     Ta    \&No     Ta    \&No     Ta    >0
                    353: .It \&%O     Ta    \&No     Ta    \&No     Ta    >0
                    354: .It \&%P     Ta    \&No     Ta    \&No     Ta    >0
                    355: .It \&%R     Ta    \&No     Ta    \&No     Ta    >0
                    356: .It \&%T     Ta    \&No     Ta    \&No     Ta    >0
                    357: .It \&%V     Ta    \&No     Ta    \&No     Ta    >0
1.44    ! kristaps  358: .It \&Ad     Ta    Yes      Ta    Yes      Ta    n
        !           359: .It \&An     Ta    Yes      Ta    Yes      Ta    n
        !           360: .It \&Ap     Ta    Yes      Ta    Yes      Ta    0
        !           361: .It \&Ar     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  362: .It \&At     Ta    Yes      Ta    Yes      Ta    1
                    363: .It \&Bsx    Ta    Yes      Ta    Yes      Ta    n
1.44    ! kristaps  364: .It \&Bt     Ta    \&No     Ta    \&No     Ta    0
1.43      kristaps  365: .It \&Bx     Ta    Yes      Ta    Yes      Ta    n
1.44    ! kristaps  366: .It \&Cd     Ta    Yes      Ta    \&No     Ta    >0
        !           367: .It \&Cm     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  368: .It \&Db     Ta    \&No     Ta    \&No     Ta    1
1.44    ! kristaps  369: .It \&Dd     Ta    \&No     Ta    \&No     Ta    >0
        !           370: .It \&Dt     Ta    \&No     Ta    \&No     Ta    n
        !           371: .It \&Dv     Ta    Yes      Ta    Yes      Ta    n
        !           372: .It \&Dx     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  373: .It \&Em     Ta    Yes      Ta    Yes      Ta    >0
1.44    ! kristaps  374: .It \&En     Ta    \&No     Ta    \&No     Ta    0
        !           375: .It \&Er     Ta    Yes      Ta    Yes      Ta    >0
        !           376: .It \&Es     Ta    \&No     Ta    \&No     Ta    0
        !           377: .It \&Ev     Ta    Yes      Ta    Yes      Ta    n
        !           378: .It \&Ex     Ta    \&No     Ta    \&No     Ta    0
        !           379: .It \&Fa     Ta    Yes      Ta    Yes      Ta    n
        !           380: .It \&Fd     Ta    \&No     Ta    \&No     Ta    >0
        !           381: .It \&Fl     Ta    Yes      Ta    Yes      Ta    n
        !           382: .It \&Fn     Ta    Yes      Ta    Yes      Ta    >0
        !           383: .It \&Fr     Ta    \&No     Ta    \&No     Ta    n
        !           384: .It \&Ft     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  385: .It \&Fx     Ta    Yes      Ta    Yes      Ta    n
1.44    ! kristaps  386: .It \&Hf     Ta    \&No     Ta    \&No     Ta    n
        !           387: .It \&Ic     Ta    Yes      Ta    Yes      Ta    >0
        !           388: .It \&In     Ta    \&No     Ta    \&No     Ta    n
        !           389: .It \&Lb     Ta    \&No     Ta    \&No     Ta    1
        !           390: .It \&Li     Ta    Yes      Ta    Yes      Ta    n
        !           391: .It \&Lk     Ta    Yes      Ta    Yes      Ta    n
        !           392: .It \&Lp     Ta    \&No     Ta    \&No     Ta    0
1.43      kristaps  393: .It \&Ms     Ta    Yes      Ta    Yes      Ta    >0
1.44    ! kristaps  394: .It \&Mt     Ta    Yes      Ta    Yes      Ta    >0
        !           395: .It \&Nm     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  396: .It \&No     Ta    Yes      Ta    Yes      Ta    0
                    397: .It \&Ns     Ta    Yes      Ta    Yes      Ta    0
                    398: .It \&Nx     Ta    Yes      Ta    Yes      Ta    n
1.44    ! kristaps  399: .It \&Os     Ta    \&No     Ta    \&No     Ta    n
        !           400: .It \&Ot     Ta    \&No     Ta    \&No     Ta    n
1.43      kristaps  401: .It \&Ox     Ta    Yes      Ta    Yes      Ta    n
1.44    ! kristaps  402: .It \&Pa     Ta    Yes      Ta    Yes      Ta    n
1.43      kristaps  403: .It \&Pf     Ta    \&No     Ta    Yes      Ta    1
1.44    ! kristaps  404: .It \&Pp     Ta    \&No     Ta    \&No     Ta    0
        !           405: .It \&Rv     Ta    \&No     Ta    \&No     Ta    0
1.43      kristaps  406: .It \&Sm     Ta    \&No     Ta    \&No     Ta    1
1.44    ! kristaps  407: .It \&St     Ta    \&No     Ta    Yes      Ta    1
1.43      kristaps  408: .It \&Sx     Ta    Yes      Ta    Yes      Ta    >0
                    409: .It \&Sy     Ta    Yes      Ta    Yes      Ta    >0
                    410: .It \&Tn     Ta    Yes      Ta    Yes      Ta    >0
1.44    ! kristaps  411: .It \&Ud     Ta    \&No     Ta    \&No     Ta    0
1.43      kristaps  412: .It \&Ux     Ta    Yes      Ta    Yes      Ta    n
1.44    ! kristaps  413: .It \&Va     Ta    Yes      Ta    Yes      Ta    n
        !           414: .It \&Vt     Ta    Yes      Ta    Yes      Ta    >0
        !           415: .It \&Xr     Ta    Yes      Ta    Yes      Ta    >0, <3
        !           416: .It \&br     Ta    \&No     Ta    \&No     Ta    0
1.1       kristaps  417: .El
1.43      kristaps  418: .\" SECTION---------------------------------------------
1.4       kristaps  419: .Sh COMPATIBILITY
1.28      kristaps  420: This section documents compatibility with other roff implementations, at
                    421: this time limited to
                    422: .Xr groff 1 .
                    423: The term
                    424: .Qq historic groff
                    425: refers to those versions before the
                    426: .Pa doc.tmac
                    427: file re-write
                    428: .Pq somewhere between 1.15 and 1.19 .
1.43      kristaps  429: .\" PARAGRAPH------------
1.4       kristaps  430: .Pp
                    431: .Bl -dash -compact
                    432: .\" LIST-ITEM
                    433: .It
1.35      kristaps  434: Some character sequences in groff are not handled depending on escape
                    435: style, e.g.,
                    436: .Sq \e(ba
                    437: and
                    438: .Sq \e*(Ba
                    439: may not be interchanged.  This is no longer the case: all character
                    440: sequences resolve to the same symbol, regardless the escape style.
                    441: .\" LIST-ITEM
                    442: .It
                    443: Blocks of whitespace are stripped from both macro and free-form text
                    444: lines (except when in literal mode), while groff would retain whitespace
                    445: in free-form text lines.
                    446: .\" LIST-ITEM
                    447: .It
1.28      kristaps  448: Historic groff has many un-callable macros.  Most of these (excluding
                    449: some block-level macros) are now callable, conforming to the
                    450: non-historic groff version.
                    451: .\" LIST-ITEM
                    452: .It
                    453: The vertical bar
1.35      kristaps  454: .Sq \(ba
1.28      kristaps  455: made historic groff
                    456: .Qq go orbital
                    457: but is a proper delimiter in this implementation.
1.5       kristaps  458: .\" LIST-ITEM
                    459: .It
1.16      kristaps  460: .Sq \&.It \-nested
1.28      kristaps  461: is assumed for all lists (it wasn't in historic groff): any list may be
                    462: nested and
1.4       kristaps  463: .Sq \-enum
                    464: lists will restart the sequence only for the sub-list.
                    465: .\" LIST-ITEM
                    466: .It
1.16      kristaps  467: .Sq \&.It \-column
1.21      kristaps  468: syntax where column widths may be preceded by other arguments (instead
1.4       kristaps  469: of proceeded) is not supported.
                    470: .\" LIST-ITEM
                    471: .It
                    472: The
1.16      kristaps  473: .Sq \&.At
1.4       kristaps  474: macro only accepts a single parameter.
                    475: .\" LIST-ITEM
                    476: .It
                    477: Some manuals use
1.16      kristaps  478: .Sq \&.Li
1.4       kristaps  479: incorrectly by following it with a reserved character and expecting the
                    480: delimiter to render.  This is not supported.
                    481: .\" LIST-ITEM
                    482: .It
1.35      kristaps  483: If an special-character control character is escaped
                    484: .Sq \e\e ,
                    485: it will obviously not render the subsequent sequence.  Even newer
                    486: versions of groff seem to dither on this.
1.41      kristaps  487: .\" LIST-ITEM
                    488: .It
                    489: In groff, the
                    490: .Sq \&.Fo
                    491: macro only produces the first parameter.  This is no longer the case.
1.4       kristaps  492: .El
1.43      kristaps  493: .\" SECTION---------------------------------------------
1.2       kristaps  494: .Sh SEE ALSO
1.19      kristaps  495: .Xr mandoc 1 ,
                    496: .Xr mandoc_char 7
1.43      kristaps  497: .\" SECTION---------------------------------------------
1.2       kristaps  498: .Sh AUTHORS
                    499: The
                    500: .Nm
                    501: utility was written by
1.24      kristaps  502: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.43      kristaps  503: .\" SECTION---------------------------------------------
1.5       kristaps  504: .Sh CAVEATS
1.28      kristaps  505: There are many ambiguous parts of mdoc.
1.43      kristaps  506: .\" PARAGRAPH------------
1.5       kristaps  507: .Pp
                    508: .Bl -dash -compact
                    509: .\" LIST-ITEM
                    510: .It
1.16      kristaps  511: .Sq \&.Fa
1.5       kristaps  512: should be
1.16      kristaps  513: .Sq \&.Va
1.5       kristaps  514: as function arguments are variables.
                    515: .\" LIST-ITEM
                    516: .It
1.16      kristaps  517: .Sq \&.Ft
1.5       kristaps  518: should be
1.16      kristaps  519: .Sq \&.Vt
1.5       kristaps  520: as function return types are still types.  Furthermore, the
1.16      kristaps  521: .Sq \&.Ft
1.5       kristaps  522: should be removed and
1.16      kristaps  523: .Sq \&.Fo ,
1.5       kristaps  524: which ostensibly follows it, should follow the same convention as
1.16      kristaps  525: .Sq \&.Va .
1.5       kristaps  526: .\" LIST-ITEM
                    527: .It
1.16      kristaps  528: .Sq \&.Va
1.5       kristaps  529: should formalise that only one or two arguments are acceptable: a
1.21      kristaps  530: variable name and optional, preceding type.
1.5       kristaps  531: .\" LIST-ITEM
                    532: .It
1.16      kristaps  533: .Sq \&.Fd
1.5       kristaps  534: is ambiguous.  It's commonly used to indicate an include file in the
                    535: synopsis section.
1.16      kristaps  536: .Sq \&.In
1.5       kristaps  537: should be used, instead.
                    538: .\" LIST-ITEM
                    539: .It
                    540: Only the
                    541: .Sq \-literal
                    542: argument to
1.16      kristaps  543: .Sq \&.Bd
1.5       kristaps  544: makes sense.  The remaining ones should be removed.
                    545: .\" LIST-ITEM
                    546: .It
                    547: The
1.16      kristaps  548: .Sq \&.Xo
1.5       kristaps  549: and
1.16      kristaps  550: .Sq \&.Xc
1.5       kristaps  551: macros should be deprecated.
                    552: .\" LIST-ITEM
                    553: .It
                    554: The
1.16      kristaps  555: .Sq \&.Dt
1.5       kristaps  556: macro lacks clarity.  It should be absolutely clear which title will
                    557: render when formatting the manual page.
1.6       kristaps  558: .\" LIST-ITEM
                    559: .It
                    560: A
1.16      kristaps  561: .Sq \&.Lx
1.6       kristaps  562: should be provided for Linux (\(`a la
1.16      kristaps  563: .Sq \&.Ox ,
                    564: .Sq \&.Nx
1.6       kristaps  565: etc.).
1.14      kristaps  566: .\" LIST-ITEM
                    567: .It
                    568: There's no way to refer to references in
1.16      kristaps  569: .Sq \&.Rs/.Re
1.14      kristaps  570: blocks.
1.31      kristaps  571: .\" LIST-ITEM
                    572: .It
                    573: The \-split and \-nosplit arguments to
                    574: .Sq \&.An
                    575: are inane.
1.5       kristaps  576: .El

CVSweb