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

Annotation of mandoc/mdoc.7, Revision 1.16

1.16    ! kristaps    1: .\" $Id: mdoc.7,v 1.15 2009/03/23 16:02:56 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
1.15      kristaps   25: .Nd mdoc language reference
1.1       kristaps   26: .\" SECTION
                     27: .Sh DESCRIPTION
                     28: The
                     29: .Nm mdoc
                     30: language is used to format
                     31: .Bx
                     32: .Ux
1.13      kristaps   33: manuals.  In this reference document, we describe the syntax, ontology
                     34: and structure of the
                     35: .Nm
                     36: language.
                     37: .\" PARAGRAPH
                     38: .Pp
                     39: An
1.1       kristaps   40: .Nm
                     41: document follows simple rules:  lines beginning with the control
1.13      kristaps   42: character
1.1       kristaps   43: .Sq \.
                     44: are parsed for macros.  Other lines are interpreted within the scope of
1.13      kristaps   45: prior macros:
                     46: .Bd -literal -offset XXX
                     47: \&.Sh Macro lines change control state.
                     48: Other lines are interpreted within the current state.
                     49: .Ed
                     50: .\" PARAGRAPH
                     51: .Pp
                     52: Macros are two- or three-character sequences whose scope rules, rules
                     53: that dictate handling of subsequent-line or same-line arguments, are
                     54: governed by one of five classifications described in this document.
1.1       kristaps   55: .\" SECTION
1.13      kristaps   56: .Sh INPUT ENCODING
1.1       kristaps   57: .Nm
1.13      kristaps   58: documents may contain only graphable 7-bit ASCII characters, the space
                     59: character
1.1       kristaps   60: .Sq \  ,
                     61: and, in certain circumstances, the tab character
                     62: .Sq \et .
                     63: All manuals must have
                     64: .Sq \en
1.10      kristaps   65: line termination.
                     66: .Pp
                     67: The only time a blank line is acceptable is within
                     68: the context of
1.16    ! kristaps   69: .Sq \&.Bd \-literal
1.10      kristaps   70: or
1.16    ! kristaps   71: .Sq \&.Bd \-unfilled .
1.10      kristaps   72: .Pp
                     73: Tab characters
                     74: .Pq \et
                     75: are only acceptable when delimiting
1.16    ! kristaps   76: .Sq \&.Bl \-column
1.10      kristaps   77: and in
1.16    ! kristaps   78: .Sq \&.Bd \-literal
1.10      kristaps   79: or
1.16    ! kristaps   80: .Sq \&.Bd \-unfilled
1.10      kristaps   81: contexts.
1.1       kristaps   82: .\" SUB-SECTION
1.2       kristaps   83: .Ss Reserved Characters
                     84: Within a macro line, the following characters are reserved:
                     85: .Bl -tag -width 12n -offset XXXX -compact
1.1       kristaps   86: .It \&.
1.2       kristaps   87: .Pq period
1.1       kristaps   88: .It \&,
1.2       kristaps   89: .Pq comma
1.1       kristaps   90: .It \&:
1.2       kristaps   91: .Pq colon
1.1       kristaps   92: .It \&;
1.2       kristaps   93: .Pq semicolon
1.1       kristaps   94: .It \&(
1.2       kristaps   95: .Pq left-parenthesis
1.1       kristaps   96: .It \&)
1.2       kristaps   97: .Pq right-parenthesis
1.1       kristaps   98: .It \&[
1.2       kristaps   99: .Pq left-bracket
1.1       kristaps  100: .It \&]
1.2       kristaps  101: .Pq right-bracket
1.1       kristaps  102: .It \&?
1.2       kristaps  103: .Pq question
1.1       kristaps  104: .It \&!
1.5       kristaps  105: .Pq exclamation
1.1       kristaps  106: .El
1.5       kristaps  107: .\" PARAGRAPH
1.1       kristaps  108: .Pp
1.5       kristaps  109: Use of reserved characters is described in
                    110: .Sx Closure .
                    111: For general non-reserved use, characters must either be escaped with a
                    112: non-breaking space
1.1       kristaps  113: .Pq Sq \e&
1.5       kristaps  114: or, if applicable, an appropriate escape-sequence used.
1.1       kristaps  115: .\" SUB-SECTION
                    116: .Ss Special Characters
                    117: Special character sequences begin with the escape character
