Annotation of mandoc/mdoc.7, Revision 1.43
1.43 ! kristaps 1: .\" $Id: mdoc.7,v 1.42 2009/07/13 07:23:07 kristaps Exp $
1.1 kristaps 2: .\"
1.23 kristaps 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.22 kristaps 6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
1.1 kristaps 8: .\"
1.22 kristaps 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 kristaps 16: .\"
17: .Dd $Mdocdate$
1.20 kristaps 18: .Dt MDOC 7
1.1 kristaps 19: .Os
1.43 ! kristaps 20: .\" SECTION---------------------------------------------
1.1 kristaps 21: .Sh NAME
22: .Nm mdoc
1.15 kristaps 23: .Nd mdoc language reference
1.43 ! kristaps 24: .\" SECTION---------------------------------------------
1.1 kristaps 25: .Sh DESCRIPTION
26: The
27: .Nm mdoc
28: language is used to format
29: .Bx
30: .Ux
1.43 ! kristaps 31: manuals. In this reference document, we describe its syntax, structure,
! 32: and usage. Our reference implementation is
1.28 kristaps 33: .Xr mandoc 1 .
34: The
35: .Sx COMPATIBILITY
36: section describes compatibility with
37: .Xr groff 1 .
1.43 ! kristaps 38: .\" PARAGRAPH------------
1.13 kristaps 39: .Pp
40: An
1.1 kristaps 41: .Nm
42: document follows simple rules: lines beginning with the control
1.13 kristaps 43: character
1.1 kristaps 44: .Sq \.
45: are parsed for macros. Other lines are interpreted within the scope of
1.13 kristaps 46: prior macros:
1.39 kristaps 47: .Bd -literal -offset indent
1.13 kristaps 48: \&.Sh Macro lines change control state.
49: Other lines are interpreted within the current state.
50: .Ed
1.43 ! kristaps 51: .\" SECTION---------------------------------------------
1.13 kristaps 52: .Sh INPUT ENCODING
1.1 kristaps 53: .Nm
1.13 kristaps 54: documents may contain only graphable 7-bit ASCII characters, the space
1.43 ! kristaps 55: character, and, in certain circumstances, the tab character. All
! 56: manuals must have
! 57: .Ux
1.10 kristaps 58: line termination.
1.43 ! kristaps 59: .\" SUB-SECTION----------------------
1.29 kristaps 60: .Ss Comments
1.43 ! kristaps 61: Text following a
! 62: .Sq \e" ,
! 63: whether in a macro or free-form text line, is ignored to the end of
! 64: line. A macro line with only a control character and comment escape,
! 65: .Sq \&.\e" ,
! 66: is also ignored.
! 67: .\" SUB-SECTION----------------------
1.2 kristaps 68: .Ss Reserved Characters
69: Within a macro line, the following characters are reserved:
1.39 kristaps 70: .Bl -tag -width Ds -offset indent -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.28 kristaps 91: .It \&|
92: .Pq vertical bar
1.1 kristaps 93: .El
1.43 ! kristaps 94: .\" PARAGRAPH------------
1.1 kristaps 95: .Pp
1.5 kristaps 96: Use of reserved characters is described in
1.43 ! kristaps 97: .Sx MACRO SYNTAX .
! 98: For general use in macro lines, these characters must either be escaped
! 99: with a non-breaking space
1.1 kristaps 100: .Pq Sq \e&
1.43 ! kristaps 101: or, if applicable, an appropriate escape sequence used.
! 102: .\" SUB-SECTION----------------------
1.1 kristaps 103: .Ss Special Characters
1.43 ! kristaps 104: Special characters may occur in both macro and free-form lines.
! 105: Sequences begin with the escape character
1.16 kristaps 106: .Sq \e
1.4 kristaps 107: followed by either an open-parenthesis
1.1 kristaps 108: .Sq \&(
109: for two-character sequences; an open-bracket
110: .Sq \&[
111: for n-character sequences (terminated at a close-bracket
112: .Sq \&] ) ;
1.43 ! kristaps 113: or a single one-character sequence. See
! 114: .Xr mandoc_char 1
! 115: for a complete list. Examples include
! 116: .Sq \e(em
! 117: .Pq em-dash
! 118: and
! 119: .Sq \ee
! 120: .Pq back-slash .
! 121: .\" PARAGRAPH------------
1.1 kristaps 122: .Pp
1.43 ! kristaps 123: An alternative escape sequence is
! 124: the slash-asterisk,
1.16 kristaps 125: .Sq \e* ,
1.43 ! kristaps 126: but this method is discouraged for compatibility reasons.
! 127: .\" PARAGRAPH------------
1.35 kristaps 128: .Pp
1.43 ! kristaps 129: Terms may
! 130: also be text-decorated using the
1.35 kristaps 131: .Sq \ef
1.43 ! kristaps 132: escape followed by an indicator: B (bold), I, (italic), or P and R
! 133: (Roman, or reset). This form is not recommended.
! 134: .\" SUB-SECTION----------------------
1.34 kristaps 135: .Ss Whitespace
1.43 ! kristaps 136: In general, consecutive blocks of whitespace are pruned from input.
! 137: These are later re-added, when applicable, by
1.34 kristaps 138: .Xr mandoc 1 .
1.43 ! kristaps 139: .\" PARAGRAPH------------
! 140: .Pp
! 141: Blank lines are permitted within
! 142: .Sq \&Bd \-literal
! 143: or
! 144: .Sq \&Bd \-unfilled
! 145: contexts. Tab characters are only acceptable when delimiting
! 146: .Sq \&Bl \-column
! 147: and in
! 148: .Sq \&Bd \-literal
! 149: or
! 150: .Sq \&Bd \-unfilled
! 151: contexts.
! 152: .\" SECTION---------------------------------------------
! 153: .Sh MANUAL STRUCTURE
1.33 kristaps 154: Each
155: .Nm
1.43 ! kristaps 156: document must begin with a document prologue, containing, in order,
! 157: .Sq \&Dd ,
! 158: .Sq \&Dt ,
1.33 kristaps 159: and
1.43 ! kristaps 160: .Sq \&Os
! 161: (using this manual as an example):
! 162: .Bd -literal -offset indent
! 163: \&.Dd $\&Mdocdate$
! 164: \&.Dt mdoc 7
! 165: \&.Os
! 166: \&.Sh NAME
! 167: \&.Nm mdoc
! 168: \&.Nd mdoc language reference
! 169: .Ed
! 170: .Pp
1.33 kristaps 171: Following these, the document body must begin with the NAME section
172: containing at least one
1.43 ! kristaps 173: .Sq \&Nm
! 174: followed by
! 175: .Sq \&Nd .
! 176: .\" PARAGRAPH------------
! 177: .Pp
! 178: Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
! 179: but non-compulsory.
! 180: .\" SUB-SECTION----------------------
! 181: .\" .Ss Classification
! 182: .\" Macros are classified by their scope rules: block full-explicit (BFE),
! 183: .\" block partial-explicit (BPE), block full-implicit (BFI), block
! 184: .\" partial-implicit (BPI), and in-line.
! 185: .\" SUB-SECTION----------------------
! 186: .\" .Ss Scope
! 187: .\" .Bl -inset
! 188: .\" .\" LIST-ITEM
! 189: .\" .It Em Block
! 190: .\" macros enclose other block macros, in-line macros or text, and
! 191: .\" may span multiple lines.
! 192: .\" .Bl -inset -offset indent
! 193: .\" .\" LIST-ITEM
! 194: .\" .It Em Full-block
! 195: .\" macros always span multiple lines. They consist of zero or
! 196: .\" more
! 197: .\" .Qq heads ,
! 198: .\" subsequent macros or text on the same line following invocation; an
! 199: .\" optional
! 200: .\" .Qq body ,
! 201: .\" which spans subsequent lines of text or macros; and an optional
! 202: .\" .Qq tail ,
! 203: .\" macros or text on the same line following closure.
! 204: .\" .\" LIST-ITEM
! 205: .\" .It Em Partial-block
! 206: .\" macros may span multiple lines. They consists of a optional
! 207: .\" .Qq head ,
! 208: .\" text immediately following invocation; always a
! 209: .\" .Qq body ,
! 210: .\" text or macros following the head on the same and subsequent lines; and
! 211: .\" optionally a
! 212: .\" .Qq tail ,
! 213: .\" text immediately following closure.
! 214: .\" .\" LIST-ITEM
! 215: .\" .It Em In-line
! 216: .\" macros may only enclose text and span at most a single line.
! 217: .\" .El
! 218: .\" .El
! 219: .\" SUB-SECTION----------------------
! 220: .\" .Ss Closure
! 221: .\" Closure of a macro's scope depends first on its classification, then
! 222: .\" on whether it's parsable. In this table,
! 223: .\" .Sq BFE
! 224: .\" refers to block full-explicit and so on.
! 225: .\" .\" PARAGRAPH------------
! 226: .\" .Pp
! 227: .\" .Bl -tag -width 12n -offset indent -compact
! 228: .\" .It BPE , BFE
! 229: .\" corresponding explicit closure macro
! 230: .\" .It BFI
! 231: .\" end-of-file or a corresponding implicit closure macro
! 232: .\" .It BPI
! 233: .\" end-of-line (body may be closed by >0 space-separated
! 234: .\" .Sx Reserved Characters ,
! 235: .\" although block scope will still be open)
! 236: .\" .It INL
! 237: .\" end-of-line
! 238: .\" .El
! 239: .\" PARAGRAPH------------
! 240: .\" .Pp
! 241: .\" If a macro (block or in-line) is parsable, it may also be closed out by
! 242: .\" one of the following scenarios (unless specifically noted otherwise):
! 243: .\" .\" PARAGRAPH------------
! 244: .\" .Pp
! 245: .\" .Bl -dash -offset indent -compact
! 246: .\" .It
! 247: .\" a sequence of >0 space-separated
! 248: .\" .Sx Reserved Characters ,
! 249: .\" .It
! 250: .\" another macro,
! 251: .\" .It
! 252: .\" end-of-line, or
! 253: .\" .It
! 254: .\" completion of a set number of arguments.
! 255: .\" .El
! 256: .\" PARAGRAPH------------
! 257: .\" .Pp
! 258: .\" If >0 space-separated
! 259: .\" .Sx Reserved Characters
! 260: .\" are followed by non-reserved characters, the behaviour differs per
! 261: .\" macro. In general, scope of the macro is closed and re-opened:
! 262: .\" subsequent tokens are interpreted as if the scope had just been opened.
! 263: .\" In other circumstances, scope is simply closed out.
! 264: .\" SECTION---------------------------------------------
! 265: .Sh MACRO SYNTAX
! 266: Every line beginning with the control character
! 267: .Sq \.
! 268: is processed for macros, two- or three-character semantic annotations.
! 269: .\" PARAGRAPH------------
1.4 kristaps 270: .Pp
1.43 ! kristaps 271: The syntax of macro depends on its classification. In this section,
! 272: .Sq \-arg
! 273: refers to macro arguments, which may be followed by zero or more
! 274: .Sq parm
! 275: parameters;
! 276: .Sq \&Yo
! 277: opens the scope of a macro; and if specified,
! 278: .Sq \&Yc
! 279: closes it out.
! 280: .\" PARAGRAPH------------
1.2 kristaps 281: .Pp
1.43 ! kristaps 282: The
! 283: .Em Callable
! 284: column indicates that the macro may be called subsequent to the initial
! 285: line-macro. The
! 286: .Qq Parsable
! 287: column indicates whether the macro may be followed by further
! 288: (ostensibly callable) macros. The
! 289: .Em Scope
! 290: column, if applicable, describes closure rules.
! 291: .\" SUB-SECTION----------------------
! 292: .Ss Block full-explicit
! 293: Multi-line scope closed by an explicit closing macro. All macros
! 294: contains bodies; only
! 295: .Pq Sq \&Bf
! 296: contains a head.
1.39 kristaps 297: .Bd -literal -offset indent
1.43 ! kristaps 298: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
1.4 kristaps 299: \(lBbody...\(rB
1.43 ! kristaps 300: \&.Yc
1.2 kristaps 301: .Ed
1.43 ! kristaps 302: .\" PARAGRAPH------------
1.2 kristaps 303: .Pp
1.43 ! kristaps 304: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
! 305: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
! 306: .It \&Bd Ta \&No Ta \&No Ta closed by \&Ed
! 307: .It \&Ed Ta \&No Ta \&No Ta opened by \&Bd
! 308: .It \&Bl Ta \&No Ta \&No Ta closed by \&El
! 309: .It \&El Ta \&No Ta \&No Ta opened by \&Bl
! 310: .It \&Bf Ta \&No Ta \&No Ta closed by \&Ef
! 311: .It \&Ef Ta \&No Ta \&No Ta opened by \&Bf
! 312: .It \&Bk Ta \&No Ta \&No Ta closed by \&Ek
! 313: .It \&Ek Ta \&No Ta \&No Ta opened by \&Bk
! 314: .El
! 315: .\" SUB-SECTION----------------------
! 316: .Ss Block full-implicit
! 317: Multi-line scope closed by end-of-file or implicitly by another macro.
! 318: All macros have bodies; some
! 319: .Po
! 320: .Sq \&It \-bullet ,
! 321: .Sq \-hyphen ,
! 322: .Sq \-dash ,
! 323: .Sq \-enum ,
! 324: .Sq \-item
! 325: .Pc
! 326: don't have heads, while
! 327: .Sq \&It \-column
! 328: may have multiple heads.
1.39 kristaps 329: .Bd -literal -offset indent
1.43 ! kristaps 330: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
1.4 kristaps 331: \(lBbody...\(rB
1.2 kristaps 332: .Ed
1.43 ! kristaps 333: .\" PARAGRAPH------------
1.2 kristaps 334: .Pp
1.43 ! kristaps 335: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
! 336: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
! 337: .It \&Nd Ta \&No Ta \&No Ta closed by \&Sh
! 338: .It \&Sh Ta \&No Ta \&No Ta closed by \&Sh
! 339: .It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss
! 340: .It \&It Ta \&No Ta Yes Ta closed by \&It, \&El
! 341: .El
! 342: .\" SUB-SECTION----------------------
! 343: .Ss Block partial-explicit
! 344: Like block full-explicit, but also with single-line scope. Each
! 345: has at least a body and, in limited circumstances, a head
! 346: .Pq So \&Fo Sc , So \&Eo Sc
! 347: and/or tail
! 348: .Pq So \&Ec Sc .
1.39 kristaps 349: .Bd -literal -offset indent
1.43 ! kristaps 350: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
1.4 kristaps 351: \(lBbody...\(rB
352: \&.Yc \(lBtail...\(rB
1.2 kristaps 353:
1.43 ! kristaps 354: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
1.4 kristaps 355: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2 kristaps 356: .Ed
1.43 ! kristaps 357: .\" PARAGRAPH------------
1.2 kristaps 358: .Pp
1.43 ! kristaps 359: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
1.1 kristaps 360: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
1.43 ! kristaps 361: .It \&Ao Ta Yes Ta Yes Ta closed by \&Ac
! 362: .It \&Ac Ta Yes Ta Yes Ta opened by \&Ao
! 363: .It \&Bc Ta Yes Ta Yes Ta closed by \&Bo
! 364: .It \&Bo Ta Yes Ta Yes Ta opened by \&Bc
! 365: .It \&Pc Ta Yes Ta Yes Ta closed by \&Po
! 366: .It \&Po Ta Yes Ta Yes Ta opened by \&Pc
! 367: .It \&Do Ta Yes Ta Yes Ta closed by \&Dc
! 368: .It \&Dc Ta Yes Ta Yes Ta opened by \&Do
! 369: .It \&Xo Ta Yes Ta Yes Ta closed by \&Xc
! 370: .It \&Xc Ta Yes Ta Yes Ta opened by \&Xo
! 371: .It \&Bro Ta Yes Ta Yes Ta closed by \&Brc
! 372: .It \&Brc Ta Yes Ta Yes Ta opened by \&Bro
! 373: .It \&Oc Ta Yes Ta Yes Ta closed by \&Oo
! 374: .It \&Oo Ta Yes Ta Yes Ta opened by \&Oc
! 375: .It \&So Ta Yes Ta Yes Ta closed by \&Sc
! 376: .It \&Sc Ta Yes Ta Yes Ta opened by \&So
! 377: .It \&Fc Ta Yes Ta Yes Ta opened by \&Fo
! 378: .It \&Fo Ta \&No Ta \&No Ta closed by \&Fc
! 379: .It \&Ec Ta Yes Ta Yes Ta opened by \&Eo
! 380: .It \&Eo Ta Yes Ta Yes Ta closed by \&Ec
! 381: .It \&Qc Ta Yes Ta Yes Ta opened by \&Oo
! 382: .It \&Qo Ta Yes Ta Yes Ta closed by \&Oc
! 383: .It \&Re Ta \&No Ta \&No Ta opened by \&Rs
! 384: .It \&Rs Ta \&No Ta \&No Ta closed by \&Re
1.1 kristaps 385: .El
1.43 ! kristaps 386: .\" SUB-SECTION----------------------
1.1 kristaps 387: .Ss Block partial-implicit
1.43 ! kristaps 388: Like block full-implicit, but with single-line scope closed by
! 389: .Sx Reserved Characters
! 390: or end of line.
! 391: .Bd -literal -offset indent
! 392: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
! 393: .Ed
! 394: .\" PARAGRAPH------------
1.1 kristaps 395: .Pp
1.39 kristaps 396: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
1.1 kristaps 397: .It Em Macro Ta Em Callable Ta Em Parsable
1.43 ! kristaps 398: .It \&Aq Ta Yes Ta Yes
! 399: .It \&Op Ta Yes Ta Yes
! 400: .It \&Bq Ta Yes Ta Yes
! 401: .It \&Dq Ta Yes Ta Yes
! 402: .It \&Pq Ta Yes Ta Yes
! 403: .It \&Qq Ta Yes Ta Yes
! 404: .It \&Sq Ta Yes Ta Yes
! 405: .It \&Brq Ta Yes Ta Yes
! 406: .It \&D1 Ta \&No Ta \&Yes
! 407: .It \&Dl Ta \&No Ta Yes
! 408: .It \&Ql Ta Yes Ta Yes
! 409: .El
! 410: .\" SUB-SECTION----------------------
! 411: .Ss In-line
! 412: Closed by
! 413: .Sx Reserved Characters ,
! 414: end of line, fixed argument lengths, and/or subsequent macros. In-line
! 415: macros have only text children. If a number (or inequality) of
1.3 kristaps 416: arguments is
417: .Pq n ,
418: then the macro accepts an arbitrary number of arguments.
1.43 ! kristaps 419: .Bd -literal -offset indent
! 420: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
! 421:
! 422: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
! 423:
! 424: \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
! 425: .Ed
! 426: .\" PARAGRAPH------------
1.2 kristaps 427: .Pp
1.39 kristaps 428: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
1.2 kristaps 429: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.43 ! kristaps 430: .It \&Dd Ta \&No Ta \&No Ta >0
! 431: .It \&Dt Ta \&No Ta \&No Ta n
! 432: .It \&Os Ta \&No Ta \&No Ta n
! 433: .It \&Pp Ta \&No Ta \&No Ta 0
! 434: .It \&Ad Ta Yes Ta Yes Ta n
! 435: .It \&An Ta Yes Ta Yes Ta n
! 436: .It \&Ar Ta Yes Ta Yes Ta n
! 437: .It \&Cd Ta Yes Ta \&No Ta >0
! 438: .It \&Cm Ta Yes Ta Yes Ta n
! 439: .It \&Dv Ta Yes Ta Yes Ta n
! 440: .It \&Er Ta Yes Ta Yes Ta >0
! 441: .It \&Ev Ta Yes Ta Yes Ta n
! 442: .It \&Ex Ta \&No Ta \&No Ta 0
! 443: .It \&Fa Ta Yes Ta Yes Ta n
! 444: .It \&Fd Ta \&No Ta \&No Ta >0
! 445: .It \&Fl Ta Yes Ta Yes Ta n
! 446: .It \&Fn Ta Yes Ta Yes Ta >0
! 447: .It \&Ft Ta Yes Ta Yes Ta n
! 448: .It \&Ic Ta Yes Ta Yes Ta >0
! 449: .It \&In Ta \&No Ta \&No Ta n
! 450: .It \&Li Ta Yes Ta Yes Ta n
! 451: .It \&Nm Ta Yes Ta Yes Ta n
! 452: .It \&Ot Ta \&No Ta \&No Ta n
! 453: .It \&Pa Ta Yes Ta Yes Ta n
! 454: .It \&Rv Ta \&No Ta \&No Ta 0
! 455: .It \&St Ta \&No Ta Yes Ta 1
! 456: .It \&Va Ta Yes Ta Yes Ta n
! 457: .It \&Vt Ta Yes Ta Yes Ta >0
! 458: .It \&Xr Ta Yes Ta Yes Ta >0, <3
! 459: .It \&%A Ta \&No Ta \&No Ta >0
! 460: .It \&%B Ta \&No Ta \&No Ta >0
! 461: .It \&%C Ta \&No Ta \&No Ta >0
! 462: .It \&%D Ta \&No Ta \&No Ta >0
! 463: .It \&%I Ta \&No Ta \&No Ta >0
! 464: .It \&%J Ta \&No Ta \&No Ta >0
! 465: .It \&%N Ta \&No Ta \&No Ta >0
! 466: .It \&%O Ta \&No Ta \&No Ta >0
! 467: .It \&%P Ta \&No Ta \&No Ta >0
! 468: .It \&%R Ta \&No Ta \&No Ta >0
! 469: .It \&%T Ta \&No Ta \&No Ta >0
! 470: .It \&%V Ta \&No Ta \&No Ta >0
! 471: .It \&At Ta Yes Ta Yes Ta 1
! 472: .It \&Bsx Ta Yes Ta Yes Ta n
! 473: .It \&Bx Ta Yes Ta Yes Ta n
! 474: .It \&Db Ta \&No Ta \&No Ta 1
! 475: .It \&Em Ta Yes Ta Yes Ta >0
! 476: .It \&Fx Ta Yes Ta Yes Ta n
! 477: .It \&Ms Ta Yes Ta Yes Ta >0
! 478: .It \&No Ta Yes Ta Yes Ta 0
! 479: .It \&Ns Ta Yes Ta Yes Ta 0
! 480: .It \&Nx Ta Yes Ta Yes Ta n
! 481: .It \&Ox Ta Yes Ta Yes Ta n
! 482: .It \&Pf Ta \&No Ta Yes Ta 1
! 483: .It \&Sm Ta \&No Ta \&No Ta 1
! 484: .It \&Sx Ta Yes Ta Yes Ta >0
! 485: .It \&Sy Ta Yes Ta Yes Ta >0
! 486: .It \&Tn Ta Yes Ta Yes Ta >0
! 487: .It \&Ux Ta Yes Ta Yes Ta n
! 488: .It \&Dx Ta Yes Ta Yes Ta n
! 489: .It \&Bt Ta \&No Ta \&No Ta 0
! 490: .It \&Hf Ta \&No Ta \&No Ta n
! 491: .It \&Fr Ta \&No Ta \&No Ta n
! 492: .It \&Ud Ta \&No Ta \&No Ta 0
! 493: .It \&Lb Ta \&No Ta \&No Ta 1
! 494: .It \&Ap Ta Yes Ta Yes Ta 0
! 495: .It \&Lp Ta \&No Ta \&No Ta 0
! 496: .It \&Lk Ta Yes Ta Yes Ta n
! 497: .It \&Mt Ta Yes Ta Yes Ta >0
! 498: .It \&Es Ta \&No Ta \&No Ta 0
! 499: .It \&En Ta \&No Ta \&No Ta 0
1.1 kristaps 500: .El
1.43 ! kristaps 501: .\" SECTION---------------------------------------------
1.4 kristaps 502: .Sh COMPATIBILITY
1.28 kristaps 503: This section documents compatibility with other roff implementations, at
504: this time limited to
505: .Xr groff 1 .
506: The term
507: .Qq historic groff
508: refers to those versions before the
509: .Pa doc.tmac
510: file re-write
511: .Pq somewhere between 1.15 and 1.19 .
1.43 ! kristaps 512: .\" PARAGRAPH------------
1.4 kristaps 513: .Pp
514: .Bl -dash -compact
515: .\" LIST-ITEM
516: .It
1.35 kristaps 517: Some character sequences in groff are not handled depending on escape
518: style, e.g.,
519: .Sq \e(ba
520: and
521: .Sq \e*(Ba
522: may not be interchanged. This is no longer the case: all character
523: sequences resolve to the same symbol, regardless the escape style.
524: .\" LIST-ITEM
525: .It
526: Blocks of whitespace are stripped from both macro and free-form text
527: lines (except when in literal mode), while groff would retain whitespace
528: in free-form text lines.
529: .\" LIST-ITEM
530: .It
1.28 kristaps 531: Historic groff has many un-callable macros. Most of these (excluding
532: some block-level macros) are now callable, conforming to the
533: non-historic groff version.
534: .\" LIST-ITEM
535: .It
536: The vertical bar
1.35 kristaps 537: .Sq \(ba
1.28 kristaps 538: made historic groff
539: .Qq go orbital
540: but is a proper delimiter in this implementation.
1.5 kristaps 541: .\" LIST-ITEM
542: .It
1.16 kristaps 543: .Sq \&.It \-nested
1.28 kristaps 544: is assumed for all lists (it wasn't in historic groff): any list may be
545: nested and
1.4 kristaps 546: .Sq \-enum
547: lists will restart the sequence only for the sub-list.
548: .\" LIST-ITEM
549: .It
1.16 kristaps 550: .Sq \&.It \-column
1.21 kristaps 551: syntax where column widths may be preceded by other arguments (instead
1.4 kristaps 552: of proceeded) is not supported.
553: .\" LIST-ITEM
554: .It
555: The
1.16 kristaps 556: .Sq \&.At
1.4 kristaps 557: macro only accepts a single parameter.
558: .\" LIST-ITEM
559: .It
560: Some manuals use
1.16 kristaps 561: .Sq \&.Li
1.4 kristaps 562: incorrectly by following it with a reserved character and expecting the
563: delimiter to render. This is not supported.
564: .\" LIST-ITEM
565: .It
1.35 kristaps 566: If an special-character control character is escaped
567: .Sq \e\e ,
568: it will obviously not render the subsequent sequence. Even newer
569: versions of groff seem to dither on this.
1.41 kristaps 570: .\" LIST-ITEM
571: .It
572: In groff, the
573: .Sq \&.Fo
574: macro only produces the first parameter. This is no longer the case.
1.4 kristaps 575: .El
1.43 ! kristaps 576: .\" SECTION---------------------------------------------
1.2 kristaps 577: .Sh SEE ALSO
1.19 kristaps 578: .Xr mandoc 1 ,
579: .Xr mandoc_char 7
1.43 ! kristaps 580: .\" SECTION---------------------------------------------
1.2 kristaps 581: .Sh AUTHORS
582: The
583: .Nm
584: utility was written by
1.24 kristaps 585: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.43 ! kristaps 586: .\" SECTION---------------------------------------------
1.5 kristaps 587: .Sh CAVEATS
1.28 kristaps 588: There are many ambiguous parts of mdoc.
1.43 ! kristaps 589: .\" PARAGRAPH------------
1.5 kristaps 590: .Pp
591: .Bl -dash -compact
592: .\" LIST-ITEM
593: .It
1.16 kristaps 594: .Sq \&.Fa
1.5 kristaps 595: should be
1.16 kristaps 596: .Sq \&.Va
1.5 kristaps 597: as function arguments are variables.
598: .\" LIST-ITEM
599: .It
1.16 kristaps 600: .Sq \&.Ft
1.5 kristaps 601: should be
1.16 kristaps 602: .Sq \&.Vt
1.5 kristaps 603: as function return types are still types. Furthermore, the
1.16 kristaps 604: .Sq \&.Ft
1.5 kristaps 605: should be removed and
1.16 kristaps 606: .Sq \&.Fo ,
1.5 kristaps 607: which ostensibly follows it, should follow the same convention as
1.16 kristaps 608: .Sq \&.Va .
1.5 kristaps 609: .\" LIST-ITEM
610: .It
1.16 kristaps 611: .Sq \&.Va
1.5 kristaps 612: should formalise that only one or two arguments are acceptable: a
1.21 kristaps 613: variable name and optional, preceding type.
1.5 kristaps 614: .\" LIST-ITEM
615: .It
1.16 kristaps 616: .Sq \&.Fd
1.5 kristaps 617: is ambiguous. It's commonly used to indicate an include file in the
618: synopsis section.
1.16 kristaps 619: .Sq \&.In
1.5 kristaps 620: should be used, instead.
621: .\" LIST-ITEM
622: .It
623: Only the
624: .Sq \-literal
625: argument to
1.16 kristaps 626: .Sq \&.Bd
1.5 kristaps 627: makes sense. The remaining ones should be removed.
628: .\" LIST-ITEM
629: .It
630: The
1.16 kristaps 631: .Sq \&.Xo
1.5 kristaps 632: and
1.16 kristaps 633: .Sq \&.Xc
1.5 kristaps 634: macros should be deprecated.
635: .\" LIST-ITEM
636: .It
637: The
1.16 kristaps 638: .Sq \&.Dt
1.5 kristaps 639: macro lacks clarity. It should be absolutely clear which title will
640: render when formatting the manual page.
1.6 kristaps 641: .\" LIST-ITEM
642: .It
643: A
1.16 kristaps 644: .Sq \&.Lx
1.6 kristaps 645: should be provided for Linux (\(`a la
1.16 kristaps 646: .Sq \&.Ox ,
647: .Sq \&.Nx
1.6 kristaps 648: etc.).
1.14 kristaps 649: .\" LIST-ITEM
650: .It
651: There's no way to refer to references in
1.16 kristaps 652: .Sq \&.Rs/.Re
1.14 kristaps 653: blocks.
1.31 kristaps 654: .\" LIST-ITEM
655: .It
656: The \-split and \-nosplit arguments to
657: .Sq \&.An
658: are inane.
1.5 kristaps 659: .El
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mdoc.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc