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

Annotation of mandoc/mdoc.7, Revision 1.15

1.15    ! kristaps    1: .\" $Id: mdoc.7,v 1.14 2009/03/23 14:22:11 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
                     69: .Sq \&Bd \-literal
                     70: or
                     71: .Sq \&Bd \-unfilled .
                     72: .Pp
                     73: Tab characters
                     74: .Pq \et
                     75: are only acceptable when delimiting
                     76: .Sq \&Bl \-column
                     77: and in
                     78: .Sq \&Bd \-literal
                     79: or
                     80: .Sq \&Bd \-unfilled
                     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
                    118: .Sq \\
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,
                    128: .Sq \\* ,
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
                    135: .It \\(em
                    136: .Pq em-dash
                    137: .It \\(en
                    138: .Pq en-dash
                    139: .It \e-
                    140: .Pq hyphen
                    141: .It \\\\
                    142: .Pq back-slash
                    143: .It \e'
                    144: .Pq apostrophe
                    145: .It \e`
                    146: .Pq back-tick
                    147: .It \\
                    148: .Pq space
                    149: .It \\.
                    150: .Pq period
1.8       kristaps  151: .It \\(r!
                    152: .Pq upside-down exclamation
                    153: .It \\(r?
                    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.5       kristaps  160: .It \\(lh
                    161: .Pq left hand
                    162: .It \\(rh
                    163: .Pq right hand
1.9       kristaps  164: .It \\(Fo
1.7       kristaps  165: .Pq left guillemet
                    166: .It \\(Fc
                    167: .Pq right guillemet
1.9       kristaps  168: .It \\(fo
1.7       kristaps  169: .Pq left guilsing
                    170: .It \\(fc
                    171: .Pq right guilsing
1.1       kristaps  172: .It \\(rC
                    173: .Pq right brace
                    174: .It \\(lC
                    175: .Pq left brace
                    176: .It \\(ra
                    177: .Pq right angle
                    178: .It \\(la
                    179: .Pq left angle
                    180: .It \\(rB
                    181: .Pq right bracket
                    182: .It \\(lB
                    183: .Pq left bracket
                    184: .It \\q
                    185: .Pq double-quote
                    186: .It \\(lq
                    187: .Pq left double-quote
                    188: .It \\(Lq
                    189: .Pq left double-quote, deprecated
                    190: .It \\(rq
                    191: .Pq right double-quote
                    192: .It \\(Rq
                    193: .Pq right double-quote, deprecated
                    194: .It \\(oq
                    195: .Pq left single-quote
                    196: .It \\(aq
                    197: .Pq right single-quote
1.8       kristaps  198: .It \\(Bq
                    199: .Pq right low double-quote
                    200: .It \\(bq
                    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
                    207: .It \\(<-
                    208: .Pq left arrow
                    209: .It \\(->
                    210: .Pq right arrow
                    211: .It \\(ua
                    212: .Pq up arrow
                    213: .It \\(da
                    214: .Pq down arrow
1.5       kristaps  215: .It \\(<>
                    216: .Pq left-right arrow
                    217: .It \\(lA
                    218: .Pq left double-arrow
                    219: .It \\(rA
                    220: .Pq right double-arrow
                    221: .It \\(uA
                    222: .Pq up double-arrow
                    223: .It \\(dA
                    224: .Pq down double-arrow
                    225: .It \\(hA
                    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.9       kristaps  232: .It \\(es
                    233: .Pq empty set
                    234: .It \\(ca
                    235: .Pq intersection
                    236: .It \\(cu
                    237: .Pq union
                    238: .It \\(gr
                    239: .Pq gradient
                    240: .It \\(pd
                    241: .Pq partial differential
                    242: .It \\(ap
                    243: .Pq similarity
                    244: .It \\(=)
                    245: .Pq proper superset
                    246: .It \\((=
                    247: .Pq proper subset
                    248: .It \\(eq
                    249: .Pq equals
                    250: .It \\(di
                    251: .Pq division
                    252: .It \\(mu
                    253: .Pq multiplication
                    254: .It \\(pl
                    255: .Pq addition
                    256: .It \\(nm
                    257: .Pq not element
                    258: .It \\(mo
                    259: .Pq element
                    260: .It \\(Im
                    261: .Pq imaginary
                    262: .It \\(Re
                    263: .Pq real
                    264: .It \\(Ah
                    265: .Pq aleph
                    266: .It \\(te
                    267: .Pq existential quantifier
                    268: .It \\(fa
                    269: .Pq universal quantifier
                    270: .It \\(AN
                    271: .Pq logical AND
                    272: .It \\(OR
                    273: .Pq logical OR
                    274: .It \\(no
                    275: .Pq logical NOT
                    276: .It \\(st
                    277: .Pq such that
                    278: .It \\(tf
                    279: .Pq therefore
                    280: .It \\(~~
                    281: .Pq approximate
                    282: .It \\(~=
                    283: .Pq approximately equals
                    284: .It \\(=~
                    285: .Pq congruent
1.1       kristaps  286: .It \\(Gt
                    287: .Pq greater-than, deprecated
                    288: .It \\(Lt
                    289: .Pq less-than, deprecated
                    290: .It \\(<=
                    291: .Pq less-than-equal
                    292: .It \\(Le
                    293: .Pq less-than-equal, deprecated
                    294: .It \\(>=
                    295: .Pq greater-than-equal
                    296: .It \\(Ge
                    297: .Pq greater-than-equal
                    298: .It \\(==
                    299: .Pq equal
                    300: .It \\(!=
                    301: .Pq not equal
                    302: .It \\(Ne
                    303: .Pq not equal, deprecated
                    304: .It \\(if
                    305: .Pq infinity
                    306: .It \\(If
                    307: .Pq infinity, deprecated
                    308: .It \\(na
                    309: .Pq NaN , an extension
                    310: .It \\(Na
                    311: .Pq NaN, deprecated
                    312: .It \\(+-
                    313: .Pq plus-minus
                    314: .It \\(Pm
                    315: .Pq plus-minus, deprecated
                    316: .It \\(**
                    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.7       kristaps  323: .It \\(ss
                    324: .Pq German eszett
1.5       kristaps  325: .It \\(AE
                    326: .Pq upper-case AE
                    327: .It \\(ae
                    328: .Pq lower-case AE
                    329: .It \\(OE
                    330: .Pq upper-case OE
                    331: .It \\(oe
                    332: .Pq lower-case OE
1.7       kristaps  333: .It \\(ff
                    334: .Pq ff ligature
                    335: .It \\(fi
                    336: .Pq fi ligature
                    337: .It \\(fl
                    338: .Pq fl ligature
                    339: .It \\(Fi
                    340: .Pq ffi ligature
                    341: .It \\(Fl
                    342: .Pq ffl ligature
                    343: .El
                    344: .\" PARAGRAPH
                    345: .Pp
                    346: Diacritics and letters:
                    347: .Bl -tag -width 12n -offset "XXXX" -compact
                    348: .It \\(ga
                    349: .Pq grave accent
                    350: .It \\(aa
                    351: .Pq accute accent
1.8       kristaps  352: .It \\(a"
                    353: .Pq umlaut accent
1.7       kristaps  354: .It \\(ad
                    355: .Pq dieresis accent
                    356: .It \\(a~
                    357: .Pq tilde accent
                    358: .It \\(a^
                    359: .Pq circumflex accent
                    360: .It \\(ac
                    361: .Pq cedilla accent
                    362: .It \\(ad
                    363: .Pq dieresis accent
                    364: .It \\(ah
                    365: .Pq caron accent
                    366: .It \\(ao
                    367: .Pq ring accent
                    368: .It \\(ho
                    369: .Pq hook accent
                    370: .It \\(ab
                    371: .Pq breve accent
                    372: .It \\(a-
                    373: .Pq macron accent
                    374: .It \\(-D
                    375: .Pq upper-case eth
                    376: .It \\(Sd
                    377: .Pq lower-case eth
                    378: .It \\(TP
                    379: .Pq upper-case thorn
                    380: .It \\(Tp
                    381: .Pq lower-case thorn
1.5       kristaps  382: .It \\('A
                    383: .Pq upper-case acute A
                    384: .It \\('E
                    385: .Pq upper-case acute E
                    386: .It \\('I
                    387: .Pq upper-case acute I
                    388: .It \\('O
                    389: .Pq upper-case acute O
                    390: .It \\('U
                    391: .Pq upper-case acute U
                    392: .It \\('a
                    393: .Pq lower-case acute a
                    394: .It \\('e
                    395: .Pq lower-case acute e
                    396: .It \\('i
                    397: .Pq lower-case acute i
                    398: .It \\('o
                    399: .Pq lower-case acute o
                    400: .It \\('u
                    401: .Pq lower-case acute u
                    402: .It \\(`A
                    403: .Pq upper-case grave A
                    404: .It \\(`E
                    405: .Pq upper-case grave E
                    406: .It \\(`I
                    407: .Pq upper-case grave I
                    408: .It \\(`O
                    409: .Pq upper-case grave O
                    410: .It \\(`U
                    411: .Pq upper-case grave U
                    412: .It \\(`a
                    413: .Pq lower-case grave a
                    414: .It \\(`e
                    415: .Pq lower-case grave e
                    416: .It \\(`i
                    417: .Pq lower-case grave i
                    418: .It \\(`o
                    419: .Pq lower-case grave o
                    420: .It \\(`u
                    421: .Pq lower-case grave u
                    422: .It \\(~A
                    423: .Pq upper-case tilde A
                    424: .It \\(~N
                    425: .Pq upper-case tilde N
                    426: .It \\(~O
                    427: .Pq upper-case tilde O
                    428: .It \\(~a
                    429: .Pq lower-case tilde a
                    430: .It \\(~n
                    431: .Pq lower-case tilde n
                    432: .It \\(~o
                    433: .Pq lower-case tilde o
                    434: .It \\(:A
                    435: .Pq upper-case dieresis A
                    436: .It \\(:E
                    437: .Pq upper-case dieresis E
                    438: .It \\(:I
                    439: .Pq upper-case dieresis I
                    440: .It \\(:O
                    441: .Pq upper-case dieresis O
                    442: .It \\(:U
                    443: .Pq upper-case dieresis U
                    444: .It \\(:a
                    445: .Pq lower-case dieresis a
                    446: .It \\(:e
                    447: .Pq lower-case dieresis e
                    448: .It \\(:i
                    449: .Pq lower-case dieresis i
                    450: .It \\(:o
                    451: .Pq lower-case dieresis o
                    452: .It \\(:u
                    453: .Pq lower-case dieresis u
                    454: .It \\(:y
                    455: .Pq lower-case dieresis y
1.7       kristaps  456: .It \\(^A
                    457: .Pq upper-case circumflex A
                    458: .It \\(^E
                    459: .Pq upper-case circumflex E
                    460: .It \\(^I
                    461: .Pq upper-case circumflex I
                    462: .It \\(^O
                    463: .Pq upper-case circumflex O
                    464: .It \\(^U
                    465: .Pq upper-case circumflex U
                    466: .It \\(^a
                    467: .Pq lower-case circumflex a
                    468: .It \\(^e
                    469: .Pq lower-case circumflex e
                    470: .It \\(^i
                    471: .Pq lower-case circumflex i
                    472: .It \\(^o
                    473: .Pq lower-case circumflex o
                    474: .It \\(^u
                    475: .Pq lower-case circumflex u
                    476: .It \\(,C
                    477: .Pq upper-case cedilla C
                    478: .It \\(,c
                    479: .Pq lower-case cedilla c
                    480: .It \\(/L
                    481: .Pq upper-case stroke L
                    482: .It \\(/l
                    483: .Pq lower-case stroke l
                    484: .It \\(/O
                    485: .Pq upper-case stroke O
                    486: .It \\(/o
                    487: .Pq lower-case stroke o
                    488: .It \\(oA
                    489: .Pq upper-case ring A
                    490: .It \\(oa
                    491: .Pq lower-case ring a
                    492: .El
                    493: .\" PARAGRAPH
                    494: .Pp
                    495: Monetary:
                    496: .Bl -tag -width 12n -offset "XXXX" -compact
                    497: .It \\(Cs
                    498: .Pq Scandinavian
                    499: .It \\(Do
                    500: .Pq dollar
                    501: .It \\(Po
                    502: .Pq pound
                    503: .It \\(Ye
                    504: .Pq yen
                    505: .It \\(Fn
                    506: .Pq florin
                    507: .It \\(ct
                    508: .Pq cent
1.1       kristaps  509: .El
                    510: .\" PARAGRAPH
                    511: .Pp
                    512: Special symbols:
                    513: .Bl -tag -width 12n -offset "XXXX" -compact
1.9       kristaps  514: .It \\(de
                    515: .Pq degree
                    516: .It \\(ps
                    517: .Pq paragraph
                    518: .It \\(sc
                    519: .Pq section
                    520: .It \\(dg
                    521: .Pq dagger
                    522: .It \\(dd
                    523: .Pq double dagger
1.8       kristaps  524: .It \\(ci
                    525: .Pq circle
1.1       kristaps  526: .It \\(ba
                    527: .Pq bar
1.8       kristaps  528: .It \\(bb
                    529: .Pq broken bar
1.1       kristaps  530: .It \\(Ba
                    531: .Pq bar, deprecated
                    532: .It \\(co
                    533: .Pq copyright
1.5       kristaps  534: .It \\(rg
                    535: .Pq registered
                    536: .It \\(tm
                    537: .Pq trademarked
1.1       kristaps  538: .It \\&
                    539: .Pq non-breaking space
                    540: .It \\e
                    541: .Pq escape
                    542: .It \\(Am
                    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
                    701: .Sq \&It \-bullet ,
                    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
                    754: .Sq \&Op
                    755: may be broken by \&Oc as in the following example:
                    756: .Bd -literal -offset XXXX
                    757: \&.Oo
                    758: \&.Op Fl a Oc
                    759: .Ed
                    760: .Pp
                    761: In the above example, the scope of
                    762: .Sq \&Op
                    763: is technically broken by
                    764: .Sq \&Oc ,
                    765: however, due to the overwhelming existence of this sequence, it's
                    766: allowed.
1.1       kristaps  767: .\" SUB-SECTION
                    768: .Ss Block partial-explicit
                    769: Each of these contains at least a body and, in limited circumstances, a
                    770: head
                    771: .Pq So \&Fo Sc , So \&Eo Sc
                    772: and/or tail
                    773: .Pq So \&Ec Sc .
                    774: .Pp
                    775: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
                    776: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
                    777: .It \&.Ao    Ta    Yes   Ta    Yes    Ta    closed by \&.Ac
                    778: .It \&.Ac    Ta    Yes   Ta    Yes    Ta    opened by \&.Ao
                    779: .It \&.Bc    Ta    Yes   Ta    Yes    Ta    closed by \&.Bo
                    780: .It \&.Bo    Ta    Yes   Ta    Yes    Ta    opened by \&.Bc
                    781: .It \&.Pc    Ta    Yes   Ta    Yes    Ta    closed by \&.Po
                    782: .It \&.Po    Ta    Yes   Ta    Yes    Ta    opened by \&.Pc
                    783: .It \&.Do    Ta    Yes   Ta    Yes    Ta    closed by \&.Dc
                    784: .It \&.Dc    Ta    Yes   Ta    Yes    Ta    opened by \&.Do
                    785: .It \&.Xo    Ta    Yes   Ta    Yes    Ta    closed by \&.Xc
                    786: .It \&.Xc    Ta    Yes   Ta    Yes    Ta    opened by \&.Xo
                    787: .It \&.Bro   Ta    Yes   Ta    Yes    Ta    closed by \&.Brc
                    788: .It \&.Brc   Ta    Yes   Ta    Yes    Ta    opened by \&.Bro
                    789: .It \&.Oc    Ta    Yes   Ta    Yes    Ta    closed by \&.Oo
                    790: .It \&.Oo    Ta    Yes   Ta    Yes    Ta    opened by \&.Oc
                    791: .It \&.So    Ta    Yes   Ta    Yes    Ta    closed by \&.Sc
                    792: .It \&.Sc    Ta    Yes   Ta    Yes    Ta    opened by \&.So
                    793: .It \&.Fc    Ta    Yes   Ta    Yes    Ta    opened by \&.Fo
                    794: .It \&.Fo    Ta    \&No  Ta    \&No   Ta    closed by \&.Fc
                    795: .It \&.Ec    Ta    Yes   Ta    Yes    Ta    opened by \&.Eo
                    796: .It \&.Eo    Ta    Yes   Ta    Yes    Ta    closed by \&.Ec
                    797: .It \&.Qc    Ta    Yes   Ta    Yes    Ta    opened by \&.Oo
                    798: .It \&.Qo    Ta    Yes   Ta    Yes    Ta    closed by \&.Oc
1.2       kristaps  799: .It \&.Re    Ta    \&No  Ta    \&No   Ta    opened by \&.Rs
                    800: .It \&.Rs    Ta    \&No  Ta    \&No   Ta    closed by \&.Re
1.1       kristaps  801: .El
                    802: .\" SUB-SECTION
1.2       kristaps  803: .Ss In-line
1.3       kristaps  804: In-line macros have only text children.  If a number (or inequality) of
                    805: arguments is
                    806: .Pq n ,
                    807: then the macro accepts an arbitrary number of arguments.
1.2       kristaps  808: .Pp
                    809: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
                    810: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.3       kristaps  811: .It \&.Dd    Ta    \&No  Ta    \&No    Ta    >0
                    812: .It \&.Dt    Ta    \&No  Ta    \&No    Ta    n
                    813: .It \&.Os    Ta    \&No  Ta    \&No    Ta    n
1.2       kristaps  814: .It \&.Pp    Ta    \&No  Ta    \&No    Ta    0
1.3       kristaps  815: .It \&.Ad    Ta    Yes   Ta    Yes     Ta    n
                    816: .It \&.An    Ta    \&No  Ta    Yes     Ta    n
                    817: .It \&.Ar    Ta    Yes   Ta    Yes     Ta    n
                    818: .It \&.Cd    Ta    Yes   Ta    \&No    Ta    >0
                    819: .It \&.Cm    Ta    Yes   Ta    Yes     Ta    n
1.11      kristaps  820: .It \&.Dv    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  821: .It \&.Er    Ta    Yes   Ta    Yes     Ta    >0
1.11      kristaps  822: .It \&.Ev    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  823: .It \&.Ex    Ta    \&No  Ta    \&No    Ta    0
1.12      kristaps  824: .It \&.Fa    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  825: .It \&.Fd    Ta    \&No  Ta    \&No    Ta    >0
                    826: .It \&.Fl    Ta    Yes   Ta    Yes     Ta    n
                    827: .It \&.Fn    Ta    Yes   Ta    Yes     Ta    >0
                    828: .It \&.Ft    Ta    \&No  Ta    Yes     Ta    n
                    829: .It \&.Ic    Ta    Yes   Ta    Yes     Ta    >0
                    830: .It \&.In    Ta    \&No  Ta    \&No    Ta    n
1.11      kristaps  831: .It \&.Li    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  832: .It \&.Nd    Ta    \&No  Ta    \&No    Ta    n
                    833: .It \&.Nm    Ta    Yes   Ta    Yes     Ta    n
                    834: .It \&.Ot    Ta    \&No  Ta    \&No    Ta    n
                    835: .It \&.Pa    Ta    Yes   Ta    Yes     Ta    n
                    836: .It \&.Rv    Ta    \&No  Ta    \&No    Ta    0
                    837: .It \&.St    Ta    \&No  Ta    Yes     Ta    1
1.11      kristaps  838: .It \&.Va    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  839: .It \&.Vt    Ta    Yes   Ta    Yes     Ta    >0
                    840: .It \&.Xr    Ta    Yes   Ta    Yes     Ta    >0, <3
                    841: .It \&.%A    Ta    \&No  Ta    \&No    Ta    >0
                    842: .It \&.%B    Ta    \&No  Ta    \&No    Ta    >0
                    843: .It \&.%C    Ta    \&No  Ta    \&No    Ta    >0
                    844: .It \&.%D    Ta    \&No  Ta    \&No    Ta    >0
                    845: .It \&.%I    Ta    \&No  Ta    \&No    Ta    >0
                    846: .It \&.%J    Ta    \&No  Ta    \&No    Ta    >0
                    847: .It \&.%N    Ta    \&No  Ta    \&No    Ta    >0
                    848: .It \&.%O    Ta    \&No  Ta    \&No    Ta    >0
                    849: .It \&.%P    Ta    \&No  Ta    \&No    Ta    >0
                    850: .It \&.%R    Ta    \&No  Ta    \&No    Ta    >0
                    851: .It \&.%T    Ta    \&No  Ta    \&No    Ta    >0
                    852: .It \&.%V    Ta    \&No  Ta    \&No    Ta    >0
                    853: .It \&.At    Ta    Yes   Ta    Yes     Ta    1
                    854: .It \&.Bsx   Ta    Yes   Ta    Yes     Ta    n
                    855: .It \&.Bx    Ta    Yes   Ta    Yes     Ta    n
                    856: .It \&.Db    Ta    \&No  Ta    \&No    Ta    1
1.11      kristaps  857: .It \&.Em    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  858: .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n
                    859: .It \&.Ms    Ta    \&No  Ta    Yes     Ta    >0
                    860: .It \&.No    Ta    Yes   Ta    Yes     Ta    0
                    861: .It \&.Ns    Ta    Yes   Ta    Yes     Ta    0
                    862: .It \&.Nx    Ta    Yes   Ta    Yes     Ta    n
                    863: .It \&.Ox    Ta    Yes   Ta    Yes     Ta    n
                    864: .It \&.Pf    Ta    \&No  Ta    Yes     Ta    1
                    865: .It \&.Sm    Ta    \&No  Ta    \&No    Ta    1
                    866: .It \&.Sx    Ta    Yes   Ta    Yes     Ta    >0
                    867: .It \&.Sy    Ta    Yes   Ta    Yes     Ta    >0
                    868: .It \&.Tn    Ta    Yes   Ta    Yes     Ta    >0
                    869: .It \&.Ux    Ta    Yes   Ta    Yes     Ta    n
1.6       kristaps  870: .It \&.Dx    Ta    Yes   Ta    Yes     Ta    n
1.3       kristaps  871: .It \&.Bt    Ta    \&No  Ta    \&No    Ta    0
                    872: .It \&.Hf    Ta    \&No  Ta    \&No    Ta    n
                    873: .It \&.Fr    Ta    \&No  Ta    \&No    Ta    n
                    874: .It \&.Ud    Ta    \&No  Ta    \&No    Ta    0
                    875: .It \&.Lb    Ta    \&No  Ta    \&No    Ta    1
                    876: .It \&.Ap    Ta    Yes   Ta    Yes     Ta    0
                    877: .It \&.Lp    Ta    \&No  Ta    \&No    Ta    0
                    878: .It \&.Lk    Ta    \&No  Ta    Yes     Ta    >0
                    879: .It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0
1.6       kristaps  880: .It \&.Es    Ta    \&No  Ta    \&No    Ta    0
                    881: .It \&.En    Ta    \&No  Ta    \&No    Ta    0
1.1       kristaps  882: .El
1.6       kristaps  883: .Pp
                    884: The
                    885: .Sq \&Ot ,
                    886: .Sq \&Fr ,
                    887: .Sq \&Es
                    888: and
                    889: .Sq \&En ,
                    890: macros are obsolete.
1.2       kristaps  891: .\" SECTION
1.4       kristaps  892: .Sh COMPATIBILITY
                    893: The mdoc language was traditionally a
                    894: .Qq roff
                    895: macro package; most existing manuals were written with mdoc syntax
                    896: dictated by system-dependent roff installations.  This section documents
                    897: compatibility with these systems.
                    898: .Pp
                    899: .Bl -dash -compact
                    900: .\" LIST-ITEM
                    901: .It
1.5       kristaps  902: .Sq \&Fo
                    903: and
                    904: .Sq \&St
                    905: historically weren't always callable.  Both are now correctly callable.
                    906: .\" LIST-ITEM
                    907: .It
1.4       kristaps  908: .Sq \&It \-nested
                    909: is assumed for all lists: any list may be nested and
                    910: .Sq \-enum
                    911: lists will restart the sequence only for the sub-list.
                    912: .\" LIST-ITEM
                    913: .It
                    914: .Sq \&It \-column
                    915: syntax where column widths may be preceeded by other arguments (instead
                    916: of proceeded) is not supported.
                    917: .\" LIST-ITEM
                    918: .It
                    919: The
                    920: .Sq \&At
                    921: macro only accepts a single parameter.
                    922: .\" LIST-ITEM
                    923: .It
                    924: The system-name macros (
                    925: .Ns Sq \&At ,
                    926: .Sq \&Bsx ,
                    927: .Sq \&Bx ,
                    928: .Sq \&Fx ,
                    929: .Sq \&Nx ,
                    930: .Sq \&Ox ,
                    931: and
                    932: .Sq \&Ux )
                    933: are callable.
                    934: .\" LIST-ITEM
                    935: .It
                    936: Some manuals use
                    937: .Sq \&Li
                    938: incorrectly by following it with a reserved character and expecting the
                    939: delimiter to render.  This is not supported.
                    940: .\" LIST-ITEM
                    941: .It
                    942: .Sq \&Cd
                    943: is callable.
                    944: .El
                    945: .\" SECTION
1.2       kristaps  946: .Sh SEE ALSO
1.15    ! kristaps  947: .Xr mandoc 1
1.2       kristaps  948: .\" SECTION
                    949: .Sh AUTHORS
                    950: The
                    951: .Nm
                    952: utility was written by
1.6       kristaps  953: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
1.5       kristaps  954: .\" SECTION
                    955: .Sh CAVEATS
                    956: There are several ambiguous parts of mdoc.
                    957: .Pp
                    958: .Bl -dash -compact
                    959: .\" LIST-ITEM
                    960: .It
                    961: .Sq \&Fa
                    962: should be
                    963: .Sq \&Va
                    964: as function arguments are variables.
                    965: .\" LIST-ITEM
                    966: .It
                    967: .Sq \&Ft
                    968: should be
                    969: .Sq \&Vt
                    970: as function return types are still types.  Furthermore, the
                    971: .Sq \&Ft
                    972: should be removed and
                    973: .Sq \&Fo ,
                    974: which ostensibly follows it, should follow the same convention as
                    975: .Sq \&Va .
                    976: .\" LIST-ITEM
                    977: .It
                    978: .Sq \&Va
                    979: should formalise that only one or two arguments are acceptable: a
                    980: variable name and optional, preceeding type.
                    981: .\" LIST-ITEM
                    982: .It
                    983: .Sq \&Fd
                    984: is ambiguous.  It's commonly used to indicate an include file in the
                    985: synopsis section.
                    986: .Sq \&In
                    987: should be used, instead.
                    988: .\" LIST-ITEM
                    989: .It
                    990: Only the
                    991: .Sq \-literal
                    992: argument to
                    993: .Sq \&Bd
                    994: makes sense.  The remaining ones should be removed.
                    995: .\" LIST-ITEM
                    996: .It
                    997: The
                    998: .Sq \&Xo
                    999: and
                   1000: .Sq \&Xc
                   1001: macros should be deprecated.
                   1002: .\" LIST-ITEM
                   1003: .It
                   1004: The
                   1005: .Sq \&Dt
                   1006: macro lacks clarity.  It should be absolutely clear which title will
                   1007: render when formatting the manual page.
1.6       kristaps 1008: .\" LIST-ITEM
                   1009: .It
                   1010: A
                   1011: .Sq \&Lx
                   1012: should be provided for Linux (\(`a la
                   1013: .Sq \&Ox ,
                   1014: .Sq \&Nx
                   1015: etc.).
1.14      kristaps 1016: .\" LIST-ITEM
                   1017: .It
                   1018: There's no way to refer to references in
                   1019: .Sq \&Rs/Re
                   1020: blocks.
1.5       kristaps 1021: .El

CVSweb