1.16    ! kristaps  118: .Sq \e
1.4       kristaps  119: followed by either an open-parenthesis
1.1       kristaps  120: .Sq \&(
                    121: for two-character sequences; an open-bracket
                    122: .Sq \&[
                    123: for n-character sequences (terminated at a close-bracket
                    124: .Sq \&] ) ;
                    125: or a single one-character sequence.
                    126: .Pp
                    127: Characters may alternatively be escaped by a slash-asterisk,
1.16    ! kristaps  128: .Sq \e* ,
1.4       kristaps  129: with the same combinations as described above.  This form is deprecated.
                    130: .Pp
                    131: The following is a table of all available escapes.
1.1       kristaps  132: .Pp
                    133: Grammatic:
                    134: .Bl -tag -width 12n -offset "XXXX" -compact
1.16    ! kristaps  135: .It \e(em
1.1       kristaps  136: .Pq em-dash
1.16    ! kristaps  137: .It \e(en
1.1       kristaps  138: .Pq en-dash
                    139: .It \e-
                    140: .Pq hyphen
1.16    ! kristaps  141: .It \e\e
1.1       kristaps  142: .Pq back-slash
                    143: .It \e'
                    144: .Pq apostrophe
                    145: .It \e`
                    146: .Pq back-tick
1.16    ! kristaps  147: .It \e
1.1       kristaps  148: .Pq space
1.16    ! kristaps  149: .It \e.
1.1       kristaps  150: .Pq period
1.16    ! kristaps  151: .It \e(r!
1.8       kristaps  152: .Pq upside-down exclamation
1.16    ! kristaps  153: .It \e(r?
1.8       kristaps  154: .Pq upside-down question
1.1       kristaps  155: .El
                    156: .\" PARAGRAPH
                    157: .Pp
                    158: Enclosures:
                    159: .Bl -tag -width 12n -offset "XXXX" -compact
1.16    ! kristaps  160: .It \e(lh
1.5       kristaps  161: .Pq left hand
1.16    ! kristaps  162: .It \e(rh
1.5       kristaps  163: .Pq right hand
1.16    ! kristaps  164: .It \e(Fo
1.7       kristaps  165: .Pq left guillemet
1.16    ! kristaps  166: .It \e(Fc
1.7       kristaps  167: .Pq right guillemet
1.16    ! kristaps  168: .It \e(fo
1.7       kristaps  169: .Pq left guilsing
1.16    ! kristaps  170: .It \e(fc
1.7       kristaps  171: .Pq right guilsing
1.16    ! kristaps  172: .It \e(rC
1.1       kristaps  173: .Pq right brace
1.16    ! kristaps  174: .It \e(lC
1.1       kristaps  175: .Pq left brace
1.16    ! kristaps  176: .It \e(ra
1.1       kristaps  177: .Pq right angle
1.16    ! kristaps  178: .It \e(la
1.1       kristaps  179: .Pq left angle
1.16    ! kristaps  180: .It \e(rB
1.1       kristaps  181: .Pq right bracket
1.16    ! kristaps  182: .It \e(lB
1.1       kristaps  183: .Pq left bracket
1.16    ! kristaps  184: .It \eq
1.1       kristaps  185: .Pq double-quote
1.16    ! kristaps  186: .It \e(lq
1.1       kristaps  187: .Pq left double-quote
1.16    ! kristaps  188: .It \e(Lq
1.1       kristaps  189: .Pq left double-quote, deprecated
1.16    ! kristaps  190: .It \e(rq
1.1       kristaps  191: .Pq right double-quote
1.16    ! kristaps  192: .It \e(Rq
1.1       kristaps  193: .Pq right double-quote, deprecated
1.16    ! kristaps  194: .It \e(oq
1.1       kristaps  195: .Pq left single-quote
1.16    ! kristaps  196: .It \e(aq
1.1       kristaps  197: .Pq right single-quote
1.16    ! kristaps  198: .It \e(Bq
1.8       kristaps  199: .Pq right low double-quote
1.16    ! kristaps  200: .It \e(bq
1.8       kristaps  201: .Pq right low single-quote
1.1       kristaps  202: .El
                    203: .\" PARAGRAPH
                    204: .Pp
                    205: Indicatives:
                    206: .Bl -tag -width 12n -offset "XXXX" -compact
1.16    ! kristaps  207: .It \e(<-
1.1       kristaps  208: .Pq left arrow
1.16    ! kristaps  209: .It \e(->
1.1       kristaps  210: .Pq right arrow
1.16    ! kristaps  211: .It \e(ua
1.1       kristaps  212: .Pq up arrow
1.16    ! kristaps  213: .It \e(da
1.1       kristaps  214: .Pq down arrow
1.16    ! kristaps  215: .It \e(<>
1.5       kristaps  216: .Pq left-right arrow
1.16    ! kristaps  217: .It \e(lA
1.5       kristaps  218: .Pq left double-arrow
1.16    ! kristaps  219: .It \e(rA
1.5       kristaps  220: .Pq right double-arrow
1.16    ! kristaps  221: .It \e(uA
1.5       kristaps  222: .Pq up double-arrow
1.16    ! kristaps  223: .It \e(dA
1.5       kristaps  224: .Pq down double-arrow
1.16    ! kristaps  225: .It \e(hA
1.5       kristaps  226: .Pq left-right double-arrow
1.1       kristaps  227: .El
                    228: .\" PARAGRAPH
                    229: .Pp
                    230: Mathematical:
                    231: .Bl -tag -width 12n -offset "XXXX" -compact
1.16    ! kristaps  232: .It \e(es
1.9       kristaps  233: .Pq empty set
1.16    ! kristaps  234: .It \e(ca
1.9       kristaps  235: .Pq intersection
1.16    ! kristaps  236: .It \e(cu
1.9       kristaps  237: .Pq union
1.16    ! kristaps  238: .It \e(gr
1.9       kristaps  239: .Pq gradient
1.16    ! kristaps  240: .It \e(pd
1.9       kristaps  241: .Pq partial differential
1.16    ! kristaps  242: .It \e(ap
1.9       kristaps  243: .Pq similarity
1.16    ! kristaps  244: .It \e(=)
1.9       kristaps  245: .Pq proper superset
1.16    ! kristaps  246: .It \e((=
1.9       kristaps  247: .Pq proper subset
1.16    ! kristaps  248: .It \e(eq
1.9       kristaps  249: .Pq equals
1.16    ! kristaps  250: .It \e(di
1.9       kristaps  251: .Pq division
1.16    ! kristaps  252: .It \e(mu
1.9       kristaps  253: .Pq multiplication
1.16    ! kristaps  254: .It \e(pl
1.9       kristaps  255: .Pq addition
1.16    ! kristaps  256: .It \e(nm
1.9       kristaps  257: .Pq not element
1.16    ! kristaps  258: .It \e(mo
1.9       kristaps  259: .Pq element
1.16    ! kristaps  260: .It \e(Im
1.9       kristaps  261: .Pq imaginary
1.16    ! kristaps  262: .It \e(Re
1.9       kristaps  263: .Pq real
1.16    ! kristaps  264: .It \e(Ah
1.9       kristaps  265: .Pq aleph
1.16    ! kristaps  266: .It \e(te
1.9       kristaps  267: .Pq existential quantifier
1.16    ! kristaps  268: .It \e(fa
1.9       kristaps  269: .Pq universal quantifier
1.16    ! kristaps  270: .It \e(AN
1.9       kristaps  271: .Pq logical AND
1.16    ! kristaps  272: .It \e(OR
1.9       kristaps  273: .Pq logical OR
1.16    ! kristaps  274: .It \e(no
1.9       kristaps  275: .Pq logical NOT
1.16    ! kristaps  276: .It \e(st
1.9       kristaps  277: .Pq such that
1.16    ! kristaps  278: .It \e(tf
1.9       kristaps  279: .Pq therefore
1.16    ! kristaps  280: .It \e(~~
1.9       kristaps  281: .Pq approximate
1.16    ! kristaps  282: .It \e(~=
1.9       kristaps  283: .Pq approximately equals
1.16    ! kristaps  284: .It \e(=~
1.9       kristaps  285: .Pq congruent
1.16    ! kristaps  286: .It \e(Gt
1.1       kristaps  287: .Pq greater-than, deprecated
1.16    ! kristaps  288: .It \e(Lt
1.1       kristaps  289: .Pq less-than, deprecated
1.16    ! kristaps  290: .It \e(<=
1.1       kristaps  291: .Pq less-than-equal
1.16    ! kristaps  292: .It \e(Le
1.1       kristaps  293: .Pq less-than-equal, deprecated
1.16    ! kristaps  294: .It \e(>=
1.1       kristaps  295: .Pq greater-than-equal
1.16    ! kristaps  296: .It \e(Ge
1.1       kristaps  297: .Pq greater-than-equal
1.16    ! kristaps  298: .It \e(==
1.1       kristaps  299: .Pq equal
1.16    ! kristaps  300: .It \e(!=
1.1       kristaps  301: .Pq not equal
1.16    ! kristaps  302: .It \e(Ne
1.1       kristaps  303: .Pq not equal, deprecated
1.16    ! kristaps  304: .It \e(if
1.1       kristaps  305: .Pq infinity
1.16    ! kristaps  306: .It \e(If
1.1       kristaps  307: .Pq infinity, deprecated
1.16    ! kristaps  308: .It \e(na
1.1       kristaps  309: .Pq NaN , an extension
1.16    ! kristaps  310: .It \e(Na
1.1       kristaps  311: .Pq NaN, deprecated
1.16    ! kristaps  312: .It \e(+-
1.1       kristaps  313: .Pq plus-minus
1.16    ! kristaps  314: .It \e(Pm
1.1       kristaps  315: .Pq plus-minus, deprecated
1.16    ! kristaps  316: .It \e(**
1.1       kristaps  317: .Pq asterisk
                    318: .El
                    319: .\" PARAGRAPH
                    320: .Pp
1.7       kristaps  321: Ligatures:
1.1       kristaps  322: .Bl -tag -width 12n -offset "XXXX" -compact
1.16    ! kristaps  323: .It \e(ss
1.7       kristaps  324: .Pq German eszett
1.16    ! kristaps  325: .It \e(AE
1.5       kristaps  326: .Pq upper-case AE
1.16    ! kristaps  327: .It \e(ae
1.5       kristaps  328: .Pq lower-case AE
1.16    ! kristaps  329: .It \e(OE
1.5       kristaps  330: .Pq upper-case OE
1.16    ! kristaps  331: .It \e(oe
1.5       kristaps  332: .Pq lower-case OE
1.16    ! kristaps  333: .It \e(ff
1.7       kristaps  334: .Pq ff ligature
1.16    ! kristaps  335: .It \e(fi
1.7       kristaps  336: .Pq fi ligature
1.16    ! kristaps  337: .It \e(fl
1.7       kristaps  338: .Pq fl ligature
1.16    ! kristaps  339: .It \e(Fi
1.7       kristaps  340: .Pq ffi ligature
1.16    ! kristaps  341: .It \e(Fl
1.7       kristaps  342: .Pq ffl ligature
                    343: .El
                    344: .\" PARAGRAPH
                    345: .Pp
                    346: Diacritics and letters:
                    347: .Bl -tag -width 12n -offset "XXXX" -compact
1.16    ! kristaps  348: .It \e(ga
1.7       kristaps  349: .Pq grave accent
1.16    ! kristaps  350: .It \e(aa
1.7       kristaps  351: .Pq accute accent
1.16    ! kristaps  352: .It \e(a"
1.8       kristaps  353: .Pq umlaut accent
1.16    ! kristaps  354: .It \e(ad
1.7       kristaps  355: .Pq dieresis accent
1.16    ! kristaps  356: .It \e(a~
1.7       kristaps  357: .Pq tilde accent
1.16    ! kristaps  358: .It \e(a^
1.7       kristaps  359: .Pq circumflex accent
1.16    ! kristaps  360: .It \e(ac
1.7       kristaps  361: .Pq cedilla accent
1.16    ! kristaps  362: .It \e(ad
1.7       kristaps  363: .Pq dieresis accent
1.16    ! kristaps  364: .It \e(ah
1.7       kristaps  365: .Pq caron accent
1.16    ! kristaps  366: .It \e(ao
1.7       kristaps  367: .Pq ring accent
1.16    ! kristaps  368: .It \e(ho
1.7       kristaps  369: .Pq hook accent
1.16    ! kristaps  370: .It \e(ab
1.7       kristaps  371: .Pq breve accent
1.16    ! kristaps  372: .It \e(a-
1.7       kristaps  373: .Pq macron accent
1.16    ! kristaps  374: .It \e(-D
1.7       kristaps  375: .Pq upper-case eth
1.16    ! kristaps  376: .It \e(Sd
1.7       kristaps  377: .Pq lower-case eth
1.16    ! kristaps  378: .It \e(TP
1.7       kristaps  379: .Pq upper-case thorn
1.16    ! kristaps  380: .It \e(Tp
1.7       kristaps  381: .Pq lower-case thorn
1.16    ! kristaps  382: .It \e('A
1.5       kristaps  383: .Pq upper-case acute A
1.16    ! kristaps  384: .It \e('E
1.5       kristaps  385: .Pq upper-case acute E
1.16    ! kristaps  386: .It \e('I
1.5       kristaps  387: .Pq upper-case acute I
1.16    ! kristaps  388: .It \e('O
1.5       kristaps  389: .Pq upper-case acute O
1.16    ! kristaps  390: .It \e('U
1.5       kristaps  391: .Pq upper-case acute U
1.16    ! kristaps  392: .It \e('a
1.5       kristaps  393: .Pq lower-case acute a
1.16    ! kristaps  394: .It \e('e
1.5       kristaps  395: .Pq lower-case acute e
1.16    ! kristaps  396: .It \e('i
1.5       kristaps  397: .Pq lower-case acute i
1.16    ! kristaps  398: .It \e('o
1.5       kristaps  399: .Pq lower-case acute o
1.16    ! kristaps  400: .It \e('u
1.5       kristaps  401: .Pq lower-case acute u
1.16    ! kristaps  402: .It \e(`A
1.5       kristaps  403: .Pq upper-case grave A
1.16    ! kristaps  404: .It \e(`E
1.5       kristaps  405: .Pq upper-case grave E
1.16    ! kristaps  406: .It \e(`I
1.5       kristaps  407: .Pq upper-case grave I
1.16    ! kristaps  408: .It \e(`O
1.5       kristaps  409: .Pq upper-case grave O
1.16    ! kristaps  410: .It \e(`U
1.5       kristaps  411: .Pq upper-case grave U
1.16    ! kristaps  412: .It \e(`a
1.5       kristaps  413: .Pq lower-case grave a
1.16    ! kristaps  414: .It \e(`e
1.5       kristaps  415: .Pq lower-case grave e
1.16    ! kristaps  416: .It \e(`i
1.5       kristaps  417: .Pq lower-case grave i
1.16    ! kristaps  418: .It \e(`o
1.5       kristaps  419: .Pq lower-case grave o
1.16    ! kristaps  420: .It \e(`u
1.5       kristaps  421: .Pq lower-case grave u
1.16    ! kristaps  422: .It \e(~A
1.5       kristaps  423: .Pq upper-case tilde A
1.16    ! kristaps  424: .It \e(~N
1.5       kristaps  425: .Pq upper-case tilde N
1.16    ! kristaps  426: .It \e(~O
1.5       kristaps  427: .Pq upper-case tilde O
1.16    ! kristaps  428: .It \e(~a
1.5       kristaps  429: .Pq lower-case tilde a
1.16    ! kristaps  430: .It \e(~n
1.5       kristaps  431: .Pq lower-case tilde n
1.16    ! kristaps  432: .It \e(~o
1.5       kristaps  433: .Pq lower-case tilde o
1.16    ! kristaps  434: .It \e(:A
1.5       kristaps  435: .Pq upper-case dieresis A
1.16    ! kristaps  436: .It \e(:E
1.5       kristaps  437: .Pq upper-case dieresis E
1.16    ! kristaps  438: .It \e(:I
1.5       kristaps  439: .Pq upper-case dieresis I
1.16    ! kristaps  440: .It \e(:O
1.5       kristaps  441: .Pq upper-case dieresis O
1.16    ! kristaps  442: .It \e(:U
1.5       kristaps  443: .Pq upper-case dieresis U
1.16    ! kristaps  444: .It \e(:a
1.5       kristaps  445: .Pq lower-case dieresis a
1.16    ! kristaps  446: .It \e(:e
1.5       kristaps  447: .Pq lower-case dieresis e
1.16    ! kristaps  448: .It \e(:i
1.5       kristaps  449: .Pq lower-case dieresis i
1.16    ! kristaps  450: .It \e(:o
1.5       kristaps  451: .Pq lower-case dieresis o
1.16    ! kristaps  452: .It \e(:u
1.5       kristaps  453: .Pq lower-case dieresis u
1.16    ! kristaps  454: .It \e(:y
1.5       kristaps  455: .Pq lower-case dieresis y
1.16    ! kristaps  456: .It \e(^A
1.7       kristaps  457: .Pq upper-case circumflex A
1.16    ! kristaps  458: .It \e(^E
1.7       kristaps  459: .Pq upper-case circumflex E
1.16    ! kristaps  460: .It \e(^I
1.7       kristaps  461: .Pq upper-case circumflex I
1.16    ! kristaps  462: .It \e(^O
1.7       kristaps  463: .Pq upper-case circumflex O
1.16    ! kristaps  464: .It \e(^U
1.7       kristaps  465: .Pq upper-case circumflex U
1.16    ! kristaps  466: .It \e(^a
1.7       kristaps  467: .Pq lower-case circumflex a
1.16    ! kristaps  468: .It \e(^e
1.7       kristaps  469: .Pq lower-case circumflex e
1.16    ! kristaps  470: .It \e(^i
1.7       kristaps  471: .Pq lower-case circumflex i
1.16    ! kristaps  472: .It \e(^o
1.7       kristaps  473: .Pq lower-case circumflex o
1.16    ! kristaps  474: .It \e(^u
1.7       kristaps  475: .Pq lower-case circumflex u
1.16    ! kristaps  476: .It \e(,C
1.7       kristaps  477: .Pq upper-case cedilla C
1.16    ! kristaps  478: .It \e(,c
1.7       kristaps  479: .Pq lower-case cedilla c
1.16    ! kristaps  480: .It \e(/L
1.7       kristaps  481: .Pq upper-case stroke L
1.16    ! kristaps  482: .It \e(/l
1.7       kristaps  483: .Pq lower-case stroke l
1.16    ! kristaps  484: .It \e(/O
1.7       kristaps  485: .Pq upper-case stroke O
1.16    ! kristaps  486: .It \e(/o
1.7       kristaps  487: .Pq lower-case stroke o
1.16    ! kristaps  488: .It \e(oA
1.7       kristaps  489: .Pq upper-case ring A
1.16    ! kristaps  490: .It \e(oa
1.7       kristaps  491: .Pq lower-case ring a
                    492: .El
                    493: .\" PARAGRAPH
                    494: .Pp
                    495: Monetary:
                    496: .Bl -tag -width 12n -offset "XXXX" -compact
1.16    ! kristaps  497: .It \e(Cs
1.7       kristaps  498: .Pq Scandinavian
1.16    ! kristaps  499: .It \e(Do
1.7       kristaps  500: .Pq dollar
1.16    ! kristaps  501: .It \e(Po
1.7       kristaps  502: .Pq pound
1.16    ! kristaps  503: .It \e(Ye
1.7       kristaps  504: .Pq yen
1.16    ! kristaps  505: .It \e(Fn
1.7       kristaps  506: .Pq florin
1.16    ! kristaps  507: .It \e(ct
1.7       kristaps  508: .Pq cent
1.1       kristaps  509: .El
                    510: .\" PARAGRAPH
                    511: .Pp
                    512: Special symbols:
                    513: .Bl -tag -width 12n -offset "XXXX" -compact
1.16    ! kristaps  514: .It \e(de
1.9       kristaps  515: .Pq degree
1.16    ! kristaps  516: .It \e(ps
1.9       kristaps  517: .Pq paragraph
1.16    ! kristaps  518: .It \e(sc
1.9       kristaps  519: .Pq section
1.16    ! kristaps  520: .It \e(dg
1.9       kristaps  521: .Pq dagger
1.16    ! kristaps  522: .It \e(dd
1.9       kristaps  523: .Pq double dagger
1.16    ! kristaps  524: .It \e(ci
1.8       kristaps  525: .Pq circle
1.16    ! kristaps  526: .It \e(ba
1.1       kristaps  527: .Pq bar
1.16    ! kristaps  528: .It \e(bb
1.8       kristaps  529: .Pq broken bar
1.16    ! kristaps  530: .It \e(Ba
1.1       kristaps  531: .Pq bar, deprecated
1.16    ! kristaps  532: .It \e(co
1.1       kristaps  533: .Pq copyright
1.16    ! kristaps  534: .It \e(rg
1.5       kristaps  535: .Pq registered
1.16    ! kristaps  536: .It \e(tm
1.5       kristaps  537: .Pq trademarked
1.16    ! kristaps  538: .It \e&
1.1       kristaps  539: .Pq non-breaking space
1.16    ! kristaps  540: .It \ee
1.1       kristaps  541: .Pq escape
1.16    ! kristaps  542: .It \e(Am
1.1       kristaps  543: .Pq ampersand, deprecated
                    544: .El
                    545: .\" SECTION
1.2       kristaps  546: .Sh ONTOLOGY
1.13      kristaps  547: Macros are classified in an ontology described by their scope rules.
                    548: Some macros are allowed to deviate from their classifications to
                    549: preserve backward-compatibility with old macro combinations still found
                    550: in the manual corpus.  These are specifically noted on a per-macro
                    551: basis.
1.4       kristaps  552: .\" SUB-SECTION
                    553: .Ss Scope
1.2       kristaps  554: .Bl -inset
1.1       kristaps  555: .\" LIST-ITEM
                    556: .It Em Block
1.2       kristaps  557: macros enclose other block macros, in-line macros or text, and
1.4       kristaps  558: may span multiple lines.
1.2       kristaps  559: .Bl -inset -offset XXXX
1.1       kristaps  560: .\" LIST-ITEM
                    561: .It Em Full-block
1.5       kristaps  562: macros always span multiple lines.  They consist of zero or
1.2       kristaps  563: more
1.1       kristaps  564: .Qq heads ,
1.5       kristaps  565: subsequent macros or text on the same line following invocation; an
                    566: optional
1.1       kristaps  567: .Qq body ,
                    568: which spans subsequent lines of text or macros; and an optional
                    569: .Qq tail ,
                    570: macros or text on the same line following closure.
                    571: .\" LIST-ITEM
                    572: .It Em Partial-block
1.5       kristaps  573: macros may span multiple lines.  They consists of a optional
1.1       kristaps  574: .Qq head ,
                    575: text immediately following invocation; always a
                    576: .Qq body ,
                    577: text or macros following the head on the same and subsequent lines; and
                    578: optionally a
                    579: .Qq tail ,
                    580: text immediately following closure.
                    581: .\" LIST-ITEM
                    582: .It Em In-line
1.4       kristaps  583: macros may only enclose text and span at most a single line.
                    584: .El
                    585: .El
                    586: .\" SUB-SECTION
                    587: .Ss Closure
                    588: Closure of a macro's scope depends first on its classification, then
                    589: on whether it's parsable.  In this table,
                    590: .Sq BFE
                    591: refers to block full-explicit and so on.
                    592: .\" PARAGRAPH
                    593: .Pp
                    594: .Bl -tag -width 12n -offset XXXX -compact
                    595: .It BPE , BFE
                    596: corresponding explicit closure macro
                    597: .It BFI
                    598: end-of-file or a corresponding implicit closure macro
                    599: .It BPI
                    600: end-of-line (body may be closed by >0 space-separated
                    601: .Sx Reserved Characters ,
                    602: although block scope will still be open)
                    603: .It INL
                    604: end-of-line
1.1       kristaps  605: .El
1.4       kristaps  606: .\" PARAGRAPH
                    607: .Pp
                    608: If a macro (block or in-line) is parsable, it may also be closed out by
                    609: one of the following scenarios (unless specifically noted otherwise):
                    610: .\" PARAGRAPH
                    611: .Pp
                    612: .Bl -dash -offset XXXX -compact
                    613: .It
                    614: a sequence of >0 space-separated
                    615: .Sx Reserved Characters ,
                    616: .It
                    617: another macro,
                    618: .It
                    619: end-of-line, or
                    620: .It
                    621: completion of a set number of arguments.
                    622: .El
                    623: .\" PARAGRAPH
                    624: .Pp
                    625: If >0 space-separated
                    626: .Sx Reserved Characters
                    627: are followed by non-reserved characters, the behaviour differs per
                    628: macro.  In general, scope of the macro is closed and re-opened:
                    629: subsequent tokens are interpreted as if the scope had just been opened.
                    630: In other circumstances, scope is simply closed out.
1.1       kristaps  631: .\" SECTION
1.2       kristaps  632: .Sh SYNTAX
1.3       kristaps  633: Macros are generally two and at times three characters in length.  The
                    634: syntax of macro invocation depends on its classification.
1.2       kristaps  635: .Qq \-arg
                    636: refers to the macro arguments (which may contain zero or more values).
                    637: In these illustrations,
                    638: .Sq \&.Yo
                    639: opens the scope of a macro, and if specified,
                    640: .Sq \&.Yc
                    641: closes it out (closure may be implicit at end-of-line or end-of-file).
1.4       kristaps  642: .\" PARAGRAPH
1.2       kristaps  643: .Pp
1.4       kristaps  644: Block full-explicit (may contain head, body, tail).
1.2       kristaps  645: .Bd -literal -offset XXXX
1.4       kristaps  646: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
                    647: \(lBbody...\(rB
                    648: \&.Yc \(lBtail...\(rB
1.2       kristaps  649: .Ed
1.4       kristaps  650: .\" PARAGRAPH
1.2       kristaps  651: .Pp
1.4       kristaps  652: Block full-implicit (may contain zero or more heads, body, no tail).
1.2       kristaps  653: .Bd -literal -offset XXXX
1.4       kristaps  654: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
                    655: \(lBbody...\(rB
1.2       kristaps  656: \&.Yc
                    657: .Ed
1.4       kristaps  658: .\" PARAGRAPH
1.2       kristaps  659: .Pp
1.4       kristaps  660: Block partial-explicit (may contain head, multi-line body, tail).
1.2       kristaps  661: .Bd -literal -offset XXXX
                    662: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
1.4       kristaps  663: \(lBbody...\(rB
                    664: \&.Yc \(lBtail...\(rB
1.2       kristaps  665:
                    666: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
1.4       kristaps  667: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2       kristaps  668: .Ed
1.4       kristaps  669: .\" PARAGRAPH
1.2       kristaps  670: .Pp
1.4       kristaps  671: Block partial-implicit (no head, body, no tail).  Note that the body
                    672: section may be followed by zero or more
                    673: .Sx Reserved Words .
                    674: These are in the block scope, but not in the body scope.
1.2       kristaps  675: .Bd -literal -offset XXXX
1.4       kristaps  676: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
1.2       kristaps  677: .Ed
1.4       kristaps  678: .\" PARAGRAPH
1.2       kristaps  679: .Pp
1.4       kristaps  680: In-lines have \(>=0 scoped arguments.
1.2       kristaps  681: .Bd -literal -offset XXX
1.4       kristaps  682: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
1.2       kristaps  683:
                    684: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
                    685: .Ed
                    686: .\"
1.1       kristaps  687: .Sh MACROS
                    688: This section contains a complete list of all
                    689: .Nm
1.2       kristaps  690: macros, arranged ontologically.  A
1.1       kristaps  691: .Qq callable
                    692: macro is may be invoked subsequent to the initial macro-line macro.  A
                    693: .Qq parsable
1.2       kristaps  694: macro may be followed by further (ostensibly callable) macros.
1.1       kristaps  695: .\" SUB-SECTION
                    696: .Ss Block full-implicit
                    697: The head of these macros follows invocation; the body is the content of
                    698: subsequent lines prior to closure.  None of these macros have tails;
                    699: some
                    700: .Po
1.16    ! kristaps  701: .Sq \&.It \-bullet ,
1.1       kristaps  702: .Sq \-hyphen ,
                    703: .Sq \-dash ,
1.2       kristaps  704: .Sq \-enum ,
                    705: .Sq \-item
1.1       kristaps  706: .Pc
                    707: don't have heads.
                    708: .Pp
                    709: .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
                    710: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
                    711: .It \&.Sh    Ta    \&No    Ta    \&No    Ta    \&.Sh
                    712: .It \&.Ss    Ta    \&No    Ta    \&No    Ta    \&.Sh, \&.Ss
                    713: .It \&.It    Ta    \&No    Ta    Yes     Ta    \&.It, \&.El
                    714: .El
                    715: .\" SUB-SECTION
                    716: .Ss Block full-explicit
                    717: None of these macros are callable or parsed.  The last column indicates
                    718: the explicit scope rules.  All contains bodies, some may contain heads
                    719: .Pq So \&Bf Sc .
                    720: .Pp
                    721: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
                    722: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    723: .It \&.Bd    Ta    \&No    Ta    \&No    Ta    closed by \&.Ed
                    724: .It \&.Ed    Ta    \&No    Ta    \&No    Ta    opened by \&.Bd
                    725: .It \&.Bl    Ta    \&No    Ta    \&No    Ta    closed by \&.El
                    726: .It \&.El    Ta    \&No    Ta    \&No    Ta    opened by \&.Bl
                    727: .It \&.Bf    Ta    \&No    Ta    \&No    Ta    closed by \&.Ef
                    728: .It \&.Ef    Ta    \&No    Ta    \&No    Ta    opened by \&.Bf
1.2       kristaps  729: .It \&.Bk    Ta    \&No    Ta    \&No    Ta    closed by \&.Ek
                    730: .It \&.Ek    Ta    \&No    Ta    \&No    Ta    opened by \&.Bk
1.1       kristaps  731: .El
                    732: .\" SUB-SECTION
                    733: .Ss Block partial-implicit
                    734: All of these are callable and parsed for further macros.  Their scopes
                    735: close at the invocation's end-of-line.
                    736: .Pp
                    737: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
                    738: .It Em Macro Ta Em Callable Ta Em Parsable
                    739: .It \&.Aq    Ta    Yes   Ta    Yes
                    740: .It \&.Op    Ta    Yes   Ta    Yes
                    741: .It \&.Bq    Ta    Yes   Ta    Yes
                    742: .It \&.Dq    Ta    Yes   Ta    Yes
                    743: .It \&.Pq    Ta    Yes   Ta    Yes
                    744: .It \&.Qq    Ta    Yes   Ta    Yes
                    745: .It \&.Sq    Ta    Yes   Ta    Yes
                    746: .It \&.Brq   Ta    Yes   Ta    Yes
1.2       kristaps  747: .It \&.D1    Ta    \&No  Ta    \&Yes
                    748: .It \&.Dl    Ta    \&No  Ta    Yes
                    749: .It \&.Ql    Ta    Yes   Ta    Yes
1.1       kristaps  750: .El
1.13      kristaps  751: .\" PARAGRAPH
                    752: .Pp
                    753: The
1.16    ! kristaps  754: .Sq \&.Op
        !           755: may be broken by
        !           756: .Sq \&.Oc
        !           757: as in the following example:
1.13      kristaps  758: .Bd -literal -offset XXXX
                    759: \&.Oo
                    760: \&.Op Fl a Oc
                    761: .Ed
                    762: .Pp
                    763: In the above example, the scope of
1.16    ! kristaps  764: .Sq \&.Op
1.13      kristaps  765: is technically broken by
1.16    ! kristaps  766: .Sq \&.Oc ,
1.13      kristaps  767: however, due to the overwhelming existence of this sequence, it's
                    768: allowed.
1.1       kristaps  769: .\" SUB-SECTION
                    770: .Ss Block partial-explicit
                    771: Each of these contains at least a body and, in limited circumstances, a
                    772: head
1.16    ! kristaps  773: .Pq So \&.Fo Sc , So \&.Eo Sc
1.1       kristaps  774: and/or tail
1.16    ! kristaps  775: .Pq So \&.Ec Sc .
1.1       kristaps  776: .Pp
                    777: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
                    778: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    779: .It \&.Ao    Ta    Yes   Ta    Yes    Ta    closed by \&.Ac
                    780: .It \&.Ac    Ta    Yes   Ta    Yes    Ta    opened by \&.Ao
                    781: .It \&.Bc    Ta    Yes   Ta    Yes    Ta    closed by \&.Bo
                    782: .It \&.Bo    Ta    Yes   Ta    Yes    Ta    opened by \&.Bc
                    783: .It \&.Pc    Ta    Yes   Ta    Yes    Ta    closed by \&.Po
                    784: .It \&.Po    Ta    Yes   Ta    Yes    Ta    opened by \&.Pc
                    785: .It \&.Do    Ta    Yes   Ta    Yes    Ta    closed by \&.Dc
                    786: .It \&.Dc    Ta    Yes   Ta    Yes    Ta    opened by \&.Do
                    787: .It \&.Xo    Ta    Yes   Ta    Yes    Ta    closed by \&.Xc
                    788: .It \&.Xc    Ta    Yes   Ta    Yes    Ta    opened by \&.Xo
                    789: .It \&.Bro   Ta    Yes   Ta    Yes    Ta    closed by \&.Brc
                    790: .It \&.Brc   Ta    Yes   Ta    Yes    Ta    opened by \&.Bro
                    791: .It \&.Oc    Ta    Yes   Ta    Yes    Ta    closed by \&.Oo
                    792: .It \&.Oo    Ta    Yes   Ta    Yes    Ta    opened by \&.Oc
                    793: .It \&.So    Ta    Yes   Ta    Yes    Ta    closed by \&.Sc
                    794: .It \&.Sc    Ta    Yes   Ta    Yes    Ta    opened by \&.So
                    795: .It \&.Fc    Ta    Yes   Ta    Yes    Ta    opened by \&.Fo
                    796: .It \&.Fo    Ta    \&No  Ta    \&No   Ta    closed by \&.Fc
                    797: .It \&.Ec    Ta    Yes   Ta    Yes    Ta    opened by \&.Eo
                    798: .It \&.Eo    Ta    Yes   Ta    Yes    Ta    closed by \&.Ec
                    799: .It \&.Qc    Ta    Yes   Ta    Yes    Ta    opened by \&.Oo
                    800: .It \&.Qo    Ta    Yes   Ta    Yes    Ta    closed by \&.Oc
1.2       kristaps  801: .It \&.Re    Ta    \&No  Ta    \&No   Ta    opened by \&.Rs
                    802: .It \&.Rs    Ta    \&No  Ta    \&No   Ta    closed by \&.Re
1.1       kristaps  803: .El
                    804: .\" SUB-SECTION
1.2       kristaps  805: .Ss In-line
1.3       kristaps  806: In-line macros have only text children.  If a number (or inequality) of
                    807: arguments is
                    808: .Pq n ,
                    809: then the macro accepts an arbitrary number of arguments.
1.2       kristaps  810: .Pp
                    811: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
                    812: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.3       kristaps  813: .It \&.Dd    Ta    \&No  Ta    \&No    Ta    >0
                    814: .It \&.Dt    Ta    \&No  Ta    \&No    Ta    n
                    815: .It \&.Os    Ta    \&No  Ta    \&No    Ta    n
1.2       kristaps  816: .It \&.Pp    Ta    \&No  Ta    \&No    Ta    0
1.3       kristaps  817: .It \&.Ad    Ta    Yes   Ta    Yes     Ta    n
                    818: .It \&.An    Ta    \&No  Ta    Yes     Ta    n
                    819: .It \&.Ar    Ta    Yes   Ta    Yes     Ta    n
                    820: .It \&.Cd    Ta    Yes   Ta    \&No    Ta    >0
                    821: .It \&.Cm    Ta    Yes   Ta    Yes     Ta    n
1.11      kristaps  822: .It \&.Dv    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  823: .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0
1.11      kristaps  824: .It \&.Ev    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  825: .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0
1.12      kristaps  826: .It \&.Fa    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  827: .It \&.Fd    Ta    \&No  Ta    \&No    Ta    >0
                    828: .It \&.Fl    Ta    Yes   Ta    Yes     Ta    n
                    829: .It \&.Fn    Ta    Yes   Ta    Yes     Ta    >0
                    830: .It \&.Ft    Ta    \&No  Ta    Yes     Ta    n
                    831: .It \&.Ic    Ta    Yes   Ta    Yes     Ta    >0
                    832: .It \&.In    Ta    \&No  Ta    \&No    Ta    n
1.11      kristaps  833: .It \&.Li    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  834: .It \&.Nd    Ta    \&No  Ta    \&No    Ta    n
                    835: .It \&.Nm    Ta    Yes   Ta    Yes     Ta    n
                    836: .It \&.Ot    Ta    \&No  Ta    \&No    Ta    n
                    837: .It \&.Pa    Ta    Yes   Ta    Yes     Ta    n
                    838: .It \&.Rv    Ta    \&No  Ta    \&No    Ta    0
                    839: .It \&.St    Ta    \&No  Ta    Yes     Ta    1
1.11      kristaps  840: .It \&.Va    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  841: .It \&.Vt    Ta    Yes   Ta    Yes     Ta    >0
                    842: .It \&.Xr    Ta    Yes   Ta    Yes     Ta    >0, <3
                    843: .It \&.%A    Ta    \&No  Ta    \&No    Ta    >0
                    844: .It \&.%B    Ta    \&No  Ta    \&No    Ta    >0
                    845: .It \&.%C    Ta    \&No  Ta    \&No    Ta    >0
                    846: .It \&.%D    Ta    \&No  Ta    \&No    Ta    >0
                    847: .It \&.%I    Ta    \&No  Ta    \&No    Ta    >0
                    848: .It \&.%J    Ta    \&No  Ta    \&No    Ta    >0
                    849: .It \&.%N    Ta    \&No  Ta    \&No    Ta    >0
                    850: .It \&.%O    Ta    \&No  Ta    \&No    Ta    >0
                    851: .It \&.%P    Ta    \&No  Ta    \&No    Ta    >0
                    852: .It \&.%R    Ta    \&No  Ta    \&No    Ta    >0
                    853: .It \&.%T    Ta    \&No  Ta    \&No    Ta    >0
                    854: .It \&.%V    Ta    \&No  Ta    \&No    Ta    >0
                    855: .It \&.At    Ta    Yes   Ta    Yes     Ta    1
                    856: .It \&.Bsx   Ta    Yes   Ta    Yes     Ta    n
                    857: .It \&.Bx    Ta    Yes   Ta    Yes     Ta    n
                    858: .It \&.Db    Ta    \&No  Ta    \&No    Ta    1
1.11      kristaps  859: .It \&.Em    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  860: .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n
                    861: .It \&.Ms    Ta    \&No  Ta    Yes     Ta    >0
                    862: .It \&.No    Ta    Yes   Ta    Yes     Ta    0
                    863: .It \&.Ns    Ta    Yes   Ta    Yes     Ta    0
                    864: .It \&.Nx    Ta    Yes   Ta    Yes     Ta    n
                    865: .It \&.Ox    Ta    Yes   Ta    Yes     Ta    n
                    866: .It \&.Pf    Ta    \&No  Ta    Yes     Ta    1
                    867: .It \&.Sm    Ta    \&No  Ta    \&No    Ta    1
                    868: .It \&.Sx    Ta    Yes   Ta    Yes     Ta    >0
                    869: .It \&.Sy    Ta    Yes   Ta    Yes     Ta    >0
                    870: .It \&.Tn    Ta    Yes   Ta    Yes     Ta    >0
                    871: .It \&.Ux    Ta    Yes   Ta    Yes     Ta    n
1.6       kristaps  872: .It \&.Dx    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  873: .It \&.Bt    Ta    \&No  Ta    \&No    Ta    0
                    874: .It \&.Hf    Ta    \&No  Ta    \&No    Ta    n
                    875: .It \&.Fr    Ta    \&No  Ta    \&No    Ta    n
                    876: .It \&.Ud    Ta    \&No  Ta    \&No    Ta    0
                    877: .It \&.Lb    Ta    \&No  Ta    \&No    Ta    1
                    878: .It \&.Ap    Ta    Yes   Ta    Yes     Ta    0
                    879: .It \&.Lp    Ta    \&No  Ta    \&No    Ta    0
                    880: .It \&.Lk    Ta    \&No  Ta    Yes     Ta    >0
                    881: .It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0
1.6       kristaps  882: .It \&.Es    Ta    \&No  Ta    \&No    Ta    0
                    883: .It \&.En    Ta    \&No  Ta    \&No    Ta    0
1.1       kristaps  884: .El
1.6       kristaps  885: .Pp
                    886: The
1.16    ! kristaps  887: .Sq \&.Ot ,
        !           888: .Sq \&.Fr ,
        !           889: .Sq \&.Es
1.6       kristaps  890: and
1.16    ! kristaps  891: .Sq \&.En ,
1.6       kristaps  892: macros are obsolete.
1.2       kristaps  893: .\" SECTION
1.4       kristaps  894: .Sh COMPATIBILITY
                    895: The mdoc language was traditionally a
                    896: .Qq roff
                    897: macro package; most existing manuals were written with mdoc syntax
                    898: dictated by system-dependent roff installations.  This section documents
                    899: compatibility with these systems.
                    900: .Pp
                    901: .Bl -dash -compact
                    902: .\" LIST-ITEM
                    903: .It
1.16    ! kristaps  904: .Sq \&.Fo
1.5       kristaps  905: and
1.16    ! kristaps  906: .Sq \&.St
1.5       kristaps  907: historically weren't always callable.  Both are now correctly callable.
                    908: .\" LIST-ITEM
                    909: .It
1.16    ! kristaps  910: .Sq \&.It \-nested
1.4       kristaps  911: is assumed for all lists: any list may be nested and
                    912: .Sq \-enum
                    913: lists will restart the sequence only for the sub-list.
                    914: .\" LIST-ITEM
                    915: .It
1.16    ! kristaps  916: .Sq \&.It \-column
1.4       kristaps  917: syntax where column widths may be preceeded by other arguments (instead
                    918: of proceeded) is not supported.
                    919: .\" LIST-ITEM
                    920: .It
                    921: The
1.16    ! kristaps  922: .Sq \&.At
1.4       kristaps  923: macro only accepts a single parameter.
                    924: .\" LIST-ITEM
                    925: .It
                    926: The system-name macros (
1.16    ! kristaps  927: .Ns Sq \&.At ,
        !           928: .Sq \&.Bsx ,
        !           929: .Sq \&.Bx ,
        !           930: .Sq \&.Fx ,
        !           931: .Sq \&.Nx ,
        !           932: .Sq \&.Ox ,
1.4       kristaps  933: and
1.16    ! kristaps  934: .Sq \&.Ux )
1.4       kristaps  935: are callable.
                    936: .\" LIST-ITEM
                    937: .It
                    938: Some manuals use
1.16    ! kristaps  939: .Sq \&.Li
1.4       kristaps  940: incorrectly by following it with a reserved character and expecting the
                    941: delimiter to render.  This is not supported.
                    942: .\" LIST-ITEM
                    943: .It
1.16    ! kristaps  944: .Sq \&.Cd
1.4       kristaps  945: is callable.
                    946: .El
                    947: .\" SECTION
1.2       kristaps  948: .Sh SEE ALSO
1.15      kristaps  949: .Xr mandoc 1
1.2       kristaps  950: .\" SECTION
                    951: .Sh AUTHORS
                    952: The
                    953: .Nm
                    954: utility was written by
1.6       kristaps  955: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
1.5       kristaps  956: .\" SECTION
                    957: .Sh CAVEATS
                    958: There are several ambiguous parts of mdoc.
                    959: .Pp
                    960: .Bl -dash -compact
                    961: .\" LIST-ITEM
                    962: .It
1.16    ! kristaps  963: .Sq \&.Fa
1.5       kristaps  964: should be
1.16    ! kristaps  965: .Sq \&.Va
1.5       kristaps  966: as function arguments are variables.
                    967: .\" LIST-ITEM
                    968: .It
1.16    ! kristaps  969: .Sq \&.Ft
1.5       kristaps  970: should be
1.16    ! kristaps  971: .Sq \&.Vt
1.5       kristaps  972: as function return types are still types.  Furthermore, the
1.16    ! kristaps  973: .Sq \&.Ft
1.5       kristaps  974: should be removed and
1.16    ! kristaps  975: .Sq \&.Fo ,
1.5       kristaps  976: which ostensibly follows it, should follow the same convention as
1.16    ! kristaps  977: .Sq \&.Va .
1.5       kristaps  978: .\" LIST-ITEM
                    979: .It
1.16    ! kristaps  980: .Sq \&.Va
1.5       kristaps  981: should formalise that only one or two arguments are acceptable: a
                    982: variable name and optional, preceeding type.
                    983: .\" LIST-ITEM
                    984: .It
1.16    ! kristaps  985: .Sq \&.Fd
1.5       kristaps  986: is ambiguous.  It's commonly used to indicate an include file in the
                    987: synopsis section.
1.16    ! kristaps  988: .Sq \&.In
1.5       kristaps  989: should be used, instead.
                    990: .\" LIST-ITEM
                    991: .It
                    992: Only the
                    993: .Sq \-literal
                    994: argument to
1.16    ! kristaps  995: .Sq \&.Bd
1.5       kristaps  996: makes sense.  The remaining ones should be removed.
                    997: .\" LIST-ITEM
                    998: .It
                    999: The
1.16    ! kristaps 1000: .Sq \&.Xo
1.5       kristaps 1001: and
1.16    ! kristaps 1002: .Sq \&.Xc
1.5       kristaps 1003: macros should be deprecated.
                   1004: .\" LIST-ITEM
                   1005: .It
                   1006: The
1.16    ! kristaps 1007: .Sq \&.Dt
1.5       kristaps 1008: macro lacks clarity.  It should be absolutely clear which title will
                   1009: render when formatting the manual page.
1.6       kristaps 1010: .\" LIST-ITEM
                   1011: .It
                   1012: A
1.16    ! kristaps 1013: .Sq \&.Lx
1.6       kristaps 1014: should be provided for Linux (\(`a la
1.16    ! kristaps 1015: .Sq \&.Ox ,
        !          1016: .Sq \&.Nx
1.6       kristaps 1017: etc.).
1.14      kristaps 1018: .\" LIST-ITEM
                   1019: .It
                   1020: There's no way to refer to references in
1.16    ! kristaps 1021: .Sq \&.Rs/.Re
1.14      kristaps 1022: blocks.
1.5       kristaps 1023: .El

CVSweb