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