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

Annotation of mandoc/mdoc.7, Revision 1.63

1.63    ! kristaps    1: .\"    $Id: mdoc.7,v 1.62 2009/10/18 19:01:24 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.61      kristaps   76: .Pp
1.57      kristaps   77: .Bl -tag -width Ds -offset indent -compact
                     78: .It \&.
                     79: .Pq period
                     80: .It \&,
                     81: .Pq comma
                     82: .It \&:
                     83: .Pq colon
                     84: .It \&;
                     85: .Pq semicolon
                     86: .It \&(
                     87: .Pq left-parenthesis
                     88: .It \&)
                     89: .Pq right-parenthesis
                     90: .It \&[
                     91: .Pq left-bracket
                     92: .It \&]
                     93: .Pq right-bracket
                     94: .It \&?
                     95: .Pq question
                     96: .It \&!
                     97: .Pq exclamation
                     98: .It \&|
                     99: .Pq vertical bar
                    100: .El
                    101: .
                    102: .Pp
1.5       kristaps  103: Use of reserved characters is described in
1.57      kristaps  104: .Sx MACRO SYNTAX .
1.43      kristaps  105: For general use in macro lines, these characters must either be escaped
                    106: with a non-breaking space
1.57      kristaps  107: .Pq Sq \e&
1.50      kristaps  108: or, if applicable, an appropriate escape sequence used.
1.56      kristaps  109: .
                    110: .
1.57      kristaps  111: .Ss Special Characters
1.43      kristaps  112: Special characters may occur in both macro and free-form lines.
                    113: Sequences begin with the escape character
