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