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