1.57      kristaps  114: .Sq \e
1.50      kristaps  115: followed by either an open-parenthesis
1.57      kristaps  116: .Sq \&(
1.1       kristaps  117: for two-character sequences; an open-bracket
1.57      kristaps  118: .Sq \&[
1.1       kristaps  119: for n-character sequences (terminated at a close-bracket
1.57      kristaps  120: .Sq \&] ) ;
1.43      kristaps  121: or a single one-character sequence.  See
1.57      kristaps  122: .Xr mandoc_char 7
1.50      kristaps  123: for a complete list.  Examples include
1.57      kristaps  124: .Sq \e(em
                    125: .Pq em-dash
1.50      kristaps  126: and
1.57      kristaps  127: .Sq \ee
                    128: .Pq back-slash .
1.56      kristaps  129: .
                    130: .
1.57      kristaps  131: .Ss Text Decoration
1.54      kristaps  132: Terms may be text-decorated using the
1.57      kristaps  133: .Sq \ef
1.43      kristaps  134: escape followed by an indicator: B (bold), I, (italic), or P and R
1.54      kristaps  135: (Roman, or reset).  This form is not recommended for
1.57      kristaps  136: .Nm ,
1.54      kristaps  137: which encourages semantic, not presentation, annotation.
1.56      kristaps  138: .
                    139: .
1.57      kristaps  140: .Ss Predefined Strings
1.54      kristaps  141: Historically,
1.57      kristaps  142: .Xr groff 1
1.54      kristaps  143: also defined a set of package-specific
1.57      kristaps  144: .Dq predefined strings ,
1.54      kristaps  145: which, like
1.57      kristaps  146: .Sx Special Characters ,
1.54      kristaps  147: demark special output characters and strings by way of input codes.
                    148: Predefined strings are escaped with the slash-asterisk,
1.57      kristaps  149: .Sq \e* :
1.54      kristaps  150: single-character
1.57      kristaps  151: .Sq \e*X ,
1.54      kristaps  152: two-character
1.57      kristaps  153: .Sq \e*(XX ,
1.54      kristaps  154: and N-character
1.57      kristaps  155: .Sq \e*[N] .
1.54      kristaps  156: See
1.57      kristaps  157: .Xr mandoc_char 7
1.54      kristaps  158: for a complete list.  Examples include
1.57      kristaps  159: .Sq \e*(Am
                    160: .Pq ampersand
1.54      kristaps  161: and
1.57      kristaps  162: .Sq \e*(Ba
                    163: .Pq vertical bar .
1.56      kristaps  164: .
                    165: .
1.57      kristaps  166: .Ss Whitespace
1.46      kristaps  167: In non-literal free-form lines, consecutive blocks of whitespace are
                    168: pruned from input and added later in the output filter, if applicable:
1.57      kristaps  169: .Bd -literal -offset indent
1.46      kristaps  170: These     spaces   are    pruned       from    input.
1.50      kristaps  171: \&.Bd \-literal
1.46      kristaps  172: These         are              not.
                    173: \&.Ed
1.57      kristaps  174: .Ed
                    175: .
                    176: .Pp
1.46      kristaps  177: In macro lines, whitespace delimits arguments and is discarded.  If
1.47      kristaps  178: arguments are quoted, whitespace within the quotes is retained.
1.57      kristaps  179: .
                    180: .Pp
1.46      kristaps  181: Blank lines are only permitted within literal contexts, as are lines
                    182: containing only whitespace.  Tab characters are only acceptable when
1.50      kristaps  183: delimiting
1.57      kristaps  184: .Sq \&Bl \-column
1.46      kristaps  185: or when in a literal context.
1.56      kristaps  186: .
                    187: .
1.57      kristaps  188: .Ss Quotation
1.46      kristaps  189: Macro arguments may be quoted with a double-quote to group
                    190: space-delimited terms or to retain blocks of whitespace.  A quoted
                    191: argument begins with a double-quote preceded by whitespace.  The next
1.48      kristaps  192: double-quote not pair-wise adjacent to another double-quote terminates
1.50      kristaps  193: the literal, regardless of surrounding whitespace.
1.57      kristaps  194: .
                    195: .Pp
1.50      kristaps  196: This produces tokens
1.57      kristaps  197: .Sq a" ,
                    198: .Sq b c ,
                    199: .Sq de ,
1.47      kristaps  200: and
1.57      kristaps  201: .Sq fg" .
1.47      kristaps  202: Note that any quoted term, be it argument or macro, is indiscriminately
1.50      kristaps  203: considered literal text.  Thus, the following produces
1.57      kristaps  204: .Sq \&Em a :
                    205: .Bd -literal -offset indent
1.47      kristaps  206: \&.Em "Em a"
1.57      kristaps  207: .Ed
                    208: .
                    209: .Pp
1.46      kristaps  210: In free-form mode, quotes are regarded as opaque text.
1.56      kristaps  211: .
1.63    ! kristaps  212: .Ss Dates
        !           213: TODO.
        !           214: .
1.61      kristaps  215: .Ss Scaling Widths
                    216: Many macros support scaled widths for their arguments, such as
                    217: stipulating a two-inch list indentation with the following:
                    218: .Bd -literal -offset indent
                    219: \&.Bl -tag -width 2i
                    220: .Ed
                    221: .
                    222: .Pp
                    223: The syntax for scaled widths is
1.62      kristaps  224: .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
1.61      kristaps  225: where a decimal must be preceded or proceeded by at least one digit.
                    226: Negative numbers, while accepted, are truncated to zero.  The following
                    227: scaling units are accepted:
                    228: .Pp
                    229: .Bl -tag -width Ds -offset indent -compact
                    230: .It c
                    231: centimetre
                    232: .It i
                    233: inch
                    234: .It P
                    235: pica (~1/6 inch)
                    236: .It p
                    237: point (~1/72 inch)
                    238: .It f
                    239: synonym for
                    240: .Sq u
                    241: .It v
                    242: default vertical span
                    243: .It m
                    244: width of rendered
                    245: .Sq m
                    246: .Pq em
                    247: character
                    248: .It n
                    249: width of rendered
                    250: .Sq n
                    251: .Pq en
                    252: character
                    253: .It u
                    254: default horizontal span
                    255: .It M
                    256: mini-em (~1/100 em)
                    257: .El
                    258: .Pp
                    259: Using anything other than
                    260: .Sq m ,
                    261: .Sq n ,
                    262: .Sq u ,
                    263: or
                    264: .Sq v
                    265: is necessarily non-portable across output media.  See
                    266: .Sx COMPATIBILITY .
                    267: .
1.56      kristaps  268: .
1.43      kristaps  269: .Sh MANUAL STRUCTURE
1.33      kristaps  270: Each
1.57      kristaps  271: .Nm
1.50      kristaps  272: document must begin with a document prologue, containing, in order,
1.57      kristaps  273: .Sq \&Dd ,
                    274: .Sq \&Dt ,
1.33      kristaps  275: and
1.57      kristaps  276: .Sq \&Os ,
1.46      kristaps  277: then the NAME section containing at least one
1.57      kristaps  278: .Sq \&Nm
1.50      kristaps  279: followed by
1.57      kristaps  280: .Sq \&Nd :
                    281: .Bd -literal -offset indent
1.43      kristaps  282: \&.Dd $\&Mdocdate$
                    283: \&.Dt mdoc 7
                    284: \&.Os
1.58      kristaps  285: \&.
1.43      kristaps  286: \&.Sh NAME
1.58      kristaps  287: \&.Nm foo
                    288: \&.Nd a description goes here
                    289: \&.\e\*q The next is for sections 2 & 3 only.
                    290: \&.\e\*q .Sh LIBRARY
                    291: \&.
                    292: \&.Sh SYNOPSIS
                    293: \&.Nm foo
                    294: \&.Op Fl options
                    295: \&.Ar
                    296: \&.
                    297: \&.Sh DESCRIPTION
                    298: The
                    299: \&.Nm
                    300: utility processes files ...
1.59      kristaps  301: \&.\e\*q .Sh IMPLEMENTATION NOTES
1.58      kristaps  302: \&.\e\*q The next is for sections 1 & 8 only.
                    303: \&.\e\*q .Sh EXIT STATUS
                    304: \&.\e\*q The next is for sections 2, 3, & 9 only.
                    305: \&.\e\*q .Sh RETURN VALUES
                    306: \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
                    307: \&.\e\*q .Sh ENVIRONMENT
                    308: \&.\e\*q .Sh FILES
                    309: \&.\e\*q .Sh EXAMPLES
                    310: \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
                    311: \&.\e\*q .Sh DIAGNOSTICS
                    312: \&.\e\*q The next is for sections 2, 3, & 9 only.
                    313: \&.\e\*q .Sh ERRORS
                    314: \&.\e\*q .Sh SEE ALSO
                    315: \&.\e\*q .Xr foobar 1
                    316: \&.\e\*q .Sh STANDARDS
                    317: \&.\e\*q .Sh HISTORY
                    318: \&.\e\*q .Sh AUTHORS
                    319: \&.\e\*q .Sh CAVEATS
                    320: \&.\e\*q .Sh BUGS
                    321: \&.\e\*q .Sh SECURITY CONSIDERATIONS
1.57      kristaps  322: .Ed
                    323: .
                    324: .Pp
1.43      kristaps  325: Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
1.50      kristaps  326: but non-compulsory.
1.56      kristaps  327: .
                    328: .
1.43      kristaps  329: .Sh MACRO SYNTAX
1.56      kristaps  330: Macros are one to three three characters in length and begin with a
                    331: control character ,
1.57      kristaps  332: .Sq \&. ,
1.56      kristaps  333: at the beginning of the line.  An arbitrary amount of whitespace may
                    334: sit between the control character and the macro name.  Thus,
1.57      kristaps  335: .Sq \&.Pp
1.56      kristaps  336: and
1.57      kristaps  337: .Sq \&.\ \ \ \&Pp
1.56      kristaps  338: are equivalent.  Macro names are two or three characters in length.
1.57      kristaps  339: .
                    340: .Pp
1.46      kristaps  341: The syntax of a macro depends on its classification.  In this section,
1.57      kristaps  342: .Sq \-arg
1.43      kristaps  343: refers to macro arguments, which may be followed by zero or more
1.57      kristaps  344: .Sq parm
1.43      kristaps  345: parameters;
1.57      kristaps  346: .Sq \&Yo
1.43      kristaps  347: opens the scope of a macro; and if specified,
1.57      kristaps  348: .Sq \&Yc
1.43      kristaps  349: closes it out.
1.57      kristaps  350: .
                    351: .Pp
1.43      kristaps  352: The
1.57      kristaps  353: .Em Callable
1.43      kristaps  354: column indicates that the macro may be called subsequent to the initial
1.55      kristaps  355: line-macro.  If a macro is not callable, then its invocation after the
                    356: initial line macro is interpreted as opaque text, such that
1.60      kristaps  357: .Sq \&.Fl \&Sh
1.55      kristaps  358: produces
1.60      kristaps  359: .Sq Fl \&Sh .
1.57      kristaps  360: .
                    361: .Pp
1.55      kristaps  362: The
1.57      kristaps  363: .Em Parsable
1.43      kristaps  364: column indicates whether the macro may be followed by further
1.55      kristaps  365: (ostensibly callable) macros.  If a macro is not parsable, subsequent
                    366: macro invocations on the line will be interpreted as opaque text.
1.57      kristaps  367: .
                    368: .Pp
1.55      kristaps  369: The
1.57      kristaps  370: .Em Scope
1.43      kristaps  371: column, if applicable, describes closure rules.
1.56      kristaps  372: .
                    373: .
1.57      kristaps  374: .Ss Block full-explicit
1.43      kristaps  375: Multi-line scope closed by an explicit closing macro.  All macros
                    376: contains bodies; only
1.57      kristaps  377: .Pq Sq \&Bf
1.43      kristaps  378: contains a head.
1.57      kristaps  379: .Bd -literal -offset indent
1.50      kristaps  380: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
                    381: \(lBbody...\(rB
1.43      kristaps  382: \&.Yc
1.57      kristaps  383: .Ed
                    384: .
                    385: .Pp
                    386: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
                    387: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    388: .It \&Bd     Ta    \&No     Ta    \&No     Ta    closed by \&Ed
                    389: .It \&Bf     Ta    \&No     Ta    \&No     Ta    closed by \&Ef
                    390: .It \&Bk     Ta    \&No     Ta    \&No     Ta    closed by \&Ek
                    391: .It \&Bl     Ta    \&No     Ta    \&No     Ta    closed by \&El
                    392: .It \&Ed     Ta    \&No     Ta    \&No     Ta    opened by \&Bd
                    393: .It \&Ef     Ta    \&No     Ta    \&No     Ta    opened by \&Bf
                    394: .It \&Ek     Ta    \&No     Ta    \&No     Ta    opened by \&Bk
                    395: .It \&El     Ta    \&No     Ta    \&No     Ta    opened by \&Bl
                    396: .El
1.56      kristaps  397: .
                    398: .
1.57      kristaps  399: .Ss Block full-implicit
1.43      kristaps  400: Multi-line scope closed by end-of-file or implicitly by another macro.
1.50      kristaps  401: All macros have bodies; some
1.57      kristaps  402: .Po
                    403: .Sq \&It \-bullet ,
                    404: .Sq \-hyphen ,
                    405: .Sq \-dash ,
                    406: .Sq \-enum ,
                    407: .Sq \-item
                    408: .Pc
1.50      kristaps  409: don't have heads, while
1.57      kristaps  410: .Sq \&It \-column
1.43      kristaps  411: may have multiple heads.
1.57      kristaps  412: .Bd -literal -offset indent
1.50      kristaps  413: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
                    414: \(lBbody...\(rB
1.57      kristaps  415: .Ed
1.56      kristaps  416: .
1.57      kristaps  417: .Pp
                    418: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
                    419: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    420: .It \&It     Ta    \&No     Ta    Yes      Ta    closed by \&It, \&El
                    421: .It \&Nd     Ta    \&No     Ta    \&No     Ta    closed by \&Sh
                    422: .It \&Sh     Ta    \&No     Ta    \&No     Ta    closed by \&Sh
                    423: .It \&Ss     Ta    \&No     Ta    \&No     Ta    closed by \&Sh, \&Ss
                    424: .El
1.56      kristaps  425: .
1.57      kristaps  426: .
                    427: .Ss Block partial-explicit
1.43      kristaps  428: Like block full-explicit, but also with single-line scope.  Each
1.50      kristaps  429: has at least a body and, in limited circumstances, a head
1.57      kristaps  430: .Pq So \&Fo Sc , So \&Eo Sc
1.50      kristaps  431: and/or tail
1.57      kristaps  432: .Pq So \&Ec Sc .
                    433: .Bd -literal -offset indent
1.50      kristaps  434: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
                    435: \(lBbody...\(rB
                    436: \&.Yc \(lBtail...\(rB
1.2       kristaps  437:
1.43      kristaps  438: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
1.50      kristaps  439: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.57      kristaps  440: .Ed
                    441: .
                    442: .Pp
                    443: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
                    444: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.63    ! kristaps  445: .It \&Ac     Ta    Yes      Ta    Yes      Ta    opened by Sx \&Ao
        !           446: .It Sx \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ac
1.57      kristaps  447: .It \&Bc     Ta    Yes      Ta    Yes      Ta    closed by \&Bo
                    448: .It \&Bo     Ta    Yes      Ta    Yes      Ta    opened by \&Bc
                    449: .It \&Brc    Ta    Yes      Ta    Yes      Ta    opened by \&Bro
                    450: .It \&Bro    Ta    Yes      Ta    Yes      Ta    closed by \&Brc
                    451: .It \&Dc     Ta    Yes      Ta    Yes      Ta    opened by \&Do
                    452: .It \&Do     Ta    Yes      Ta    Yes      Ta    closed by \&Dc
                    453: .It \&Ec     Ta    Yes      Ta    Yes      Ta    opened by \&Eo
                    454: .It \&Eo     Ta    Yes      Ta    Yes      Ta    closed by \&Ec
                    455: .It \&Fc     Ta    Yes      Ta    Yes      Ta    opened by \&Fo
                    456: .It \&Fo     Ta    \&No     Ta    \&No     Ta    closed by \&Fc
                    457: .It \&Oc     Ta    Yes      Ta    Yes      Ta    closed by \&Oo
                    458: .It \&Oo     Ta    Yes      Ta    Yes      Ta    opened by \&Oc
                    459: .It \&Pc     Ta    Yes      Ta    Yes      Ta    closed by \&Po
                    460: .It \&Po     Ta    Yes      Ta    Yes      Ta    opened by \&Pc
                    461: .It \&Qc     Ta    Yes      Ta    Yes      Ta    opened by \&Oo
                    462: .It \&Qo     Ta    Yes      Ta    Yes      Ta    closed by \&Oc
1.63    ! kristaps  463: .It Sx \&Re  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Rs
        !           464: .It Sx \&Rs  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Re
1.57      kristaps  465: .It \&Sc     Ta    Yes      Ta    Yes      Ta    opened by \&So
                    466: .It \&So     Ta    Yes      Ta    Yes      Ta    closed by \&Sc
                    467: .It \&Xc     Ta    Yes      Ta    Yes      Ta    opened by \&Xo
                    468: .It \&Xo     Ta    Yes      Ta    Yes      Ta    closed by \&Xc
                    469: .El
1.56      kristaps  470: .
                    471: .
1.57      kristaps  472: .Ss Block partial-implicit
1.50      kristaps  473: Like block full-implicit, but with single-line scope closed by
1.57      kristaps  474: .Sx Reserved Characters
1.43      kristaps  475: or end of line.
1.57      kristaps  476: .Bd -literal -offset indent
1.43      kristaps  477: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
1.57      kristaps  478: .Ed
1.56      kristaps  479: .
1.57      kristaps  480: .Pp
                    481: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
                    482: .It Em Macro Ta Em Callable Ta Em Parsable
                    483: .It \&Aq     Ta    Yes      Ta    Yes
                    484: .It \&Bq     Ta    Yes      Ta    Yes
                    485: .It \&Brq    Ta    Yes      Ta    Yes
                    486: .It \&D1     Ta    \&No     Ta    \&Yes
                    487: .It \&Dl     Ta    \&No     Ta    Yes
                    488: .It \&Dq     Ta    Yes      Ta    Yes
                    489: .It \&Op     Ta    Yes      Ta    Yes
                    490: .It \&Pq     Ta    Yes      Ta    Yes
                    491: .It \&Ql     Ta    Yes      Ta    Yes
                    492: .It \&Qq     Ta    Yes      Ta    Yes
                    493: .It \&Sq     Ta    Yes      Ta    Yes
                    494: .El
1.56      kristaps  495: .
1.57      kristaps  496: .
                    497: .Ss In-line
1.50      kristaps  498: Closed by
1.57      kristaps  499: .Sx Reserved Characters ,
1.43      kristaps  500: end of line, fixed argument lengths, and/or subsequent macros.  In-line
                    501: macros have only text children.  If a number (or inequality) of
1.3       kristaps  502: arguments is
1.57      kristaps  503: .Pq n ,
1.3       kristaps  504: then the macro accepts an arbitrary number of arguments.
1.57      kristaps  505: .Bd -literal -offset indent
1.43      kristaps  506: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
                    507:
                    508: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
                    509:
                    510: \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
1.57      kristaps  511: .Ed
                    512: .
                    513: .Pp
                    514: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
                    515: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.63    ! kristaps  516: .It Sx \&%A  Ta    \&No     Ta    \&No     Ta    >0
        !           517: .It Sx \&%B  Ta    \&No     Ta    \&No     Ta    >0
        !           518: .It Sx \&%C  Ta    \&No     Ta    \&No     Ta    >0
        !           519: .It Sx \&%D  Ta    \&No     Ta    \&No     Ta    >0
        !           520: .It Sx \&%I  Ta    \&No     Ta    \&No     Ta    >0
        !           521: .It Sx \&%J  Ta    \&No     Ta    \&No     Ta    >0
        !           522: .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0
        !           523: .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0
        !           524: .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0
        !           525: .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0
        !           526: .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0
        !           527: .It Sx \&%V  Ta    \&No     Ta    \&No     Ta    >0
1.57      kristaps  528: .It \&Ad     Ta    Yes      Ta    Yes      Ta    n
                    529: .It \&An     Ta    Yes      Ta    Yes      Ta    n
                    530: .It \&Ap     Ta    Yes      Ta    Yes      Ta    0
                    531: .It \&Ar     Ta    Yes      Ta    Yes      Ta    n
                    532: .It \&At     Ta    Yes      Ta    Yes      Ta    1
                    533: .It \&Bsx    Ta    Yes      Ta    Yes      Ta    n
                    534: .It \&Bt     Ta    \&No     Ta    \&No     Ta    0
                    535: .It \&Bx     Ta    Yes      Ta    Yes      Ta    n
                    536: .It \&Cd     Ta    Yes      Ta    Yes      Ta    >0
                    537: .It \&Cm     Ta    Yes      Ta    Yes      Ta    n
                    538: .It \&Db     Ta    \&No     Ta    \&No     Ta    1
                    539: .It \&Dd     Ta    \&No     Ta    \&No     Ta    >0
                    540: .It \&Dt     Ta    \&No     Ta    \&No     Ta    n
                    541: .It \&Dv     Ta    Yes      Ta    Yes      Ta    n
                    542: .It \&Dx     Ta    Yes      Ta    Yes      Ta    n
                    543: .It \&Em     Ta    Yes      Ta    Yes      Ta    >0
                    544: .It \&En     Ta    \&No     Ta    \&No     Ta    0
                    545: .It \&Er     Ta    Yes      Ta    Yes      Ta    >0
                    546: .It \&Es     Ta    \&No     Ta    \&No     Ta    0
                    547: .It \&Ev     Ta    Yes      Ta    Yes      Ta    n
1.58      kristaps  548: .It \&Ex     Ta    \&No     Ta    \&No     Ta    n
1.57      kristaps  549: .It \&Fa     Ta    Yes      Ta    Yes      Ta    n
                    550: .It \&Fd     Ta    \&No     Ta    \&No     Ta    >0
                    551: .It \&Fl     Ta    Yes      Ta    Yes      Ta    n
                    552: .It \&Fn     Ta    Yes      Ta    Yes      Ta    >0
                    553: .It \&Fr     Ta    \&No     Ta    \&No     Ta    n
                    554: .It \&Ft     Ta    Yes      Ta    Yes      Ta    n
                    555: .It \&Fx     Ta    Yes      Ta    Yes      Ta    n
                    556: .It \&Hf     Ta    \&No     Ta    \&No     Ta    n
                    557: .It \&Ic     Ta    Yes      Ta    Yes      Ta    >0
                    558: .It \&In     Ta    \&No     Ta    \&No     Ta    n
                    559: .It \&Lb     Ta    \&No     Ta    \&No     Ta    1
                    560: .It \&Li     Ta    Yes      Ta    Yes      Ta    n
                    561: .It \&Lk     Ta    Yes      Ta    Yes      Ta    n
                    562: .It \&Lp     Ta    \&No     Ta    \&No     Ta    0
                    563: .It \&Ms     Ta    Yes      Ta    Yes      Ta    >0
                    564: .It \&Mt     Ta    Yes      Ta    Yes      Ta    >0
                    565: .It \&Nm     Ta    Yes      Ta    Yes      Ta    n
                    566: .It \&No     Ta    Yes      Ta    Yes      Ta    0
                    567: .It \&Ns     Ta    Yes      Ta    Yes      Ta    0
                    568: .It \&Nx     Ta    Yes      Ta    Yes      Ta    n
                    569: .It \&Os     Ta    \&No     Ta    \&No     Ta    n
                    570: .It \&Ot     Ta    \&No     Ta    \&No     Ta    n
                    571: .It \&Ox     Ta    Yes      Ta    Yes      Ta    n
                    572: .It \&Pa     Ta    Yes      Ta    Yes      Ta    n
                    573: .It \&Pf     Ta    \&No     Ta    Yes      Ta    1
                    574: .It \&Pp     Ta    \&No     Ta    \&No     Ta    0
1.58      kristaps  575: .It \&Rv     Ta    \&No     Ta    \&No     Ta    n
1.57      kristaps  576: .It \&Sm     Ta    \&No     Ta    \&No     Ta    1
                    577: .It \&St     Ta    \&No     Ta    Yes      Ta    1
                    578: .It \&Sx     Ta    Yes      Ta    Yes      Ta    >0
                    579: .It \&Sy     Ta    Yes      Ta    Yes      Ta    >0
                    580: .It \&Tn     Ta    Yes      Ta    Yes      Ta    >0
                    581: .It \&Ud     Ta    \&No     Ta    \&No     Ta    0
                    582: .It \&Ux     Ta    Yes      Ta    Yes      Ta    n
                    583: .It \&Va     Ta    Yes      Ta    Yes      Ta    n
                    584: .It \&Vt     Ta    Yes      Ta    Yes      Ta    >0
                    585: .It \&Xr     Ta    Yes      Ta    Yes      Ta    >0, <3
                    586: .It \&br     Ta    \&No     Ta    \&No     Ta    0
                    587: .It \&sp     Ta    \&No     Ta    \&No     Ta    1
                    588: .El
1.56      kristaps  589: .
                    590: .
1.63    ! kristaps  591: .Sh REFERENCE
        !           592: This section is a canonical reference of all macros, arranged
        !           593: alphabetically.  For the scoping of individual macros, see
        !           594: .Sx MACRO SYNTAX .
        !           595: .
        !           596: .Ss \&%A
        !           597: Author name of an
        !           598: .Sx \&Rs
        !           599: block.  Multiple authors should each be accorded their own
        !           600: .Sq \%%A
        !           601: line.
        !           602: .Pp
        !           603: Author names should be ordered with full or abbreviated forename(s)
        !           604: first, then full surname.
        !           605: .Ss \&%B
        !           606: Book title of an
        !           607: .Sx \&Rs
        !           608: block.  This macro may also be used in a non-bibliographic context when
        !           609: referring to book titles.
        !           610: .Ss \&%C
        !           611: Publication city or location of an
        !           612: .Sx \&Rs
        !           613: block.
        !           614: .Pp
        !           615: .Em Compatibility remark :
        !           616: this macro is not implemented in
        !           617: .Xr groff 1 .
        !           618: .Ss \&%D
        !           619: Publication date of an
        !           620: .Sx \&Rs
        !           621: block.  This should follow the canonical syntax for
        !           622: .Sx Dates .
        !           623: .Ss \&%I
        !           624: Publisher or issuer name of an
        !           625: .Sx \&Rs
        !           626: block.
        !           627: .Ss \&%J
        !           628: Journal name of an
        !           629: .Sx \&Rs
        !           630: block.
        !           631: .Ss \&%N
        !           632: Issue number (usually for journals) of an
        !           633: .Sx \&Rs
        !           634: block.
        !           635: .Ss \&%O
        !           636: Optional information of an
        !           637: .Sx \&Rs
        !           638: block.
        !           639: .Ss \&%P
        !           640: Book or journal page number of an
        !           641: .Sx \&Rs
        !           642: block.
        !           643: .Ss \&%Q
        !           644: Institutional author (school, government, etc.) of an
        !           645: .Sx \&Rs
        !           646: block.  Multiple institutional authors should each be accorded their own
        !           647: .Sq \&%Q
        !           648: line.
        !           649: .Ss \&%R
        !           650: Technical report name of an
        !           651: .Sx \&Rs
        !           652: block.
        !           653: .Ss \&%T
        !           654: Article title of an
        !           655: .Sx \&Rs
        !           656: block.  This macro may also be used in a non-bibliographical context
        !           657: when referring to article titles.
        !           658: .Ss \&%V
        !           659: Volume number of an
        !           660: .Sx \&Rs
        !           661: block.
        !           662: .Ss \&Ac
        !           663: Closes an
        !           664: .Sx \&Ao
        !           665: block.  Does not have any tail arguments.
        !           666: .Ss \&Ad
        !           667: Address construct: usually in the context of an computational address in
        !           668: memory, not a physical (post) address.
        !           669: .Pp
        !           670: Example:
        !           671: .Bd -literal -offset indent
        !           672: \&.Ad [0,$]
        !           673: \&.Ad 0x00000000
        !           674: .Ed
        !           675: .Ss \&An
        !           676: .Ss \&Ao
        !           677: Begins a block enclosed by angled brackets.  Does not have any head
        !           678: arguments.
        !           679: .Pp
        !           680: Example:
        !           681: .Bd -literal -offset indent
        !           682: \&.Fl -key= Ns Ao Ar val Ac
        !           683: .Ed
        !           684: .Pp
        !           685: Note that, although this is overwhelmingly used to note URIs, the
        !           686: .Sx \&Lk
        !           687: and
        !           688: .Sx \&Mt
        !           689: macros are better suited for this purpose.
        !           690: .Ss \&Ap
        !           691: .Ss \&Aq
        !           692: .Ss \&Ar
        !           693: .Ss \&At
        !           694: .Ss \&Bc
        !           695: .Ss \&Bd
        !           696: .Ss \&Bf
        !           697: .Ss \&Bk
        !           698: .Ss \&Bl
        !           699: .Ss \&Bo
        !           700: .Ss \&Bq
        !           701: .Ss \&Brc
        !           702: .Ss \&Bro
        !           703: .Ss \&Brq
        !           704: .Ss \&Bsx
        !           705: .Ss \&Bt
        !           706: .Ss \&Bx
        !           707: .Ss \&Cd
        !           708: .Ss \&Cm
        !           709: .Ss \&D1
        !           710: .Ss \&Db
        !           711: .Ss \&Dc
        !           712: .Ss \&Dd
        !           713: .Ss \&Dl
        !           714: .Ss \&Do
        !           715: .Ss \&Dq
        !           716: .Ss \&Dt
        !           717: .Ss \&Dv
        !           718: .Ss \&Dx
        !           719: .Ss \&Ec
        !           720: .Ss \&Ed
        !           721: .Ss \&Ef
        !           722: .Ss \&Ek
        !           723: .Ss \&El
        !           724: .Ss \&Em
        !           725: .Ss \&En
        !           726: .Ss \&Eo
        !           727: .Ss \&Er
        !           728: .Ss \&Es
        !           729: .Ss \&Ev
        !           730: .Ss \&Ex
        !           731: .Ss \&Fa
        !           732: .Ss \&Fc
        !           733: .Ss \&Fd
        !           734: .Ss \&Fl
        !           735: .Ss \&Fn
        !           736: .Ss \&Fo
        !           737: .Ss \&Fr
        !           738: .Ss \&Ft
        !           739: .Ss \&Fx
        !           740: .Ss \&Hf
        !           741: .Ss \&Ic
        !           742: .Ss \&In
        !           743: .Ss \&It
        !           744: .Ss \&Lb
        !           745: .Ss \&Li
        !           746: .Ss \&Lk
        !           747: .Ss \&Lp
        !           748: .Ss \&Ms
        !           749: .Ss \&Mt
        !           750: .Ss \&Nd
        !           751: .Ss \&Nm
        !           752: .Ss \&No
        !           753: .Ss \&Ns
        !           754: .Ss \&Nx
        !           755: .Ss \&Oc
        !           756: .Ss \&Oo
        !           757: .Ss \&Op
        !           758: .Ss \&Os
        !           759: .Ss \&Ot
        !           760: .Ss \&Ox
        !           761: .Ss \&Pa
        !           762: .Ss \&Pc
        !           763: .Ss \&Pf
        !           764: .Ss \&Po
        !           765: .Ss \&Pp
        !           766: .Ss \&Pq
        !           767: .Ss \&Qc
        !           768: .Ss \&Ql
        !           769: .Ss \&Qo
        !           770: .Ss \&Qq
        !           771: .Ss \&Re
        !           772: Closes a
        !           773: .Sx \&Rs
        !           774: block.  Does not have any tail arguments.
        !           775: .Ss \&Rs
        !           776: Begins a bibliographic
        !           777: .Pq Dq reference
        !           778: block.  Does not have any head arguments.  The block macro and may only
        !           779: contain
        !           780: .Sx \&%A ,
        !           781: .Sx \&%B ,
        !           782: .Sx \&%C ,
        !           783: .Sx \&%D ,
        !           784: .Sx \&%I ,
        !           785: .Sx \&%J ,
        !           786: .Sx \&%N ,
        !           787: .Sx \&%O ,
        !           788: .Sx \&%P ,
        !           789: .Sx \&%Q ,
        !           790: .Sx \&%R ,
        !           791: .Sx \&%T ,
        !           792: and
        !           793: .Sx \&%V
        !           794: child macros (at least one must be specified).
        !           795: .Pp
        !           796: Example:
        !           797: .Bd -literal -offset indent
        !           798: \&.Rs
        !           799: \&.%A J. E. Hopcroft
        !           800: \&.%A J. D. Ullman
        !           801: \&.%B Introduction to Automata Theory, Languages, and Computation
        !           802: \&.%I Addison-Wesley
        !           803: \&.%C Reading, Massachusettes
        !           804: \&.%D 1979
        !           805: \&.Re
        !           806: .Ed
        !           807: .Pp
        !           808: If an
        !           809: .Sx \&Rs
        !           810: block is used within a SEE ALSO section, a vertical space is asserted
        !           811: before the rendered output, else the block continues on the current
        !           812: line.
        !           813: .Ss \&Rv
        !           814: .Ss \&Sc
        !           815: .Ss \&Sh
        !           816: .Ss \&Sm
        !           817: .Ss \&So
        !           818: .Ss \&Sq
        !           819: .Ss \&Ss
        !           820: .Ss \&St
        !           821: .Ss \&Sx
        !           822: .Ss \&Sy
        !           823: .Ss \&Tn
        !           824: .Ss \&Ud
        !           825: .Ss \&Ux
        !           826: .Ss \&Va
        !           827: .Ss \&Vt
        !           828: .Ss \&Xc
        !           829: .Ss \&Xo
        !           830: .Ss \&Xr
        !           831: .Ss \&br
        !           832: .Ss \&sp
        !           833: .
        !           834: .
1.4       kristaps  835: .Sh COMPATIBILITY
1.28      kristaps  836: This section documents compatibility with other roff implementations, at
1.50      kristaps  837: this time limited to
1.57      kristaps  838: .Xr groff 1 .
1.50      kristaps  839: The term
1.57      kristaps  840: .Qq historic groff
1.50      kristaps  841: refers to those versions before the
1.57      kristaps  842: .Pa doc.tmac
1.50      kristaps  843: file re-write
1.57      kristaps  844: .Pq somewhere between 1.15 and 1.19 .
                    845: .
                    846: .Pp
                    847: .Bl -dash -compact
                    848: .It
1.61      kristaps  849: Negative scaling units are now truncated to zero instead of creating
                    850: interesting conditions, such as with
                    851: .Sq \&sp -1i .
                    852: Furthermore, the
                    853: .Sq f
                    854: scaling unit, while accepted, is rendered as the default unit.
                    855: .It
1.51      kristaps  856: The
1.57      kristaps  857: .Sq \-split
1.51      kristaps  858: or
1.57      kristaps  859: .Sq \-nosplit
1.51      kristaps  860: argument to
1.57      kristaps  861: .Sq \&An
1.51      kristaps  862: applies to the whole document, not just to the current section as it
                    863: does in groff.
1.57      kristaps  864: .It
1.48      kristaps  865: In quoted literals, groff allowed pair-wise double-quotes to produce a
                    866: standalone double-quote in formatted output.  This idiosyncratic
                    867: behaviour is no longer applicable.
1.57      kristaps  868: .It
1.50      kristaps  869: The
1.57      kristaps  870: .Sq \&sp
1.45      kristaps  871: macro does not accept negative numbers.
1.57      kristaps  872: .It
1.35      kristaps  873: Blocks of whitespace are stripped from both macro and free-form text
                    874: lines (except when in literal mode), while groff would retain whitespace
                    875: in free-form text lines.
1.57      kristaps  876: .It
1.28      kristaps  877: Historic groff has many un-callable macros.  Most of these (excluding
                    878: some block-level macros) are now callable, conforming to the
                    879: non-historic groff version.
1.57      kristaps  880: .It
1.50      kristaps  881: The vertical bar
1.57      kristaps  882: .Sq \(ba
1.28      kristaps  883: made historic groff
1.57      kristaps  884: .Qq go orbital
1.28      kristaps  885: but is a proper delimiter in this implementation.
1.57      kristaps  886: .It
                    887: .Sq \&It \-nested
1.28      kristaps  888: is assumed for all lists (it wasn't in historic groff): any list may be
                    889: nested and
1.57      kristaps  890: .Sq \-enum
1.4       kristaps  891: lists will restart the sequence only for the sub-list.
1.57      kristaps  892: .It
                    893: .Sq \&It \-column
1.21      kristaps  894: syntax where column widths may be preceded by other arguments (instead
1.4       kristaps  895: of proceeded) is not supported.
1.57      kristaps  896: .It
1.50      kristaps  897: The
1.57      kristaps  898: .Sq \&At
1.4       kristaps  899: macro only accepts a single parameter.
1.57      kristaps  900: .It
1.4       kristaps  901: Some manuals use
1.57      kristaps  902: .Sq \&Li
1.4       kristaps  903: incorrectly by following it with a reserved character and expecting the
                    904: delimiter to render.  This is not supported.
1.57      kristaps  905: .It
1.50      kristaps  906: In groff, the
1.57      kristaps  907: .Sq \&Fo
1.41      kristaps  908: macro only produces the first parameter.  This is no longer the case.
1.57      kristaps  909: .El
1.56      kristaps  910: .
                    911: .
1.2       kristaps  912: .Sh SEE ALSO
1.57      kristaps  913: .Xr mandoc 1 ,
                    914: .Xr mandoc_char 7
1.56      kristaps  915: .
                    916: .
1.2       kristaps  917: .Sh AUTHORS
                    918: The
1.57      kristaps  919: .Nm
1.50      kristaps  920: reference was written by
1.57      kristaps  921: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.56      kristaps  922: .
                    923: .
1.5       kristaps  924: .Sh CAVEATS
1.28      kristaps  925: There are many ambiguous parts of mdoc.
1.57      kristaps  926: .
                    927: .Pp
                    928: .Bl -dash -compact
                    929: .It
                    930: .Sq \&Fa
1.50      kristaps  931: should be
1.57      kristaps  932: .Sq \&Va
1.5       kristaps  933: as function arguments are variables.
1.57      kristaps  934: .It
                    935: .Sq \&Ft
1.5       kristaps  936: should be
1.57      kristaps  937: .Sq \&Vt
1.5       kristaps  938: as function return types are still types.  Furthermore, the
1.57      kristaps  939: .Sq \&Ft
1.5       kristaps  940: should be removed and
1.57      kristaps  941: .Sq \&Fo ,
1.5       kristaps  942: which ostensibly follows it, should follow the same convention as
1.57      kristaps  943: .Sq \&Va .
                    944: .It
                    945: .Sq \&Va
1.5       kristaps  946: should formalise that only one or two arguments are acceptable: a
1.21      kristaps  947: variable name and optional, preceding type.
1.57      kristaps  948: .It
                    949: .Sq \&Fd
1.5       kristaps  950: is ambiguous.  It's commonly used to indicate an include file in the
1.50      kristaps  951: synopsis section.
1.57      kristaps  952: .Sq \&In
1.5       kristaps  953: should be used, instead.
1.57      kristaps  954: .It
1.5       kristaps  955: Only the
1.57      kristaps  956: .Sq \-literal
1.5       kristaps  957: argument to
1.57      kristaps  958: .Sq \&Bd
1.5       kristaps  959: makes sense.  The remaining ones should be removed.
1.57      kristaps  960: .It
1.50      kristaps  961: The
1.57      kristaps  962: .Sq \&Xo
1.5       kristaps  963: and
1.57      kristaps  964: .Sq \&Xc
1.5       kristaps  965: macros should be deprecated.
1.57      kristaps  966: .It
1.5       kristaps  967: The
1.57      kristaps  968: .Sq \&Dt
1.5       kristaps  969: macro lacks clarity.  It should be absolutely clear which title will
                    970: render when formatting the manual page.
1.57      kristaps  971: .It
1.6       kristaps  972: A
1.57      kristaps  973: .Sq \&Lx
1.50      kristaps  974: should be provided for Linux (\(`a la
1.57      kristaps  975: .Sq \&Ox ,
                    976: .Sq \&Nx
1.6       kristaps  977: etc.).
1.57      kristaps  978: .It
1.14      kristaps  979: There's no way to refer to references in
1.57      kristaps  980: .Sq \&Rs/Re
1.14      kristaps  981: blocks.
1.57      kristaps  982: .It
1.54      kristaps  983: The \-split and \-nosplit dictates via
1.57      kristaps  984: .Sq \&An
1.54      kristaps  985: are re-set when entering and leaving the AUTHORS section.
1.57      kristaps  986: .El
1.56      kristaps  987: .

CVSweb