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

Annotation of mandoc/mdoc.7, Revision 1.6

1.6     ! kristaps    1: .\" $Id: mdoc.7,v 1.5 2009/03/16 22:19:19 kristaps Exp $
1.1       kristaps    2: .\"
1.6     ! kristaps    3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
1.1       kristaps    4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
                      6: .\" purpose with or without fee is hereby granted, provided that the
                      7: .\" above copyright notice and this permission notice appear in all
                      8: .\" copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
                     11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
                     12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
                     13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
                     14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
                     15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
                     16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
                     17: .\" PERFORMANCE OF THIS SOFTWARE.
                     18: .\"
                     19: .Dd $Mdocdate$
                     20: .Dt mdoc 7
                     21: .Os
                     22: .\" SECTION
                     23: .Sh NAME
                     24: .Nm mdoc
                     25: .Nd mdoc macro reference
                     26: .\" SECTION
                     27: .Sh DESCRIPTION
                     28: The
                     29: .Nm mdoc
                     30: language is used to format
                     31: .Bx
                     32: .Ux
                     33: manuals.  An
                     34: .Nm
                     35: document follows simple rules:  lines beginning with the control
                     36: character
                     37: .Sq \.
                     38: are parsed for macros.  Other lines are interpreted within the scope of
1.3       kristaps   39: prior macros.  This document describes the encoding, ontology and syntax
                     40: of these macros.
1.1       kristaps   41: .\" SECTION
                     42: .Sh CHARACTER ENCODING
                     43: .Nm
1.6     ! kristaps   44: documents may contain only printable characters, the space character
1.1       kristaps   45: .Sq \  ,
                     46: and, in certain circumstances, the tab character
                     47: .Sq \et .
                     48: All manuals must have
                     49: .Sq \en
                     50: line termination.
                     51: .\" SUB-SECTION
1.2       kristaps   52: .Ss Reserved Characters
                     53: Within a macro line, the following characters are reserved:
                     54: .Bl -tag -width 12n -offset XXXX -compact
1.1       kristaps   55: .It \&.
1.2       kristaps   56: .Pq period
1.1       kristaps   57: .It \&,
1.2       kristaps   58: .Pq comma
1.1       kristaps   59: .It \&:
1.2       kristaps   60: .Pq colon
1.1       kristaps   61: .It \&;
1.2       kristaps   62: .Pq semicolon
1.1       kristaps   63: .It \&(
1.2       kristaps   64: .Pq left-parenthesis
1.1       kristaps   65: .It \&)
1.2       kristaps   66: .Pq right-parenthesis
1.1       kristaps   67: .It \&[
1.2       kristaps   68: .Pq left-bracket
1.1       kristaps   69: .It \&]
1.2       kristaps   70: .Pq right-bracket
1.1       kristaps   71: .It \&?
1.2       kristaps   72: .Pq question
1.1       kristaps   73: .It \&!
1.5       kristaps   74: .Pq exclamation
1.1       kristaps   75: .El
1.5       kristaps   76: .\" PARAGRAPH
1.1       kristaps   77: .Pp
1.5       kristaps   78: Use of reserved characters is described in
                     79: .Sx Closure .
                     80: For general non-reserved use, characters must either be escaped with a
                     81: non-breaking space
1.1       kristaps   82: .Pq Sq \e&
1.5       kristaps   83: or, if applicable, an appropriate escape-sequence used.
1.1       kristaps   84: .\" SUB-SECTION
                     85: .Ss Special Characters
                     86: Special character sequences begin with the escape character
                     87: .Sq \\
