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