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

Annotation of mandoc/mdoc.7, Revision 1.10

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

CVSweb