1.4       kristaps   88: followed by either an open-parenthesis
1.1       kristaps   89: .Sq \&(
                     90: for two-character sequences; an open-bracket
                     91: .Sq \&[
                     92: for n-character sequences (terminated at a close-bracket
                     93: .Sq \&] ) ;
                     94: or a single one-character sequence.
                     95: .Pp
                     96: Characters may alternatively be escaped by a slash-asterisk,
                     97: .Sq \\* ,
1.4       kristaps   98: with the same combinations as described above.  This form is deprecated.
                     99: .Pp
                    100: The following is a table of all available escapes.
1.1       kristaps  101: .Pp
                    102: Grammatic:
                    103: .Bl -tag -width 12n -offset "XXXX" -compact
                    104: .It \\(em
                    105: .Pq em-dash
                    106: .It \\(en
                    107: .Pq en-dash
                    108: .It \e-
                    109: .Pq hyphen
                    110: .It \\\\
                    111: .Pq back-slash
                    112: .It \e'
                    113: .Pq apostrophe
                    114: .It \e`
                    115: .Pq back-tick
                    116: .It \\
                    117: .Pq space
                    118: .It \\.
                    119: .Pq period
                    120: .El
                    121: .\" PARAGRAPH
                    122: .Pp
                    123: Enclosures:
                    124: .Bl -tag -width 12n -offset "XXXX" -compact
1.5       kristaps  125: .It \\(lh
                    126: .Pq left hand
                    127: .It \\(rh
                    128: .Pq right hand
                    129: .It \\(<<
                    130: .Pq left guillemot
                    131: .It \\(>>
                    132: .Pq right guillemot
1.1       kristaps  133: .It \\(rC
                    134: .Pq right brace
                    135: .It \\(lC
                    136: .Pq left brace
                    137: .It \\(ra
                    138: .Pq right angle
                    139: .It \\(la
                    140: .Pq left angle
                    141: .It \\(rB
                    142: .Pq right bracket
                    143: .It \\(lB
                    144: .Pq left bracket
                    145: .It \\q
                    146: .Pq double-quote
                    147: .It \\(lq
                    148: .Pq left double-quote
                    149: .It \\(Lq
                    150: .Pq left double-quote, deprecated
                    151: .It \\(rq
                    152: .Pq right double-quote
                    153: .It \\(Rq
                    154: .Pq right double-quote, deprecated
                    155: .It \\(oq
                    156: .Pq left single-quote
                    157: .It \\(aq
                    158: .Pq right single-quote
                    159: .El
                    160: .\" PARAGRAPH
                    161: .Pp
                    162: Indicatives:
                    163: .Bl -tag -width 12n -offset "XXXX" -compact
                    164: .It \\(<-
                    165: .Pq left arrow
                    166: .It \\(->
                    167: .Pq right arrow
                    168: .It \\(ua
                    169: .Pq up arrow
                    170: .It \\(da
                    171: .Pq down arrow
1.5       kristaps  172: .It \\(<>
                    173: .Pq left-right arrow
                    174: .It \\(lA
                    175: .Pq left double-arrow
                    176: .It \\(rA
                    177: .Pq right double-arrow
                    178: .It \\(uA
                    179: .Pq up double-arrow
                    180: .It \\(dA
                    181: .Pq down double-arrow
                    182: .It \\(hA
                    183: .Pq left-right double-arrow
1.1       kristaps  184: .El
                    185: .\" PARAGRAPH
                    186: .Pp
                    187: Mathematical:
                    188: .Bl -tag -width 12n -offset "XXXX" -compact
                    189: .It \\(Gt
                    190: .Pq greater-than, deprecated
                    191: .It \\(Lt
                    192: .Pq less-than, deprecated
                    193: .It \\(<=
                    194: .Pq less-than-equal
                    195: .It \\(Le
                    196: .Pq less-than-equal, deprecated
                    197: .It \\(>=
                    198: .Pq greater-than-equal
                    199: .It \\(Ge
                    200: .Pq greater-than-equal
                    201: .It \\(==
                    202: .Pq equal
                    203: .It \\(!=
                    204: .Pq not equal
                    205: .It \\(Ne
                    206: .Pq not equal, deprecated
                    207: .It \\(if
                    208: .Pq infinity
                    209: .It \\(If
                    210: .Pq infinity, deprecated
                    211: .It \\(na
                    212: .Pq NaN , an extension
                    213: .It \\(Na
                    214: .Pq NaN, deprecated
                    215: .It \\(+-
                    216: .Pq plus-minus
                    217: .It \\(Pm
                    218: .Pq plus-minus, deprecated
                    219: .It \\(**
                    220: .Pq asterisk
                    221: .El
                    222: .\" PARAGRAPH
                    223: .Pp
1.5       kristaps  224: Diacritics and letter combinations:
1.1       kristaps  225: .Bl -tag -width 12n -offset "XXXX" -compact
                    226: .It \\(ga
                    227: .Pq accent grave
                    228: .It \\(aa
                    229: .Pq accent accute
1.5       kristaps  230: .It \\(ad
                    231: .Pq accent dieresis
                    232: .It \\(a~
                    233: .Pq accent tilde
                    234: .It \\(AE
                    235: .Pq upper-case AE
                    236: .It \\(ae
                    237: .Pq lower-case AE
                    238: .It \\(OE
                    239: .Pq upper-case OE
                    240: .It \\(oe
                    241: .Pq lower-case OE
                    242: .It \\('A
                    243: .Pq upper-case acute A
                    244: .It \\('E
                    245: .Pq upper-case acute E
                    246: .It \\('I
                    247: .Pq upper-case acute I
                    248: .It \\('O
                    249: .Pq upper-case acute O
                    250: .It \\('U
                    251: .Pq upper-case acute U
                    252: .It \\('a
                    253: .Pq lower-case acute a
                    254: .It \\('e
                    255: .Pq lower-case acute e
                    256: .It \\('i
                    257: .Pq lower-case acute i
                    258: .It \\('o
                    259: .Pq lower-case acute o
                    260: .It \\('u
                    261: .Pq lower-case acute u
                    262: .It \\(`A
                    263: .Pq upper-case grave A
                    264: .It \\(`E
                    265: .Pq upper-case grave E
                    266: .It \\(`I
                    267: .Pq upper-case grave I
                    268: .It \\(`O
                    269: .Pq upper-case grave O
                    270: .It \\(`U
                    271: .Pq upper-case grave U
                    272: .It \\(`a
                    273: .Pq lower-case grave a
                    274: .It \\(`e
                    275: .Pq lower-case grave e
                    276: .It \\(`i
                    277: .Pq lower-case grave i
                    278: .It \\(`o
                    279: .Pq lower-case grave o
                    280: .It \\(`u
                    281: .Pq lower-case grave u
                    282: .It \\(~A
                    283: .Pq upper-case tilde A
                    284: .It \\(~N
                    285: .Pq upper-case tilde N
                    286: .It \\(~O
                    287: .Pq upper-case tilde O
                    288: .It \\(~a
                    289: .Pq lower-case tilde a
                    290: .It \\(~n
                    291: .Pq lower-case tilde n
                    292: .It \\(~o
                    293: .Pq lower-case tilde o
                    294: .It \\(:A
                    295: .Pq upper-case dieresis A
                    296: .It \\(:E
                    297: .Pq upper-case dieresis E
                    298: .It \\(:I
                    299: .Pq upper-case dieresis I
                    300: .It \\(:O
                    301: .Pq upper-case dieresis O
                    302: .It \\(:U
                    303: .Pq upper-case dieresis U
                    304: .It \\(:a
                    305: .Pq lower-case dieresis a
                    306: .It \\(:e
                    307: .Pq lower-case dieresis e
                    308: .It \\(:i
                    309: .Pq lower-case dieresis i
                    310: .It \\(:o
                    311: .Pq lower-case dieresis o
                    312: .It \\(:u
                    313: .Pq lower-case dieresis u
                    314: .It \\(:y
                    315: .Pq lower-case dieresis y
1.1       kristaps  316: .El
                    317: .\" PARAGRAPH
                    318: .Pp
                    319: Special symbols:
                    320: .Bl -tag -width 12n -offset "XXXX" -compact
                    321: .It \\(bu
                    322: .Pq bullet
                    323: .It \\(ba
                    324: .Pq bar
                    325: .It \\(Ba
                    326: .Pq bar, deprecated
                    327: .It \\(co
                    328: .Pq copyright
1.5       kristaps  329: .It \\(rg
                    330: .Pq registered
                    331: .It \\(tm
                    332: .Pq trademarked
1.1       kristaps  333: .It \\&
                    334: .Pq non-breaking space
                    335: .It \\e
                    336: .Pq escape
                    337: .It \\(Am
                    338: .Pq ampersand, deprecated
                    339: .El
                    340: .\" SECTION
1.2       kristaps  341: .Sh ONTOLOGY
1.1       kristaps  342: Macros are classified in an ontology described by scope rules.
1.4       kristaps  343: .\" SUB-SECTION
                    344: .Ss Scope
1.2       kristaps  345: .Bl -inset
1.1       kristaps  346: .\" LIST-ITEM
                    347: .It Em Block
1.2       kristaps  348: macros enclose other block macros, in-line macros or text, and
1.4       kristaps  349: may span multiple lines.
1.2       kristaps  350: .Bl -inset -offset XXXX
1.1       kristaps  351: .\" LIST-ITEM
                    352: .It Em Full-block
1.5       kristaps  353: macros always span multiple lines.  They consist of zero or
1.2       kristaps  354: more
1.1       kristaps  355: .Qq heads ,
1.5       kristaps  356: subsequent macros or text on the same line following invocation; an
                    357: optional
1.1       kristaps  358: .Qq body ,
                    359: which spans subsequent lines of text or macros; and an optional
                    360: .Qq tail ,
                    361: macros or text on the same line following closure.
                    362: .\" LIST-ITEM
                    363: .It Em Partial-block
1.5       kristaps  364: macros may span multiple lines.  They consists of a optional
1.1       kristaps  365: .Qq head ,
                    366: text immediately following invocation; always a
                    367: .Qq body ,
                    368: text or macros following the head on the same and subsequent lines; and
                    369: optionally a
                    370: .Qq tail ,
                    371: text immediately following closure.
                    372: .\" LIST-ITEM
                    373: .It Em In-line
1.4       kristaps  374: macros may only enclose text and span at most a single line.
                    375: .El
                    376: .El
                    377: .\" SUB-SECTION
                    378: .Ss Closure
                    379: Closure of a macro's scope depends first on its classification, then
                    380: on whether it's parsable.  In this table,
                    381: .Sq BFE
                    382: refers to block full-explicit and so on.
                    383: .\" PARAGRAPH
                    384: .Pp
                    385: .Bl -tag -width 12n -offset XXXX -compact
                    386: .It BPE , BFE
                    387: corresponding explicit closure macro
                    388: .It BFI
                    389: end-of-file or a corresponding implicit closure macro
                    390: .It BPI
                    391: end-of-line (body may be closed by >0 space-separated
                    392: .Sx Reserved Characters ,
                    393: although block scope will still be open)
                    394: .It INL
                    395: end-of-line
1.1       kristaps  396: .El
1.4       kristaps  397: .\" PARAGRAPH
                    398: .Pp
                    399: If a macro (block or in-line) is parsable, it may also be closed out by
                    400: one of the following scenarios (unless specifically noted otherwise):
                    401: .\" PARAGRAPH
                    402: .Pp
                    403: .Bl -dash -offset XXXX -compact
                    404: .It
                    405: a sequence of >0 space-separated
                    406: .Sx Reserved Characters ,
                    407: .It
                    408: another macro,
                    409: .It
                    410: end-of-line, or
                    411: .It
                    412: completion of a set number of arguments.
                    413: .El
                    414: .\" PARAGRAPH
                    415: .Pp
                    416: If >0 space-separated
                    417: .Sx Reserved Characters
                    418: are followed by non-reserved characters, the behaviour differs per
                    419: macro.  In general, scope of the macro is closed and re-opened:
                    420: subsequent tokens are interpreted as if the scope had just been opened.
                    421: In other circumstances, scope is simply closed out.
1.1       kristaps  422: .\" SECTION
1.2       kristaps  423: .Sh SYNTAX
1.3       kristaps  424: Macros are generally two and at times three characters in length.  The
                    425: syntax of macro invocation depends on its classification.
1.2       kristaps  426: .Qq \-arg
                    427: refers to the macro arguments (which may contain zero or more values).
                    428: In these illustrations,
                    429: .Sq \&.Yo
                    430: opens the scope of a macro, and if specified,
                    431: .Sq \&.Yc
                    432: closes it out (closure may be implicit at end-of-line or end-of-file).
1.4       kristaps  433: .\" PARAGRAPH
1.2       kristaps  434: .Pp
1.4       kristaps  435: Block full-explicit (may contain head, body, tail).
1.2       kristaps  436: .Bd -literal -offset XXXX
1.4       kristaps  437: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
                    438: \(lBbody...\(rB
                    439: \&.Yc \(lBtail...\(rB
1.2       kristaps  440: .Ed
1.4       kristaps  441: .\" PARAGRAPH
1.2       kristaps  442: .Pp
1.4       kristaps  443: Block full-implicit (may contain zero or more heads, body, no tail).
1.2       kristaps  444: .Bd -literal -offset XXXX
1.4       kristaps  445: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
                    446: \(lBbody...\(rB
1.2       kristaps  447: \&.Yc
                    448: .Ed
1.4       kristaps  449: .\" PARAGRAPH
1.2       kristaps  450: .Pp
1.4       kristaps  451: Block partial-explicit (may contain head, multi-line body, tail).
1.2       kristaps  452: .Bd -literal -offset XXXX
                    453: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
1.4       kristaps  454: \(lBbody...\(rB
                    455: \&.Yc \(lBtail...\(rB
1.2       kristaps  456:
                    457: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
1.4       kristaps  458: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2       kristaps  459: .Ed
1.4       kristaps  460: .\" PARAGRAPH
1.2       kristaps  461: .Pp
1.4       kristaps  462: Block partial-implicit (no head, body, no tail).  Note that the body
                    463: section may be followed by zero or more
                    464: .Sx Reserved Words .
                    465: These are in the block scope, but not in the body scope.
1.2       kristaps  466: .Bd -literal -offset XXXX
1.4       kristaps  467: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
1.2       kristaps  468: .Ed
1.4       kristaps  469: .\" PARAGRAPH
1.2       kristaps  470: .Pp
1.4       kristaps  471: In-lines have \(>=0 scoped arguments.
1.2       kristaps  472: .Bd -literal -offset XXX
1.4       kristaps  473: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
1.2       kristaps  474:
                    475: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
                    476: .Ed
                    477: .\"
1.1       kristaps  478: .Sh MACROS
                    479: This section contains a complete list of all
                    480: .Nm
1.2       kristaps  481: macros, arranged ontologically.  A
1.1       kristaps  482: .Qq callable
                    483: macro is may be invoked subsequent to the initial macro-line macro.  A
                    484: .Qq parsable
1.2       kristaps  485: macro may be followed by further (ostensibly callable) macros.
1.1       kristaps  486: .\" SUB-SECTION
                    487: .Ss Block full-implicit
                    488: The head of these macros follows invocation; the body is the content of
                    489: subsequent lines prior to closure.  None of these macros have tails;
                    490: some
                    491: .Po
                    492: .Sq \&It \-bullet ,
                    493: .Sq \-hyphen ,
                    494: .Sq \-dash ,
1.2       kristaps  495: .Sq \-enum ,
                    496: .Sq \-item
1.1       kristaps  497: .Pc
                    498: don't have heads.
                    499: .Pp
                    500: .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
                    501: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
                    502: .It \&.Sh    Ta    \&No    Ta    \&No    Ta    \&.Sh
                    503: .It \&.Ss    Ta    \&No    Ta    \&No    Ta    \&.Sh, \&.Ss
                    504: .It \&.It    Ta    \&No    Ta    Yes     Ta    \&.It, \&.El
                    505: .El
                    506: .\" SUB-SECTION
                    507: .Ss Block full-explicit
                    508: None of these macros are callable or parsed.  The last column indicates
                    509: the explicit scope rules.  All contains bodies, some may contain heads
                    510: .Pq So \&Bf Sc .
                    511: .Pp
                    512: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
                    513: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    514: .It \&.Bd    Ta    \&No    Ta    \&No    Ta    closed by \&.Ed
                    515: .It \&.Ed    Ta    \&No    Ta    \&No    Ta    opened by \&.Bd
                    516: .It \&.Bl    Ta    \&No    Ta    \&No    Ta    closed by \&.El
                    517: .It \&.El    Ta    \&No    Ta    \&No    Ta    opened by \&.Bl
                    518: .It \&.Bf    Ta    \&No    Ta    \&No    Ta    closed by \&.Ef
                    519: .It \&.Ef    Ta    \&No    Ta    \&No    Ta    opened by \&.Bf
1.2       kristaps  520: .It \&.Bk    Ta    \&No    Ta    \&No    Ta    closed by \&.Ek
                    521: .It \&.Ek    Ta    \&No    Ta    \&No    Ta    opened by \&.Bk
1.1       kristaps  522: .El
                    523: .\" SUB-SECTION
                    524: .Ss Block partial-implicit
                    525: All of these are callable and parsed for further macros.  Their scopes
                    526: close at the invocation's end-of-line.
                    527: .Pp
                    528: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
                    529: .It Em Macro Ta Em Callable Ta Em Parsable
                    530: .It \&.Aq    Ta    Yes   Ta    Yes
                    531: .It \&.Op    Ta    Yes   Ta    Yes
                    532: .It \&.Bq    Ta    Yes   Ta    Yes
                    533: .It \&.Dq    Ta    Yes   Ta    Yes
                    534: .It \&.Pq    Ta    Yes   Ta    Yes
                    535: .It \&.Qq    Ta    Yes   Ta    Yes
                    536: .It \&.Sq    Ta    Yes   Ta    Yes
                    537: .It \&.Brq   Ta    Yes   Ta    Yes
1.2       kristaps  538: .It \&.D1    Ta    \&No  Ta    \&Yes
                    539: .It \&.Dl    Ta    \&No  Ta    Yes
                    540: .It \&.Ql    Ta    Yes   Ta    Yes
1.1       kristaps  541: .El
                    542: .\" SUB-SECTION
                    543: .Ss Block partial-explicit
                    544: Each of these contains at least a body and, in limited circumstances, a
                    545: head
                    546: .Pq So \&Fo Sc , So \&Eo Sc
                    547: and/or tail
                    548: .Pq So \&Ec Sc .
                    549: .Pp
                    550: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
                    551: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    552: .It \&.Ao    Ta    Yes   Ta    Yes    Ta    closed by \&.Ac
                    553: .It \&.Ac    Ta    Yes   Ta    Yes    Ta    opened by \&.Ao
                    554: .It \&.Bc    Ta    Yes   Ta    Yes    Ta    closed by \&.Bo
                    555: .It \&.Bo    Ta    Yes   Ta    Yes    Ta    opened by \&.Bc
                    556: .It \&.Pc    Ta    Yes   Ta    Yes    Ta    closed by \&.Po
                    557: .It \&.Po    Ta    Yes   Ta    Yes    Ta    opened by \&.Pc
                    558: .It \&.Do    Ta    Yes   Ta    Yes    Ta    closed by \&.Dc
                    559: .It \&.Dc    Ta    Yes   Ta    Yes    Ta    opened by \&.Do
                    560: .It \&.Xo    Ta    Yes   Ta    Yes    Ta    closed by \&.Xc
                    561: .It \&.Xc    Ta    Yes   Ta    Yes    Ta    opened by \&.Xo
                    562: .It \&.Bro   Ta    Yes   Ta    Yes    Ta    closed by \&.Brc
                    563: .It \&.Brc   Ta    Yes   Ta    Yes    Ta    opened by \&.Bro
                    564: .It \&.Oc    Ta    Yes   Ta    Yes    Ta    closed by \&.Oo
                    565: .It \&.Oo    Ta    Yes   Ta    Yes    Ta    opened by \&.Oc
                    566: .It \&.So    Ta    Yes   Ta    Yes    Ta    closed by \&.Sc
                    567: .It \&.Sc    Ta    Yes   Ta    Yes    Ta    opened by \&.So
                    568: .It \&.Fc    Ta    Yes   Ta    Yes    Ta    opened by \&.Fo
                    569: .It \&.Fo    Ta    \&No  Ta    \&No   Ta    closed by \&.Fc
                    570: .It \&.Ec    Ta    Yes   Ta    Yes    Ta    opened by \&.Eo
                    571: .It \&.Eo    Ta    Yes   Ta    Yes    Ta    closed by \&.Ec
                    572: .It \&.Qc    Ta    Yes   Ta    Yes    Ta    opened by \&.Oo
                    573: .It \&.Qo    Ta    Yes   Ta    Yes    Ta    closed by \&.Oc
1.2       kristaps  574: .It \&.Re    Ta    \&No  Ta    \&No   Ta    opened by \&.Rs
                    575: .It \&.Rs    Ta    \&No  Ta    \&No   Ta    closed by \&.Re
1.1       kristaps  576: .El
                    577: .\" SUB-SECTION
1.2       kristaps  578: .Ss In-line
1.3       kristaps  579: In-line macros have only text children.  If a number (or inequality) of
                    580: arguments is
                    581: .Pq n ,
                    582: then the macro accepts an arbitrary number of arguments.
1.2       kristaps  583: .Pp
                    584: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
                    585: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.3       kristaps  586: .It \&.Dd    Ta    \&No  Ta    \&No    Ta    >0
                    587: .It \&.Dt    Ta    \&No  Ta    \&No    Ta    n
                    588: .It \&.Os    Ta    \&No  Ta    \&No    Ta    n
1.2       kristaps  589: .It \&.Pp    Ta    \&No  Ta    \&No    Ta    0
1.3       kristaps  590: .It \&.Ad    Ta    Yes   Ta    Yes     Ta    n
                    591: .It \&.An    Ta    \&No  Ta    Yes     Ta    n
                    592: .It \&.Ar    Ta    Yes   Ta    Yes     Ta    n
                    593: .It \&.Cd    Ta    Yes   Ta    \&No    Ta    >0
                    594: .It \&.Cm    Ta    Yes   Ta    Yes     Ta    n
                    595: .It \&.Dv    Ta    Yes   Ta    Yes     Ta    >0
                    596: .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0
                    597: .It \&.Ev    Ta    Yes   Ta    Yes     Ta    >0
                    598: .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0
                    599: .It \&.Fa    Ta    Yes   Ta    Yes     Ta    >0
                    600: .It \&.Fd    Ta    \&No  Ta    \&No    Ta    >0
                    601: .It \&.Fl    Ta    Yes   Ta    Yes     Ta    n
                    602: .It \&.Fn    Ta    Yes   Ta    Yes     Ta    >0
                    603: .It \&.Ft    Ta    \&No  Ta    Yes     Ta    n
                    604: .It \&.Ic    Ta    Yes   Ta    Yes     Ta    >0
                    605: .It \&.In    Ta    \&No  Ta    \&No    Ta    n
                    606: .It \&.Li    Ta    Yes   Ta    Yes     Ta    >0
                    607: .It \&.Nd    Ta    \&No  Ta    \&No    Ta    n
                    608: .It \&.Nm    Ta    Yes   Ta    Yes     Ta    n
                    609: .It \&.Ot    Ta    \&No  Ta    \&No    Ta    n
                    610: .It \&.Pa    Ta    Yes   Ta    Yes     Ta    n
                    611: .It \&.Rv    Ta    \&No  Ta    \&No    Ta    0
                    612: .It \&.St    Ta    \&No  Ta    Yes     Ta    1
                    613: .It \&.Va    Ta    Yes   Ta    Yes     Ta    >0
                    614: .It \&.Vt    Ta    Yes   Ta    Yes     Ta    >0
                    615: .It \&.Xr    Ta    Yes   Ta    Yes     Ta    >0, <3
                    616: .It \&.%A    Ta    \&No  Ta    \&No    Ta    >0
                    617: .It \&.%B    Ta    \&No  Ta    \&No    Ta    >0
                    618: .It \&.%C    Ta    \&No  Ta    \&No    Ta    >0
                    619: .It \&.%D    Ta    \&No  Ta    \&No    Ta    >0
                    620: .It \&.%I    Ta    \&No  Ta    \&No    Ta    >0
                    621: .It \&.%J    Ta    \&No  Ta    \&No    Ta    >0
                    622: .It \&.%N    Ta    \&No  Ta    \&No    Ta    >0
                    623: .It \&.%O    Ta    \&No  Ta    \&No    Ta    >0
                    624: .It \&.%P    Ta    \&No  Ta    \&No    Ta    >0
                    625: .It \&.%R    Ta    \&No  Ta    \&No    Ta    >0
                    626: .It \&.%T    Ta    \&No  Ta    \&No    Ta    >0
                    627: .It \&.%V    Ta    \&No  Ta    \&No    Ta    >0
                    628: .It \&.At    Ta    Yes   Ta    Yes     Ta    1
                    629: .It \&.Bsx   Ta    Yes   Ta    Yes     Ta    n
                    630: .It \&.Bx    Ta    Yes   Ta    Yes     Ta    n
                    631: .It \&.Db    Ta    \&No  Ta    \&No    Ta    1
                    632: .It \&.Em    Ta    Yes   Ta    Yes     Ta    >0
                    633: .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n
                    634: .It \&.Ms    Ta    \&No  Ta    Yes     Ta    >0
                    635: .It \&.No    Ta    Yes   Ta    Yes     Ta    0
                    636: .It \&.Ns    Ta    Yes   Ta    Yes     Ta    0
                    637: .It \&.Nx    Ta    Yes   Ta    Yes     Ta    n
                    638: .It \&.Ox    Ta    Yes   Ta    Yes     Ta    n
                    639: .It \&.Pf    Ta    \&No  Ta    Yes     Ta    1
                    640: .It \&.Sm    Ta    \&No  Ta    \&No    Ta    1
                    641: .It \&.Sx    Ta    Yes   Ta    Yes     Ta    >0
                    642: .It \&.Sy    Ta    Yes   Ta    Yes     Ta    >0
                    643: .It \&.Tn    Ta    Yes   Ta    Yes     Ta    >0
                    644: .It \&.Ux    Ta    Yes   Ta    Yes     Ta    n
1.6     ! kristaps  645: .It \&.Dx    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  646: .It \&.Bt    Ta    \&No  Ta    \&No    Ta    0
                    647: .It \&.Hf    Ta    \&No  Ta    \&No    Ta    n
                    648: .It \&.Fr    Ta    \&No  Ta    \&No    Ta    n
                    649: .It \&.Ud    Ta    \&No  Ta    \&No    Ta    0
                    650: .It \&.Lb    Ta    \&No  Ta    \&No    Ta    1
                    651: .It \&.Ap    Ta    Yes   Ta    Yes     Ta    0
                    652: .It \&.Lp    Ta    \&No  Ta    \&No    Ta    0
                    653: .It \&.Lk    Ta    \&No  Ta    Yes     Ta    >0
                    654: .It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0
1.6     ! kristaps  655: .It \&.Es    Ta    \&No  Ta    \&No    Ta    0
        !           656: .It \&.En    Ta    \&No  Ta    \&No    Ta    0
1.1       kristaps  657: .El
1.6     ! kristaps  658: .Pp
        !           659: The
        !           660: .Sq \&Ot ,
        !           661: .Sq \&Fr ,
        !           662: .Sq \&Es
        !           663: and
        !           664: .Sq \&En ,
        !           665: macros are obsolete.
1.2       kristaps  666: .\" SECTION
1.4       kristaps  667: .Sh COMPATIBILITY
                    668: The mdoc language was traditionally a
                    669: .Qq roff
                    670: macro package; most existing manuals were written with mdoc syntax
                    671: dictated by system-dependent roff installations.  This section documents
                    672: compatibility with these systems.
                    673: .Pp
                    674: .Bl -dash -compact
                    675: .\" LIST-ITEM
                    676: .It
1.5       kristaps  677: .Sq \&Fo
                    678: and
                    679: .Sq \&St
                    680: historically weren't always callable.  Both are now correctly callable.
                    681: .\" LIST-ITEM
                    682: .It
1.4       kristaps  683: .Sq \&It \-nested
                    684: is assumed for all lists: any list may be nested and
                    685: .Sq \-enum
                    686: lists will restart the sequence only for the sub-list.
                    687: .\" LIST-ITEM
                    688: .It
                    689: .Sq \&It \-column
                    690: syntax where column widths may be preceeded by other arguments (instead
                    691: of proceeded) is not supported.
                    692: .\" LIST-ITEM
                    693: .It
                    694: The
                    695: .Sq \&At
                    696: macro only accepts a single parameter.
                    697: .\" LIST-ITEM
                    698: .It
                    699: The system-name macros (
                    700: .Ns Sq \&At ,
                    701: .Sq \&Bsx ,
                    702: .Sq \&Bx ,
                    703: .Sq \&Fx ,
                    704: .Sq \&Nx ,
                    705: .Sq \&Ox ,
                    706: and
                    707: .Sq \&Ux )
                    708: are callable.
                    709: .\" LIST-ITEM
                    710: .It
                    711: Some manuals use
                    712: .Sq \&Li
                    713: incorrectly by following it with a reserved character and expecting the
                    714: delimiter to render.  This is not supported.
                    715: .\" LIST-ITEM
                    716: .It
                    717: .Sq \&Cd
                    718: is callable.
                    719: .El
                    720: .\" SECTION
1.2       kristaps  721: .Sh SEE ALSO
                    722: .Xr mdoctree 1 ,
                    723: .Xr mdoclint 1 ,
                    724: .Xr mdocterm 1 ,
                    725: .Xr mdoc 3
                    726: .\" SECTION
                    727: .Sh AUTHORS
                    728: The
                    729: .Nm
                    730: utility was written by
1.6     ! kristaps  731: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
1.5       kristaps  732: .\" SECTION
                    733: .Sh CAVEATS
                    734: There are several ambiguous parts of mdoc.
                    735: .Pp
                    736: .Bl -dash -compact
                    737: .\" LIST-ITEM
                    738: .It
                    739: .Sq \&Fa
                    740: should be
                    741: .Sq \&Va
                    742: as function arguments are variables.
                    743: .\" LIST-ITEM
                    744: .It
                    745: .Sq \&Ft
                    746: should be
                    747: .Sq \&Vt
                    748: as function return types are still types.  Furthermore, the
                    749: .Sq \&Ft
                    750: should be removed and
                    751: .Sq \&Fo ,
                    752: which ostensibly follows it, should follow the same convention as
                    753: .Sq \&Va .
                    754: .\" LIST-ITEM
                    755: .It
                    756: .Sq \&Va
                    757: should formalise that only one or two arguments are acceptable: a
                    758: variable name and optional, preceeding type.
                    759: .\" LIST-ITEM
                    760: .It
                    761: .Sq \&Fd
                    762: is ambiguous.  It's commonly used to indicate an include file in the
                    763: synopsis section.
                    764: .Sq \&In
                    765: should be used, instead.
                    766: .\" LIST-ITEM
                    767: .It
                    768: Only the
                    769: .Sq \-literal
                    770: argument to
                    771: .Sq \&Bd
                    772: makes sense.  The remaining ones should be removed.
                    773: .\" LIST-ITEM
                    774: .It
                    775: The
                    776: .Sq \&Xo
                    777: and
                    778: .Sq \&Xc
                    779: macros should be deprecated.
                    780: .\" LIST-ITEM
                    781: .It
                    782: The
                    783: .Sq \&Dt
                    784: macro lacks clarity.  It should be absolutely clear which title will
                    785: render when formatting the manual page.
1.6     ! kristaps  786: .\" LIST-ITEM
        !           787: .It
        !           788: A
        !           789: .Sq \&Lx
        !           790: should be provided for Linux (\(`a la
        !           791: .Sq \&Ox ,
        !           792: .Sq \&Nx
        !           793: etc.).
1.5       kristaps  794: .El

CVSweb