Annotation of mandoc/mdoc.7, Revision 1.28
1.28 ! kristaps 1: .\" $Id: mdoc.7,v 1.27 2009/06/12 09:18:00 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.1 kristaps 16: .\"
17: .Dd $Mdocdate$
1.20 kristaps 18: .Dt MDOC 7
1.1 kristaps 19: .Os
20: .\" SECTION
21: .Sh NAME
22: .Nm mdoc
1.15 kristaps 23: .Nd mdoc language reference
1.1 kristaps 24: .\" SECTION
25: .Sh DESCRIPTION
26: The
27: .Nm mdoc
28: language is used to format
29: .Bx
30: .Ux
1.13 kristaps 31: manuals. In this reference document, we describe the syntax, ontology
32: and structure of the
33: .Nm
1.28 ! kristaps 34: language. Our reference implementation is
! 35: .Xr mandoc 1 .
! 36: The
! 37: .Sx COMPATIBILITY
! 38: section describes compatibility with
! 39: .Xr groff 1 .
1.13 kristaps 40: .\" PARAGRAPH
41: .Pp
42: An
1.1 kristaps 43: .Nm
44: document follows simple rules: lines beginning with the control
1.13 kristaps 45: character
1.1 kristaps 46: .Sq \.
47: are parsed for macros. Other lines are interpreted within the scope of
1.13 kristaps 48: prior macros:
49: .Bd -literal -offset XXX
50: \&.Sh Macro lines change control state.
51: Other lines are interpreted within the current state.
52: .Ed
1.1 kristaps 53: .\" SECTION
1.13 kristaps 54: .Sh INPUT ENCODING
1.1 kristaps 55: .Nm
1.13 kristaps 56: documents may contain only graphable 7-bit ASCII characters, the space
57: character
1.1 kristaps 58: .Sq \ ,
59: and, in certain circumstances, the tab character
60: .Sq \et .
61: All manuals must have
62: .Sq \en
1.10 kristaps 63: line termination.
64: .Pp
65: The only time a blank line is acceptable is within
66: the context of
1.16 kristaps 67: .Sq \&.Bd \-literal
1.10 kristaps 68: or
1.16 kristaps 69: .Sq \&.Bd \-unfilled .
1.10 kristaps 70: .Pp
71: Tab characters
72: .Pq \et
73: are only acceptable when delimiting
1.16 kristaps 74: .Sq \&.Bl \-column
1.10 kristaps 75: and in
1.16 kristaps 76: .Sq \&.Bd \-literal
1.10 kristaps 77: or
1.16 kristaps 78: .Sq \&.Bd \-unfilled
1.10 kristaps 79: contexts.
1.1 kristaps 80: .\" SUB-SECTION
1.2 kristaps 81: .Ss Reserved Characters
82: Within a macro line, the following characters are reserved:
83: .Bl -tag -width 12n -offset XXXX -compact
1.1 kristaps 84: .It \&.
1.2 kristaps 85: .Pq period
1.1 kristaps 86: .It \&,
1.2 kristaps 87: .Pq comma
1.1 kristaps 88: .It \&:
1.2 kristaps 89: .Pq colon
1.1 kristaps 90: .It \&;
1.2 kristaps 91: .Pq semicolon
1.1 kristaps 92: .It \&(
1.2 kristaps 93: .Pq left-parenthesis
1.1 kristaps 94: .It \&)
1.2 kristaps 95: .Pq right-parenthesis
1.1 kristaps 96: .It \&[
1.2 kristaps 97: .Pq left-bracket
1.1 kristaps 98: .It \&]
1.2 kristaps 99: .Pq right-bracket
1.1 kristaps 100: .It \&?
1.2 kristaps 101: .Pq question
1.1 kristaps 102: .It \&!
1.5 kristaps 103: .Pq exclamation
1.28 ! kristaps 104: .It \&|
! 105: .Pq vertical bar
1.1 kristaps 106: .El
1.5 kristaps 107: .\" PARAGRAPH
1.1 kristaps 108: .Pp
1.5 kristaps 109: Use of reserved characters is described in
110: .Sx Closure .
111: For general non-reserved use, characters must either be escaped with a
112: non-breaking space
1.1 kristaps 113: .Pq Sq \e&
1.5 kristaps 114: or, if applicable, an appropriate escape-sequence used.
1.1 kristaps 115: .\" SUB-SECTION
116: .Ss Special Characters
117: Special character sequences begin with the escape character
1.16 kristaps 118: .Sq \e
1.4 kristaps 119: followed by either an open-parenthesis
1.1 kristaps 120: .Sq \&(
121: for two-character sequences; an open-bracket
122: .Sq \&[
123: for n-character sequences (terminated at a close-bracket
124: .Sq \&] ) ;
125: or a single one-character sequence.
126: .Pp
127: Characters may alternatively be escaped by a slash-asterisk,
1.16 kristaps 128: .Sq \e* ,
1.4 kristaps 129: with the same combinations as described above. This form is deprecated.
1.1 kristaps 130: .\" SECTION
1.17 kristaps 131: .Sh STRUCTURE
1.13 kristaps 132: Macros are classified in an ontology described by their scope rules.
133: Some macros are allowed to deviate from their classifications to
134: preserve backward-compatibility with old macro combinations still found
135: in the manual corpus. These are specifically noted on a per-macro
136: basis.
1.4 kristaps 137: .\" SUB-SECTION
138: .Ss Scope
1.2 kristaps 139: .Bl -inset
1.1 kristaps 140: .\" LIST-ITEM
141: .It Em Block
1.2 kristaps 142: macros enclose other block macros, in-line macros or text, and
1.4 kristaps 143: may span multiple lines.
1.2 kristaps 144: .Bl -inset -offset XXXX
1.1 kristaps 145: .\" LIST-ITEM
146: .It Em Full-block
1.5 kristaps 147: macros always span multiple lines. They consist of zero or
1.2 kristaps 148: more
1.1 kristaps 149: .Qq heads ,
1.5 kristaps 150: subsequent macros or text on the same line following invocation; an
151: optional
1.1 kristaps 152: .Qq body ,
153: which spans subsequent lines of text or macros; and an optional
154: .Qq tail ,
155: macros or text on the same line following closure.
156: .\" LIST-ITEM
157: .It Em Partial-block
1.5 kristaps 158: macros may span multiple lines. They consists of a optional
1.1 kristaps 159: .Qq head ,
160: text immediately following invocation; always a
161: .Qq body ,
162: text or macros following the head on the same and subsequent lines; and
163: optionally a
164: .Qq tail ,
165: text immediately following closure.
166: .\" LIST-ITEM
167: .It Em In-line
1.4 kristaps 168: macros may only enclose text and span at most a single line.
169: .El
170: .El
171: .\" SUB-SECTION
172: .Ss Closure
173: Closure of a macro's scope depends first on its classification, then
174: on whether it's parsable. In this table,
175: .Sq BFE
176: refers to block full-explicit and so on.
177: .\" PARAGRAPH
178: .Pp
179: .Bl -tag -width 12n -offset XXXX -compact
180: .It BPE , BFE
181: corresponding explicit closure macro
182: .It BFI
183: end-of-file or a corresponding implicit closure macro
184: .It BPI
185: end-of-line (body may be closed by >0 space-separated
186: .Sx Reserved Characters ,
187: although block scope will still be open)
188: .It INL
189: end-of-line
1.1 kristaps 190: .El
1.4 kristaps 191: .\" PARAGRAPH
192: .Pp
193: If a macro (block or in-line) is parsable, it may also be closed out by
194: one of the following scenarios (unless specifically noted otherwise):
195: .\" PARAGRAPH
196: .Pp
197: .Bl -dash -offset XXXX -compact
198: .It
199: a sequence of >0 space-separated
200: .Sx Reserved Characters ,
201: .It
202: another macro,
203: .It
204: end-of-line, or
205: .It
206: completion of a set number of arguments.
207: .El
208: .\" PARAGRAPH
209: .Pp
210: If >0 space-separated
211: .Sx Reserved Characters
212: are followed by non-reserved characters, the behaviour differs per
213: macro. In general, scope of the macro is closed and re-opened:
214: subsequent tokens are interpreted as if the scope had just been opened.
215: In other circumstances, scope is simply closed out.
1.1 kristaps 216: .\" SECTION
1.2 kristaps 217: .Sh SYNTAX
1.17 kristaps 218: Macros are two or three characters in length. The syntax of macro
219: invocation depends on its classification.
1.2 kristaps 220: .Qq \-arg
221: refers to the macro arguments (which may contain zero or more values).
222: In these illustrations,
223: .Sq \&.Yo
224: opens the scope of a macro, and if specified,
225: .Sq \&.Yc
226: closes it out (closure may be implicit at end-of-line or end-of-file).
1.4 kristaps 227: .\" PARAGRAPH
1.2 kristaps 228: .Pp
1.4 kristaps 229: Block full-explicit (may contain head, body, tail).
1.2 kristaps 230: .Bd -literal -offset XXXX
1.4 kristaps 231: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
232: \(lBbody...\(rB
233: \&.Yc \(lBtail...\(rB
1.2 kristaps 234: .Ed
1.4 kristaps 235: .\" PARAGRAPH
1.2 kristaps 236: .Pp
1.4 kristaps 237: Block full-implicit (may contain zero or more heads, body, no tail).
1.2 kristaps 238: .Bd -literal -offset XXXX
1.4 kristaps 239: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
240: \(lBbody...\(rB
1.2 kristaps 241: \&.Yc
242: .Ed
1.4 kristaps 243: .\" PARAGRAPH
1.2 kristaps 244: .Pp
1.4 kristaps 245: Block partial-explicit (may contain head, multi-line body, tail).
1.2 kristaps 246: .Bd -literal -offset XXXX
247: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
1.4 kristaps 248: \(lBbody...\(rB
249: \&.Yc \(lBtail...\(rB
1.2 kristaps 250:
251: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
1.4 kristaps 252: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2 kristaps 253: .Ed
1.4 kristaps 254: .\" PARAGRAPH
1.2 kristaps 255: .Pp
1.4 kristaps 256: Block partial-implicit (no head, body, no tail). Note that the body
257: section may be followed by zero or more
258: .Sx Reserved Words .
259: These are in the block scope, but not in the body scope.
1.2 kristaps 260: .Bd -literal -offset XXXX
1.4 kristaps 261: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
1.2 kristaps 262: .Ed
1.4 kristaps 263: .\" PARAGRAPH
1.2 kristaps 264: .Pp
1.4 kristaps 265: In-lines have \(>=0 scoped arguments.
1.2 kristaps 266: .Bd -literal -offset XXX
1.4 kristaps 267: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
1.2 kristaps 268:
269: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
270: .Ed
271: .\"
1.1 kristaps 272: .Sh MACROS
273: This section contains a complete list of all
274: .Nm
1.2 kristaps 275: macros, arranged ontologically. A
1.1 kristaps 276: .Qq callable
1.17 kristaps 277: macro is invoked subsequent to the initial macro-line macro. A
1.1 kristaps 278: .Qq parsable
1.2 kristaps 279: macro may be followed by further (ostensibly callable) macros.
1.1 kristaps 280: .\" SUB-SECTION
281: .Ss Block full-implicit
282: The head of these macros follows invocation; the body is the content of
283: subsequent lines prior to closure. None of these macros have tails;
284: some
285: .Po
1.16 kristaps 286: .Sq \&.It \-bullet ,
1.1 kristaps 287: .Sq \-hyphen ,
288: .Sq \-dash ,
1.2 kristaps 289: .Sq \-enum ,
290: .Sq \-item
1.1 kristaps 291: .Pc
292: don't have heads.
293: .Pp
294: .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
295: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
296: .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
297: .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
298: .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
299: .El
300: .\" SUB-SECTION
301: .Ss Block full-explicit
302: None of these macros are callable or parsed. The last column indicates
303: the explicit scope rules. All contains bodies, some may contain heads
304: .Pq So \&Bf Sc .
305: .Pp
306: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
307: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
308: .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
309: .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
310: .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
311: .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
312: .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
313: .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
1.2 kristaps 314: .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
315: .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
1.1 kristaps 316: .El
317: .\" SUB-SECTION
318: .Ss Block partial-implicit
319: All of these are callable and parsed for further macros. Their scopes
320: close at the invocation's end-of-line.
321: .Pp
322: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
323: .It Em Macro Ta Em Callable Ta Em Parsable
324: .It \&.Aq Ta Yes Ta Yes
325: .It \&.Op Ta Yes Ta Yes
326: .It \&.Bq Ta Yes Ta Yes
327: .It \&.Dq Ta Yes Ta Yes
328: .It \&.Pq Ta Yes Ta Yes
329: .It \&.Qq Ta Yes Ta Yes
330: .It \&.Sq Ta Yes Ta Yes
331: .It \&.Brq Ta Yes Ta Yes
1.2 kristaps 332: .It \&.D1 Ta \&No Ta \&Yes
333: .It \&.Dl Ta \&No Ta Yes
334: .It \&.Ql Ta Yes Ta Yes
1.1 kristaps 335: .El
1.13 kristaps 336: .\" PARAGRAPH
337: .Pp
338: The
1.16 kristaps 339: .Sq \&.Op
340: may be broken by
341: .Sq \&.Oc
342: as in the following example:
1.13 kristaps 343: .Bd -literal -offset XXXX
344: \&.Oo
345: \&.Op Fl a Oc
346: .Ed
347: .Pp
348: In the above example, the scope of
1.16 kristaps 349: .Sq \&.Op
1.13 kristaps 350: is technically broken by
1.16 kristaps 351: .Sq \&.Oc ,
1.13 kristaps 352: however, due to the overwhelming existence of this sequence, it's
353: allowed.
1.1 kristaps 354: .\" SUB-SECTION
355: .Ss Block partial-explicit
356: Each of these contains at least a body and, in limited circumstances, a
357: head
1.16 kristaps 358: .Pq So \&.Fo Sc , So \&.Eo Sc
1.1 kristaps 359: and/or tail
1.16 kristaps 360: .Pq So \&.Ec Sc .
1.1 kristaps 361: .Pp
362: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
363: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
364: .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
365: .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
366: .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
367: .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
368: .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
369: .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
370: .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
371: .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
372: .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
373: .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
374: .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
375: .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
376: .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
377: .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
378: .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
379: .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
380: .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
381: .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
382: .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
383: .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
384: .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
385: .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
1.2 kristaps 386: .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
387: .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
1.1 kristaps 388: .El
389: .\" SUB-SECTION
1.2 kristaps 390: .Ss In-line
1.3 kristaps 391: In-line macros have only text children. If a number (or inequality) of
392: arguments is
393: .Pq n ,
394: then the macro accepts an arbitrary number of arguments.
1.2 kristaps 395: .Pp
396: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
397: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.3 kristaps 398: .It \&.Dd Ta \&No Ta \&No Ta >0
399: .It \&.Dt Ta \&No Ta \&No Ta n
400: .It \&.Os Ta \&No Ta \&No Ta n
1.2 kristaps 401: .It \&.Pp Ta \&No Ta \&No Ta 0
1.3 kristaps 402: .It \&.Ad Ta Yes Ta Yes Ta n
1.25 kristaps 403: .It \&.An Ta Yes Ta Yes Ta n
1.3 kristaps 404: .It \&.Ar Ta Yes Ta Yes Ta n
405: .It \&.Cd Ta Yes Ta \&No Ta >0
406: .It \&.Cm Ta Yes Ta Yes Ta n
1.11 kristaps 407: .It \&.Dv Ta Yes Ta Yes Ta n
1.3 kristaps 408: .It \&.Er Ta Yes Ta Yes Ta >0
1.11 kristaps 409: .It \&.Ev Ta Yes Ta Yes Ta n
1.3 kristaps 410: .It \&.Ex Ta \&No Ta \&No Ta 0
1.12 kristaps 411: .It \&.Fa Ta Yes Ta Yes Ta n
1.3 kristaps 412: .It \&.Fd Ta \&No Ta \&No Ta >0
413: .It \&.Fl Ta Yes Ta Yes Ta n
414: .It \&.Fn Ta Yes Ta Yes Ta >0
1.26 kristaps 415: .It \&.Ft Ta Yes Ta Yes Ta n
1.3 kristaps 416: .It \&.Ic Ta Yes Ta Yes Ta >0
417: .It \&.In Ta \&No Ta \&No Ta n
1.11 kristaps 418: .It \&.Li Ta Yes Ta Yes Ta n
1.3 kristaps 419: .It \&.Nd Ta \&No Ta \&No Ta n
420: .It \&.Nm Ta Yes Ta Yes Ta n
421: .It \&.Ot Ta \&No Ta \&No Ta n
422: .It \&.Pa Ta Yes Ta Yes Ta n
423: .It \&.Rv Ta \&No Ta \&No Ta 0
424: .It \&.St Ta \&No Ta Yes Ta 1
1.11 kristaps 425: .It \&.Va Ta Yes Ta Yes Ta n
1.3 kristaps 426: .It \&.Vt Ta Yes Ta Yes Ta >0
427: .It \&.Xr Ta Yes Ta Yes Ta >0, <3
428: .It \&.%A Ta \&No Ta \&No Ta >0
429: .It \&.%B Ta \&No Ta \&No Ta >0
430: .It \&.%C Ta \&No Ta \&No Ta >0
431: .It \&.%D Ta \&No Ta \&No Ta >0
432: .It \&.%I Ta \&No Ta \&No Ta >0
433: .It \&.%J Ta \&No Ta \&No Ta >0
434: .It \&.%N Ta \&No Ta \&No Ta >0
435: .It \&.%O Ta \&No Ta \&No Ta >0
436: .It \&.%P Ta \&No Ta \&No Ta >0
437: .It \&.%R Ta \&No Ta \&No Ta >0
438: .It \&.%T Ta \&No Ta \&No Ta >0
439: .It \&.%V Ta \&No Ta \&No Ta >0
440: .It \&.At Ta Yes Ta Yes Ta 1
441: .It \&.Bsx Ta Yes Ta Yes Ta n
442: .It \&.Bx Ta Yes Ta Yes Ta n
443: .It \&.Db Ta \&No Ta \&No Ta 1
1.19 kristaps 444: .It \&.Em Ta Yes Ta Yes Ta >0
1.3 kristaps 445: .It \&.Fx Ta Yes Ta Yes Ta n
1.26 kristaps 446: .It \&.Ms Ta Yes Ta Yes Ta >0
1.3 kristaps 447: .It \&.No Ta Yes Ta Yes Ta 0
448: .It \&.Ns Ta Yes Ta Yes Ta 0
449: .It \&.Nx Ta Yes Ta Yes Ta n
450: .It \&.Ox Ta Yes Ta Yes Ta n
451: .It \&.Pf Ta \&No Ta Yes Ta 1
452: .It \&.Sm Ta \&No Ta \&No Ta 1
453: .It \&.Sx Ta Yes Ta Yes Ta >0
454: .It \&.Sy Ta Yes Ta Yes Ta >0
455: .It \&.Tn Ta Yes Ta Yes Ta >0
456: .It \&.Ux Ta Yes Ta Yes Ta n
1.6 kristaps 457: .It \&.Dx Ta Yes Ta Yes Ta n
1.3 kristaps 458: .It \&.Bt Ta \&No Ta \&No Ta 0
459: .It \&.Hf Ta \&No Ta \&No Ta n
460: .It \&.Fr Ta \&No Ta \&No Ta n
461: .It \&.Ud Ta \&No Ta \&No Ta 0
462: .It \&.Lb Ta \&No Ta \&No Ta 1
463: .It \&.Ap Ta Yes Ta Yes Ta 0
464: .It \&.Lp Ta \&No Ta \&No Ta 0
1.27 kristaps 465: .It \&.Lk Ta Yes Ta Yes Ta n
466: .It \&.Mt Ta Yes Ta Yes Ta >0
1.6 kristaps 467: .It \&.Es Ta \&No Ta \&No Ta 0
468: .It \&.En Ta \&No Ta \&No Ta 0
1.1 kristaps 469: .El
1.6 kristaps 470: .Pp
471: The
1.16 kristaps 472: .Sq \&.Ot ,
473: .Sq \&.Fr ,
474: .Sq \&.Es
1.6 kristaps 475: and
1.16 kristaps 476: .Sq \&.En ,
1.6 kristaps 477: macros are obsolete.
1.2 kristaps 478: .\" SECTION
1.4 kristaps 479: .Sh COMPATIBILITY
1.28 ! kristaps 480: This section documents compatibility with other roff implementations, at
! 481: this time limited to
! 482: .Xr groff 1 .
! 483: The term
! 484: .Qq historic groff
! 485: refers to those versions before the
! 486: .Pa doc.tmac
! 487: file re-write
! 488: .Pq somewhere between 1.15 and 1.19 .
1.4 kristaps 489: .Pp
490: .Bl -dash -compact
491: .\" LIST-ITEM
492: .It
1.28 ! kristaps 493: Historic groff has many un-callable macros. Most of these (excluding
! 494: some block-level macros) are now callable, conforming to the
! 495: non-historic groff version.
! 496: .\" LIST-ITEM
! 497: .It
! 498: The vertical bar
! 499: .Sq \(Ba
! 500: made historic groff
! 501: .Qq go orbital
! 502: but is a proper delimiter in this implementation.
1.5 kristaps 503: .\" LIST-ITEM
504: .It
1.16 kristaps 505: .Sq \&.It \-nested
1.28 ! kristaps 506: is assumed for all lists (it wasn't in historic groff): any list may be
! 507: nested and
1.4 kristaps 508: .Sq \-enum
509: lists will restart the sequence only for the sub-list.
510: .\" LIST-ITEM
511: .It
1.16 kristaps 512: .Sq \&.It \-column
1.21 kristaps 513: syntax where column widths may be preceded by other arguments (instead
1.4 kristaps 514: of proceeded) is not supported.
515: .\" LIST-ITEM
516: .It
517: The
1.16 kristaps 518: .Sq \&.At
1.4 kristaps 519: macro only accepts a single parameter.
520: .\" LIST-ITEM
521: .It
522: Some manuals use
1.16 kristaps 523: .Sq \&.Li
1.4 kristaps 524: incorrectly by following it with a reserved character and expecting the
525: delimiter to render. This is not supported.
526: .\" LIST-ITEM
527: .It
1.28 ! kristaps 528: If an special-character control character
! 529: .Sq \e
! 530: is escaped, it will
! 531: obviously not render the sequence. Even newer versions of groff seem to
! 532: dither on this.
1.4 kristaps 533: .El
534: .\" SECTION
1.2 kristaps 535: .Sh SEE ALSO
1.19 kristaps 536: .Xr mandoc 1 ,
537: .Xr mandoc_char 7
1.2 kristaps 538: .\" SECTION
539: .Sh AUTHORS
540: The
541: .Nm
542: utility was written by
1.24 kristaps 543: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.5 kristaps 544: .\" SECTION
545: .Sh CAVEATS
1.28 ! kristaps 546: There are many ambiguous parts of mdoc.
1.5 kristaps 547: .Pp
548: .Bl -dash -compact
549: .\" LIST-ITEM
550: .It
1.16 kristaps 551: .Sq \&.Fa
1.5 kristaps 552: should be
1.16 kristaps 553: .Sq \&.Va
1.5 kristaps 554: as function arguments are variables.
555: .\" LIST-ITEM
556: .It
1.16 kristaps 557: .Sq \&.Ft
1.5 kristaps 558: should be
1.16 kristaps 559: .Sq \&.Vt
1.5 kristaps 560: as function return types are still types. Furthermore, the
1.16 kristaps 561: .Sq \&.Ft
1.5 kristaps 562: should be removed and
1.16 kristaps 563: .Sq \&.Fo ,
1.5 kristaps 564: which ostensibly follows it, should follow the same convention as
1.16 kristaps 565: .Sq \&.Va .
1.5 kristaps 566: .\" LIST-ITEM
567: .It
1.16 kristaps 568: .Sq \&.Va
1.5 kristaps 569: should formalise that only one or two arguments are acceptable: a
1.21 kristaps 570: variable name and optional, preceding type.
1.5 kristaps 571: .\" LIST-ITEM
572: .It
1.16 kristaps 573: .Sq \&.Fd
1.5 kristaps 574: is ambiguous. It's commonly used to indicate an include file in the
575: synopsis section.
1.16 kristaps 576: .Sq \&.In
1.5 kristaps 577: should be used, instead.
578: .\" LIST-ITEM
579: .It
580: Only the
581: .Sq \-literal
582: argument to
1.16 kristaps 583: .Sq \&.Bd
1.5 kristaps 584: makes sense. The remaining ones should be removed.
585: .\" LIST-ITEM
586: .It
587: The
1.16 kristaps 588: .Sq \&.Xo
1.5 kristaps 589: and
1.16 kristaps 590: .Sq \&.Xc
1.5 kristaps 591: macros should be deprecated.
592: .\" LIST-ITEM
593: .It
594: The
1.16 kristaps 595: .Sq \&.Dt
1.5 kristaps 596: macro lacks clarity. It should be absolutely clear which title will
597: render when formatting the manual page.
1.6 kristaps 598: .\" LIST-ITEM
599: .It
600: A
1.16 kristaps 601: .Sq \&.Lx
1.6 kristaps 602: should be provided for Linux (\(`a la
1.16 kristaps 603: .Sq \&.Ox ,
604: .Sq \&.Nx
1.6 kristaps 605: etc.).
1.14 kristaps 606: .\" LIST-ITEM
607: .It
608: There's no way to refer to references in
1.16 kristaps 609: .Sq \&.Rs/.Re
1.14 kristaps 610: blocks.
1.5 kristaps 611: .El
CVSweb