Annotation of mandoc/mdoc.7, Revision 1.57
1.57 ! kristaps 1: .\" $Id: mdoc.7,v 1.56 2009/08/18 14:27:16 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.50 kristaps 16: .\"
1.1 kristaps 17: .Dd $Mdocdate$
1.20 kristaps 18: .Dt MDOC 7
1.1 kristaps 19: .Os
1.56 kristaps 20: .
21: .
1.1 kristaps 22: .Sh NAME
1.57 ! kristaps 23: .Nm mdoc
! 24: .Nd mdoc language reference
1.56 kristaps 25: .
26: .
1.1 kristaps 27: .Sh DESCRIPTION
28: The
1.57 ! kristaps 29: .Nm mdoc
1.50 kristaps 30: language is used to format
1.57 ! kristaps 31: .Bx
! 32: .Ux
1.43 kristaps 33: manuals. In this reference document, we describe its syntax, structure,
34: and usage. Our reference implementation is
1.57 ! kristaps 35: .Xr mandoc 1 .
1.28 kristaps 36: The
1.57 ! kristaps 37: .Sx COMPATIBILITY
1.50 kristaps 38: section describes compatibility with
1.57 ! kristaps 39: .Xr groff 1 .
! 40: .
! 41: .Pp
1.13 kristaps 42: An
1.57 ! kristaps 43: .Nm
1.1 kristaps 44: document follows simple rules: lines beginning with the control
1.50 kristaps 45: character
1.57 ! kristaps 46: .Sq \.
1.1 kristaps 47: are parsed for macros. Other lines are interpreted within the scope of
1.13 kristaps 48: prior macros:
1.57 ! kristaps 49: .Bd -literal -offset indent
1.13 kristaps 50: \&.Sh Macro lines change control state.
51: Other lines are interpreted within the current state.
1.57 ! kristaps 52: .Ed
1.56 kristaps 53: .
54: .
1.46 kristaps 55: .Sh LANGUAGE SYNTAX
1.57 ! kristaps 56: .Nm
1.13 kristaps 57: documents may contain only graphable 7-bit ASCII characters, the space
1.43 kristaps 58: character, and, in certain circumstances, the tab character. All
59: manuals must have
1.57 ! kristaps 60: .Ux
1.50 kristaps 61: line terminators.
1.56 kristaps 62: .
63: .
1.57 ! kristaps 64: .Ss Comments
1.43 kristaps 65: Text following a
1.57 ! kristaps 66: .Sq \e" ,
1.43 kristaps 67: whether in a macro or free-form text line, is ignored to the end of
68: line. A macro line with only a control character and comment escape,
1.57 ! kristaps 69: .Sq \&.\e" ,
1.43 kristaps 70: is also ignored.
1.56 kristaps 71: .
72: .
1.57 ! kristaps 73: .Ss Reserved Characters
1.2 kristaps 74: Within a macro line, the following characters are reserved:
1.57 ! kristaps 75: .Bl -tag -width Ds -offset indent -compact
! 76: .It \&.
! 77: .Pq period
! 78: .It \&,
! 79: .Pq comma
! 80: .It \&:
! 81: .Pq colon
! 82: .It \&;
! 83: .Pq semicolon
! 84: .It \&(
! 85: .Pq left-parenthesis
! 86: .It \&)
! 87: .Pq right-parenthesis
! 88: .It \&[
! 89: .Pq left-bracket
! 90: .It \&]
! 91: .Pq right-bracket
! 92: .It \&?
! 93: .Pq question
! 94: .It \&!
! 95: .Pq exclamation
! 96: .It \&|
! 97: .Pq vertical bar
! 98: .El
! 99: .
! 100: .Pp
1.5 kristaps 101: Use of reserved characters is described in
1.57 ! kristaps 102: .Sx MACRO SYNTAX .
1.43 kristaps 103: For general use in macro lines, these characters must either be escaped
104: with a non-breaking space
1.57 ! kristaps 105: .Pq Sq \e&
1.50 kristaps 106: or, if applicable, an appropriate escape sequence used.
1.56 kristaps 107: .
108: .
1.57 ! kristaps 109: .Ss Special Characters
1.43 kristaps 110: Special characters may occur in both macro and free-form lines.
111: Sequences begin with the escape character
1.57 ! kristaps 112: .Sq \e
1.50 kristaps 113: followed by either an open-parenthesis
1.57 ! kristaps 114: .Sq \&(
1.1 kristaps 115: for two-character sequences; an open-bracket
1.57 ! kristaps 116: .Sq \&[
1.1 kristaps 117: for n-character sequences (terminated at a close-bracket
1.57 ! kristaps 118: .Sq \&] ) ;
1.43 kristaps 119: or a single one-character sequence. See
1.57 ! kristaps 120: .Xr mandoc_char 7
1.50 kristaps 121: for a complete list. Examples include
1.57 ! kristaps 122: .Sq \e(em
! 123: .Pq em-dash
1.50 kristaps 124: and
1.57 ! kristaps 125: .Sq \ee
! 126: .Pq back-slash .
1.56 kristaps 127: .
128: .
1.57 ! kristaps 129: .Ss Text Decoration
1.54 kristaps 130: Terms may be text-decorated using the
1.57 ! kristaps 131: .Sq \ef
1.43 kristaps 132: escape followed by an indicator: B (bold), I, (italic), or P and R
1.54 kristaps 133: (Roman, or reset). This form is not recommended for
1.57 ! kristaps 134: .Nm ,
1.54 kristaps 135: which encourages semantic, not presentation, annotation.
1.56 kristaps 136: .
137: .
1.57 ! kristaps 138: .Ss Predefined Strings
1.54 kristaps 139: Historically,
1.57 ! kristaps 140: .Xr groff 1
1.54 kristaps 141: also defined a set of package-specific
1.57 ! kristaps 142: .Dq predefined strings ,
1.54 kristaps 143: which, like
1.57 ! kristaps 144: .Sx Special Characters ,
1.54 kristaps 145: demark special output characters and strings by way of input codes.
146: Predefined strings are escaped with the slash-asterisk,
1.57 ! kristaps 147: .Sq \e* :
1.54 kristaps 148: single-character
1.57 ! kristaps 149: .Sq \e*X ,
1.54 kristaps 150: two-character
1.57 ! kristaps 151: .Sq \e*(XX ,
1.54 kristaps 152: and N-character
1.57 ! kristaps 153: .Sq \e*[N] .
1.54 kristaps 154: See
1.57 ! kristaps 155: .Xr mandoc_char 7
1.54 kristaps 156: for a complete list. Examples include
1.57 ! kristaps 157: .Sq \e*(Am
! 158: .Pq ampersand
1.54 kristaps 159: and
1.57 ! kristaps 160: .Sq \e*(Ba
! 161: .Pq vertical bar .
1.56 kristaps 162: .
163: .
1.57 ! kristaps 164: .Ss Whitespace
1.46 kristaps 165: In non-literal free-form lines, consecutive blocks of whitespace are
166: pruned from input and added later in the output filter, if applicable:
1.57 ! kristaps 167: .Bd -literal -offset indent
1.46 kristaps 168: These spaces are pruned from input.
1.50 kristaps 169: \&.Bd \-literal
1.46 kristaps 170: These are not.
171: \&.Ed
1.57 ! kristaps 172: .Ed
! 173: .
! 174: .Pp
1.46 kristaps 175: In macro lines, whitespace delimits arguments and is discarded. If
1.47 kristaps 176: arguments are quoted, whitespace within the quotes is retained.
1.57 ! kristaps 177: .
! 178: .Pp
1.46 kristaps 179: Blank lines are only permitted within literal contexts, as are lines
180: containing only whitespace. Tab characters are only acceptable when
1.50 kristaps 181: delimiting
1.57 ! kristaps 182: .Sq \&Bl \-column
1.46 kristaps 183: or when in a literal context.
1.56 kristaps 184: .
185: .
1.57 ! kristaps 186: .Ss Quotation
1.46 kristaps 187: Macro arguments may be quoted with a double-quote to group
188: space-delimited terms or to retain blocks of whitespace. A quoted
189: argument begins with a double-quote preceded by whitespace. The next
1.48 kristaps 190: double-quote not pair-wise adjacent to another double-quote terminates
1.50 kristaps 191: the literal, regardless of surrounding whitespace.
1.57 ! kristaps 192: .
! 193: .Pp
1.50 kristaps 194: This produces tokens
1.57 ! kristaps 195: .Sq a" ,
! 196: .Sq b c ,
! 197: .Sq de ,
1.47 kristaps 198: and
1.57 ! kristaps 199: .Sq fg" .
1.47 kristaps 200: Note that any quoted term, be it argument or macro, is indiscriminately
1.50 kristaps 201: considered literal text. Thus, the following produces
1.57 ! kristaps 202: .Sq \&Em a :
! 203: .Bd -literal -offset indent
1.47 kristaps 204: \&.Em "Em a"
1.57 ! kristaps 205: .Ed
! 206: .
! 207: .Pp
1.46 kristaps 208: In free-form mode, quotes are regarded as opaque text.
1.56 kristaps 209: .
210: .
1.43 kristaps 211: .Sh MANUAL STRUCTURE
1.33 kristaps 212: Each
1.57 ! kristaps 213: .Nm
1.50 kristaps 214: document must begin with a document prologue, containing, in order,
1.57 ! kristaps 215: .Sq \&Dd ,
! 216: .Sq \&Dt ,
1.33 kristaps 217: and
1.57 ! kristaps 218: .Sq \&Os ,
1.46 kristaps 219: then the NAME section containing at least one
1.57 ! kristaps 220: .Sq \&Nm
1.50 kristaps 221: followed by
1.57 ! kristaps 222: .Sq \&Nd :
! 223: .Bd -literal -offset indent
1.43 kristaps 224: \&.Dd $\&Mdocdate$
225: \&.Dt mdoc 7
226: \&.Os
227: \&.Sh NAME
228: \&.Nm mdoc
229: \&.Nd mdoc language reference
1.57 ! kristaps 230: .Ed
! 231: .
! 232: .Pp
1.43 kristaps 233: Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
1.50 kristaps 234: but non-compulsory.
1.56 kristaps 235: .
236: .
1.43 kristaps 237: .Sh MACRO SYNTAX
1.56 kristaps 238: Macros are one to three three characters in length and begin with a
239: control character ,
1.57 ! kristaps 240: .Sq \&. ,
1.56 kristaps 241: at the beginning of the line. An arbitrary amount of whitespace may
242: sit between the control character and the macro name. Thus,
1.57 ! kristaps 243: .Sq \&.Pp
1.56 kristaps 244: and
1.57 ! kristaps 245: .Sq \&.\ \ \ \&Pp
1.56 kristaps 246: are equivalent. Macro names are two or three characters in length.
1.57 ! kristaps 247: .
! 248: .Pp
1.46 kristaps 249: The syntax of a macro depends on its classification. In this section,
1.57 ! kristaps 250: .Sq \-arg
1.43 kristaps 251: refers to macro arguments, which may be followed by zero or more
1.57 ! kristaps 252: .Sq parm
1.43 kristaps 253: parameters;
1.57 ! kristaps 254: .Sq \&Yo
1.43 kristaps 255: opens the scope of a macro; and if specified,
1.57 ! kristaps 256: .Sq \&Yc
1.43 kristaps 257: closes it out.
1.57 ! kristaps 258: .
! 259: .Pp
1.43 kristaps 260: The
1.57 ! kristaps 261: .Em Callable
1.43 kristaps 262: column indicates that the macro may be called subsequent to the initial
1.55 kristaps 263: line-macro. If a macro is not callable, then its invocation after the
264: initial line macro is interpreted as opaque text, such that
1.57 ! kristaps 265: .Sq \&.Fl Sh
1.55 kristaps 266: produces
1.57 ! kristaps 267: .Sq Fl Sh .
! 268: .
! 269: .Pp
1.55 kristaps 270: The
1.57 ! kristaps 271: .Em Parsable
1.43 kristaps 272: column indicates whether the macro may be followed by further
1.55 kristaps 273: (ostensibly callable) macros. If a macro is not parsable, subsequent
274: macro invocations on the line will be interpreted as opaque text.
1.57 ! kristaps 275: .
! 276: .Pp
1.55 kristaps 277: The
1.57 ! kristaps 278: .Em Scope
1.43 kristaps 279: column, if applicable, describes closure rules.
1.56 kristaps 280: .
281: .
1.57 ! kristaps 282: .Ss Block full-explicit
1.43 kristaps 283: Multi-line scope closed by an explicit closing macro. All macros
284: contains bodies; only
1.57 ! kristaps 285: .Pq Sq \&Bf
1.43 kristaps 286: contains a head.
1.57 ! kristaps 287: .Bd -literal -offset indent
1.50 kristaps 288: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
289: \(lBbody...\(rB
1.43 kristaps 290: \&.Yc
1.57 ! kristaps 291: .Ed
! 292: .
! 293: .Pp
! 294: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
! 295: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
! 296: .It \&Bd Ta \&No Ta \&No Ta closed by \&Ed
! 297: .It \&Bf Ta \&No Ta \&No Ta closed by \&Ef
! 298: .It \&Bk Ta \&No Ta \&No Ta closed by \&Ek
! 299: .It \&Bl Ta \&No Ta \&No Ta closed by \&El
! 300: .It \&Ed Ta \&No Ta \&No Ta opened by \&Bd
! 301: .It \&Ef Ta \&No Ta \&No Ta opened by \&Bf
! 302: .It \&Ek Ta \&No Ta \&No Ta opened by \&Bk
! 303: .It \&El Ta \&No Ta \&No Ta opened by \&Bl
! 304: .El
1.56 kristaps 305: .
306: .
1.57 ! kristaps 307: .Ss Block full-implicit
1.43 kristaps 308: Multi-line scope closed by end-of-file or implicitly by another macro.
1.50 kristaps 309: All macros have bodies; some
1.57 ! kristaps 310: .Po
! 311: .Sq \&It \-bullet ,
! 312: .Sq \-hyphen ,
! 313: .Sq \-dash ,
! 314: .Sq \-enum ,
! 315: .Sq \-item
! 316: .Pc
1.50 kristaps 317: don't have heads, while
1.57 ! kristaps 318: .Sq \&It \-column
1.43 kristaps 319: may have multiple heads.
1.57 ! kristaps 320: .Bd -literal -offset indent
1.50 kristaps 321: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
322: \(lBbody...\(rB
1.57 ! kristaps 323: .Ed
1.56 kristaps 324: .
1.57 ! kristaps 325: .Pp
! 326: .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
! 327: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
! 328: .It \&It Ta \&No Ta Yes Ta closed by \&It, \&El
! 329: .It \&Nd Ta \&No Ta \&No Ta closed by \&Sh
! 330: .It \&Sh Ta \&No Ta \&No Ta closed by \&Sh
! 331: .It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss
! 332: .El
1.56 kristaps 333: .
1.57 ! kristaps 334: .
! 335: .Ss Block partial-explicit
1.43 kristaps 336: Like block full-explicit, but also with single-line scope. Each
1.50 kristaps 337: has at least a body and, in limited circumstances, a head
1.57 ! kristaps 338: .Pq So \&Fo Sc , So \&Eo Sc
1.50 kristaps 339: and/or tail
1.57 ! kristaps 340: .Pq So \&Ec Sc .
! 341: .Bd -literal -offset indent
1.50 kristaps 342: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
343: \(lBbody...\(rB
344: \&.Yc \(lBtail...\(rB
1.2 kristaps 345:
1.43 kristaps 346: \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
1.50 kristaps 347: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.57 ! kristaps 348: .Ed
! 349: .
! 350: .Pp
! 351: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
! 352: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
! 353: .It \&Ac Ta Yes Ta Yes Ta opened by \&Ao
! 354: .It \&Ao Ta Yes Ta Yes Ta closed by \&Ac
! 355: .It \&Bc Ta Yes Ta Yes Ta closed by \&Bo
! 356: .It \&Bo Ta Yes Ta Yes Ta opened by \&Bc
! 357: .It \&Brc Ta Yes Ta Yes Ta opened by \&Bro
! 358: .It \&Bro Ta Yes Ta Yes Ta closed by \&Brc
! 359: .It \&Dc Ta Yes Ta Yes Ta opened by \&Do
! 360: .It \&Do Ta Yes Ta Yes Ta closed by \&Dc
! 361: .It \&Ec Ta Yes Ta Yes Ta opened by \&Eo
! 362: .It \&Eo Ta Yes Ta Yes Ta closed by \&Ec
! 363: .It \&Fc Ta Yes Ta Yes Ta opened by \&Fo
! 364: .It \&Fo Ta \&No Ta \&No Ta closed by \&Fc
! 365: .It \&Oc Ta Yes Ta Yes Ta closed by \&Oo
! 366: .It \&Oo Ta Yes Ta Yes Ta opened by \&Oc
! 367: .It \&Pc Ta Yes Ta Yes Ta closed by \&Po
! 368: .It \&Po Ta Yes Ta Yes Ta opened by \&Pc
! 369: .It \&Qc Ta Yes Ta Yes Ta opened by \&Oo
! 370: .It \&Qo Ta Yes Ta Yes Ta closed by \&Oc
! 371: .It \&Re Ta \&No Ta \&No Ta opened by \&Rs
! 372: .It \&Rs Ta \&No Ta \&No Ta closed by \&Re
! 373: .It \&Sc Ta Yes Ta Yes Ta opened by \&So
! 374: .It \&So Ta Yes Ta Yes Ta closed by \&Sc
! 375: .It \&Xc Ta Yes Ta Yes Ta opened by \&Xo
! 376: .It \&Xo Ta Yes Ta Yes Ta closed by \&Xc
! 377: .El
1.56 kristaps 378: .
379: .
1.57 ! kristaps 380: .Ss Block partial-implicit
1.50 kristaps 381: Like block full-implicit, but with single-line scope closed by
1.57 ! kristaps 382: .Sx Reserved Characters
1.43 kristaps 383: or end of line.
1.57 ! kristaps 384: .Bd -literal -offset indent
1.43 kristaps 385: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
1.57 ! kristaps 386: .Ed
1.56 kristaps 387: .
1.57 ! kristaps 388: .Pp
! 389: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
! 390: .It Em Macro Ta Em Callable Ta Em Parsable
! 391: .It \&Aq Ta Yes Ta Yes
! 392: .It \&Bq Ta Yes Ta Yes
! 393: .It \&Brq Ta Yes Ta Yes
! 394: .It \&D1 Ta \&No Ta \&Yes
! 395: .It \&Dl Ta \&No Ta Yes
! 396: .It \&Dq Ta Yes Ta Yes
! 397: .It \&Op Ta Yes Ta Yes
! 398: .It \&Pq Ta Yes Ta Yes
! 399: .It \&Ql Ta Yes Ta Yes
! 400: .It \&Qq Ta Yes Ta Yes
! 401: .It \&Sq Ta Yes Ta Yes
! 402: .El
1.56 kristaps 403: .
1.57 ! kristaps 404: .
! 405: .Ss In-line
1.50 kristaps 406: Closed by
1.57 ! kristaps 407: .Sx Reserved Characters ,
1.43 kristaps 408: end of line, fixed argument lengths, and/or subsequent macros. In-line
409: macros have only text children. If a number (or inequality) of
1.3 kristaps 410: arguments is
1.57 ! kristaps 411: .Pq n ,
1.3 kristaps 412: then the macro accepts an arbitrary number of arguments.
1.57 ! kristaps 413: .Bd -literal -offset indent
1.43 kristaps 414: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
415:
416: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
417:
418: \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
1.57 ! kristaps 419: .Ed
! 420: .
! 421: .Pp
! 422: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
! 423: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
! 424: .It \&%A Ta \&No Ta \&No Ta >0
! 425: .It \&%B Ta \&No Ta \&No Ta >0
! 426: .It \&%C Ta \&No Ta \&No Ta >0
! 427: .It \&%D Ta \&No Ta \&No Ta >0
! 428: .It \&%I Ta \&No Ta \&No Ta >0
! 429: .It \&%J Ta \&No Ta \&No Ta >0
! 430: .It \&%N Ta \&No Ta \&No Ta >0
! 431: .It \&%O Ta \&No Ta \&No Ta >0
! 432: .It \&%P Ta \&No Ta \&No Ta >0
! 433: .It \&%R Ta \&No Ta \&No Ta >0
! 434: .It \&%T Ta \&No Ta \&No Ta >0
! 435: .It \&%V Ta \&No Ta \&No Ta >0
! 436: .It \&Ad Ta Yes Ta Yes Ta n
! 437: .It \&An Ta Yes Ta Yes Ta n
! 438: .It \&Ap Ta Yes Ta Yes Ta 0
! 439: .It \&Ar Ta Yes Ta Yes Ta n
! 440: .It \&At Ta Yes Ta Yes Ta 1
! 441: .It \&Bsx Ta Yes Ta Yes Ta n
! 442: .It \&Bt Ta \&No Ta \&No Ta 0
! 443: .It \&Bx Ta Yes Ta Yes Ta n
! 444: .It \&Cd Ta Yes Ta Yes Ta >0
! 445: .It \&Cm Ta Yes Ta Yes Ta n
! 446: .It \&Db Ta \&No Ta \&No Ta 1
! 447: .It \&Dd Ta \&No Ta \&No Ta >0
! 448: .It \&Dt Ta \&No Ta \&No Ta n
! 449: .It \&Dv Ta Yes Ta Yes Ta n
! 450: .It \&Dx Ta Yes Ta Yes Ta n
! 451: .It \&Em Ta Yes Ta Yes Ta >0
! 452: .It \&En Ta \&No Ta \&No Ta 0
! 453: .It \&Er Ta Yes Ta Yes Ta >0
! 454: .It \&Es Ta \&No Ta \&No Ta 0
! 455: .It \&Ev Ta Yes Ta Yes Ta n
! 456: .It \&Ex Ta \&No Ta \&No Ta 0
! 457: .It \&Fa Ta Yes Ta Yes Ta n
! 458: .It \&Fd Ta \&No Ta \&No Ta >0
! 459: .It \&Fl Ta Yes Ta Yes Ta n
! 460: .It \&Fn Ta Yes Ta Yes Ta >0
! 461: .It \&Fr Ta \&No Ta \&No Ta n
! 462: .It \&Ft Ta Yes Ta Yes Ta n
! 463: .It \&Fx Ta Yes Ta Yes Ta n
! 464: .It \&Hf Ta \&No Ta \&No Ta n
! 465: .It \&Ic Ta Yes Ta Yes Ta >0
! 466: .It \&In Ta \&No Ta \&No Ta n
! 467: .It \&Lb Ta \&No Ta \&No Ta 1
! 468: .It \&Li Ta Yes Ta Yes Ta n
! 469: .It \&Lk Ta Yes Ta Yes Ta n
! 470: .It \&Lp Ta \&No Ta \&No Ta 0
! 471: .It \&Ms Ta Yes Ta Yes Ta >0
! 472: .It \&Mt Ta Yes Ta Yes Ta >0
! 473: .It \&Nm Ta Yes Ta Yes Ta n
! 474: .It \&No Ta Yes Ta Yes Ta 0
! 475: .It \&Ns Ta Yes Ta Yes Ta 0
! 476: .It \&Nx Ta Yes Ta Yes Ta n
! 477: .It \&Os Ta \&No Ta \&No Ta n
! 478: .It \&Ot Ta \&No Ta \&No Ta n
! 479: .It \&Ox Ta Yes Ta Yes Ta n
! 480: .It \&Pa Ta Yes Ta Yes Ta n
! 481: .It \&Pf Ta \&No Ta Yes Ta 1
! 482: .It \&Pp Ta \&No Ta \&No Ta 0
! 483: .It \&Rv Ta \&No Ta \&No Ta 0
! 484: .It \&Sm Ta \&No Ta \&No Ta 1
! 485: .It \&St Ta \&No Ta Yes Ta 1
! 486: .It \&Sx Ta Yes Ta Yes Ta >0
! 487: .It \&Sy Ta Yes Ta Yes Ta >0
! 488: .It \&Tn Ta Yes Ta Yes Ta >0
! 489: .It \&Ud Ta \&No Ta \&No Ta 0
! 490: .It \&Ux Ta Yes Ta Yes Ta n
! 491: .It \&Va Ta Yes Ta Yes Ta n
! 492: .It \&Vt Ta Yes Ta Yes Ta >0
! 493: .It \&Xr Ta Yes Ta Yes Ta >0, <3
! 494: .It \&br Ta \&No Ta \&No Ta 0
! 495: .It \&sp Ta \&No Ta \&No Ta 1
! 496: .El
1.56 kristaps 497: .
498: .
1.4 kristaps 499: .Sh COMPATIBILITY
1.28 kristaps 500: This section documents compatibility with other roff implementations, at
1.50 kristaps 501: this time limited to
1.57 ! kristaps 502: .Xr groff 1 .
1.50 kristaps 503: The term
1.57 ! kristaps 504: .Qq historic groff
1.50 kristaps 505: refers to those versions before the
1.57 ! kristaps 506: .Pa doc.tmac
1.50 kristaps 507: file re-write
1.57 ! kristaps 508: .Pq somewhere between 1.15 and 1.19 .
! 509: .
! 510: .Pp
! 511: .Bl -dash -compact
! 512: .It
1.51 kristaps 513: The
1.57 ! kristaps 514: .Sq \-split
1.51 kristaps 515: or
1.57 ! kristaps 516: .Sq \-nosplit
1.51 kristaps 517: argument to
1.57 ! kristaps 518: .Sq \&An
1.51 kristaps 519: applies to the whole document, not just to the current section as it
520: does in groff.
1.57 ! kristaps 521: .It
1.48 kristaps 522: In quoted literals, groff allowed pair-wise double-quotes to produce a
523: standalone double-quote in formatted output. This idiosyncratic
524: behaviour is no longer applicable.
1.57 ! kristaps 525: .It
1.50 kristaps 526: The
1.57 ! kristaps 527: .Sq \&sp
1.45 kristaps 528: macro does not accept negative numbers.
1.57 ! kristaps 529: .It
1.35 kristaps 530: Blocks of whitespace are stripped from both macro and free-form text
531: lines (except when in literal mode), while groff would retain whitespace
532: in free-form text lines.
1.57 ! kristaps 533: .It
1.28 kristaps 534: Historic groff has many un-callable macros. Most of these (excluding
535: some block-level macros) are now callable, conforming to the
536: non-historic groff version.
1.57 ! kristaps 537: .It
1.50 kristaps 538: The vertical bar
1.57 ! kristaps 539: .Sq \(ba
1.28 kristaps 540: made historic groff
1.57 ! kristaps 541: .Qq go orbital
1.28 kristaps 542: but is a proper delimiter in this implementation.
1.57 ! kristaps 543: .It
! 544: .Sq \&It \-nested
1.28 kristaps 545: is assumed for all lists (it wasn't in historic groff): any list may be
546: nested and
1.57 ! kristaps 547: .Sq \-enum
1.4 kristaps 548: lists will restart the sequence only for the sub-list.
1.57 ! kristaps 549: .It
! 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.
1.57 ! kristaps 553: .It
1.50 kristaps 554: The
1.57 ! kristaps 555: .Sq \&At
1.4 kristaps 556: macro only accepts a single parameter.
1.57 ! kristaps 557: .It
1.4 kristaps 558: Some manuals use
1.57 ! kristaps 559: .Sq \&Li
1.4 kristaps 560: incorrectly by following it with a reserved character and expecting the
561: delimiter to render. This is not supported.
1.57 ! kristaps 562: .It
1.50 kristaps 563: In groff, the
1.57 ! kristaps 564: .Sq \&Fo
1.41 kristaps 565: macro only produces the first parameter. This is no longer the case.
1.57 ! kristaps 566: .El
1.56 kristaps 567: .
568: .
1.2 kristaps 569: .Sh SEE ALSO
1.57 ! kristaps 570: .Xr mandoc 1 ,
! 571: .Xr mandoc_char 7
1.56 kristaps 572: .
573: .
1.2 kristaps 574: .Sh AUTHORS
575: The
1.57 ! kristaps 576: .Nm
1.50 kristaps 577: reference was written by
1.57 ! kristaps 578: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.56 kristaps 579: .
580: .
1.5 kristaps 581: .Sh CAVEATS
1.28 kristaps 582: There are many ambiguous parts of mdoc.
1.57 ! kristaps 583: .
! 584: .Pp
! 585: .Bl -dash -compact
! 586: .It
! 587: .Sq \&Fa
1.50 kristaps 588: should be
1.57 ! kristaps 589: .Sq \&Va
1.5 kristaps 590: as function arguments are variables.
1.57 ! kristaps 591: .It
! 592: .Sq \&Ft
1.5 kristaps 593: should be
1.57 ! kristaps 594: .Sq \&Vt
1.5 kristaps 595: as function return types are still types. Furthermore, the
1.57 ! kristaps 596: .Sq \&Ft
1.5 kristaps 597: should be removed and
1.57 ! kristaps 598: .Sq \&Fo ,
1.5 kristaps 599: which ostensibly follows it, should follow the same convention as
1.57 ! kristaps 600: .Sq \&Va .
! 601: .It
! 602: .Sq \&Va
1.5 kristaps 603: should formalise that only one or two arguments are acceptable: a
1.21 kristaps 604: variable name and optional, preceding type.
1.57 ! kristaps 605: .It
! 606: .Sq \&Fd
1.5 kristaps 607: is ambiguous. It's commonly used to indicate an include file in the
1.50 kristaps 608: synopsis section.
1.57 ! kristaps 609: .Sq \&In
1.5 kristaps 610: should be used, instead.
1.57 ! kristaps 611: .It
1.5 kristaps 612: Only the
1.57 ! kristaps 613: .Sq \-literal
1.5 kristaps 614: argument to
1.57 ! kristaps 615: .Sq \&Bd
1.5 kristaps 616: makes sense. The remaining ones should be removed.
1.57 ! kristaps 617: .It
1.50 kristaps 618: The
1.57 ! kristaps 619: .Sq \&Xo
1.5 kristaps 620: and
1.57 ! kristaps 621: .Sq \&Xc
1.5 kristaps 622: macros should be deprecated.
1.57 ! kristaps 623: .It
1.5 kristaps 624: The
1.57 ! kristaps 625: .Sq \&Dt
1.5 kristaps 626: macro lacks clarity. It should be absolutely clear which title will
627: render when formatting the manual page.
1.57 ! kristaps 628: .It
1.6 kristaps 629: A
1.57 ! kristaps 630: .Sq \&Lx
1.50 kristaps 631: should be provided for Linux (\(`a la
1.57 ! kristaps 632: .Sq \&Ox ,
! 633: .Sq \&Nx
1.6 kristaps 634: etc.).
1.57 ! kristaps 635: .It
1.14 kristaps 636: There's no way to refer to references in
1.57 ! kristaps 637: .Sq \&Rs/Re
1.14 kristaps 638: blocks.
1.57 ! kristaps 639: .It
1.54 kristaps 640: The \-split and \-nosplit dictates via
1.57 ! kristaps 641: .Sq \&An
1.54 kristaps 642: are re-set when entering and leaving the AUTHORS section.
1.57 ! kristaps 643: .El
1.56 kristaps 644: .
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