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

Annotation of mandoc/mdoc.7, Revision 1.58

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

CVSweb