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