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