Annotation of mandoc/mdoc.7, Revision 1.6
1.6 ! kristaps 1: .\" $Id: mdoc.7,v 1.5 2009/03/16 22:19:19 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$
20: .Dt mdoc 7
21: .Os
22: .\" SECTION
23: .Sh NAME
24: .Nm mdoc
25: .Nd mdoc macro reference
26: .\" SECTION
27: .Sh DESCRIPTION
28: The
29: .Nm mdoc
30: language is used to format
31: .Bx
32: .Ux
33: manuals. An
34: .Nm
35: document follows simple rules: lines beginning with the control
36: character
37: .Sq \.
38: are parsed for macros. Other lines are interpreted within the scope of
1.3 kristaps 39: prior macros. This document describes the encoding, ontology and syntax
40: of these macros.
1.1 kristaps 41: .\" SECTION
42: .Sh CHARACTER ENCODING
43: .Nm
1.6 ! kristaps 44: documents may contain only printable characters, the space character
1.1 kristaps 45: .Sq \ ,
46: and, in certain circumstances, the tab character
47: .Sq \et .
48: All manuals must have
49: .Sq \en
50: line termination.
51: .\" SUB-SECTION
1.2 kristaps 52: .Ss Reserved Characters
53: Within a macro line, the following characters are reserved:
54: .Bl -tag -width 12n -offset XXXX -compact
1.1 kristaps 55: .It \&.
1.2 kristaps 56: .Pq period
1.1 kristaps 57: .It \&,
1.2 kristaps 58: .Pq comma
1.1 kristaps 59: .It \&:
1.2 kristaps 60: .Pq colon
1.1 kristaps 61: .It \&;
1.2 kristaps 62: .Pq semicolon
1.1 kristaps 63: .It \&(
1.2 kristaps 64: .Pq left-parenthesis
1.1 kristaps 65: .It \&)
1.2 kristaps 66: .Pq right-parenthesis
1.1 kristaps 67: .It \&[
1.2 kristaps 68: .Pq left-bracket
1.1 kristaps 69: .It \&]
1.2 kristaps 70: .Pq right-bracket
1.1 kristaps 71: .It \&?
1.2 kristaps 72: .Pq question
1.1 kristaps 73: .It \&!
1.5 kristaps 74: .Pq exclamation
1.1 kristaps 75: .El
1.5 kristaps 76: .\" PARAGRAPH
1.1 kristaps 77: .Pp
1.5 kristaps 78: Use of reserved characters is described in
79: .Sx Closure .
80: For general non-reserved use, characters must either be escaped with a
81: non-breaking space
1.1 kristaps 82: .Pq Sq \e&
1.5 kristaps 83: or, if applicable, an appropriate escape-sequence used.
1.1 kristaps 84: .\" SUB-SECTION
85: .Ss Special Characters
86: Special character sequences begin with the escape character
87: .Sq \\
1.4 kristaps 88: followed by either an open-parenthesis
1.1 kristaps 89: .Sq \&(
90: for two-character sequences; an open-bracket
91: .Sq \&[
92: for n-character sequences (terminated at a close-bracket
93: .Sq \&] ) ;
94: or a single one-character sequence.
95: .Pp
96: Characters may alternatively be escaped by a slash-asterisk,
97: .Sq \\* ,
1.4 kristaps 98: with the same combinations as described above. This form is deprecated.
99: .Pp
100: The following is a table of all available escapes.
1.1 kristaps 101: .Pp
102: Grammatic:
103: .Bl -tag -width 12n -offset "XXXX" -compact
104: .It \\(em
105: .Pq em-dash
106: .It \\(en
107: .Pq en-dash
108: .It \e-
109: .Pq hyphen
110: .It \\\\
111: .Pq back-slash
112: .It \e'
113: .Pq apostrophe
114: .It \e`
115: .Pq back-tick
116: .It \\
117: .Pq space
118: .It \\.
119: .Pq period
120: .El
121: .\" PARAGRAPH
122: .Pp
123: Enclosures:
124: .Bl -tag -width 12n -offset "XXXX" -compact
1.5 kristaps 125: .It \\(lh
126: .Pq left hand
127: .It \\(rh
128: .Pq right hand
129: .It \\(<<
130: .Pq left guillemot
131: .It \\(>>
132: .Pq right guillemot
1.1 kristaps 133: .It \\(rC
134: .Pq right brace
135: .It \\(lC
136: .Pq left brace
137: .It \\(ra
138: .Pq right angle
139: .It \\(la
140: .Pq left angle
141: .It \\(rB
142: .Pq right bracket
143: .It \\(lB
144: .Pq left bracket
145: .It \\q
146: .Pq double-quote
147: .It \\(lq
148: .Pq left double-quote
149: .It \\(Lq
150: .Pq left double-quote, deprecated
151: .It \\(rq
152: .Pq right double-quote
153: .It \\(Rq
154: .Pq right double-quote, deprecated
155: .It \\(oq
156: .Pq left single-quote
157: .It \\(aq
158: .Pq right single-quote
159: .El
160: .\" PARAGRAPH
161: .Pp
162: Indicatives:
163: .Bl -tag -width 12n -offset "XXXX" -compact
164: .It \\(<-
165: .Pq left arrow
166: .It \\(->
167: .Pq right arrow
168: .It \\(ua
169: .Pq up arrow
170: .It \\(da
171: .Pq down arrow
1.5 kristaps 172: .It \\(<>
173: .Pq left-right arrow
174: .It \\(lA
175: .Pq left double-arrow
176: .It \\(rA
177: .Pq right double-arrow
178: .It \\(uA
179: .Pq up double-arrow
180: .It \\(dA
181: .Pq down double-arrow
182: .It \\(hA
183: .Pq left-right double-arrow
1.1 kristaps 184: .El
185: .\" PARAGRAPH
186: .Pp
187: Mathematical:
188: .Bl -tag -width 12n -offset "XXXX" -compact
189: .It \\(Gt
190: .Pq greater-than, deprecated
191: .It \\(Lt
192: .Pq less-than, deprecated
193: .It \\(<=
194: .Pq less-than-equal
195: .It \\(Le
196: .Pq less-than-equal, deprecated
197: .It \\(>=
198: .Pq greater-than-equal
199: .It \\(Ge
200: .Pq greater-than-equal
201: .It \\(==
202: .Pq equal
203: .It \\(!=
204: .Pq not equal
205: .It \\(Ne
206: .Pq not equal, deprecated
207: .It \\(if
208: .Pq infinity
209: .It \\(If
210: .Pq infinity, deprecated
211: .It \\(na
212: .Pq NaN , an extension
213: .It \\(Na
214: .Pq NaN, deprecated
215: .It \\(+-
216: .Pq plus-minus
217: .It \\(Pm
218: .Pq plus-minus, deprecated
219: .It \\(**
220: .Pq asterisk
221: .El
222: .\" PARAGRAPH
223: .Pp
1.5 kristaps 224: Diacritics and letter combinations:
1.1 kristaps 225: .Bl -tag -width 12n -offset "XXXX" -compact
226: .It \\(ga
227: .Pq accent grave
228: .It \\(aa
229: .Pq accent accute
1.5 kristaps 230: .It \\(ad
231: .Pq accent dieresis
232: .It \\(a~
233: .Pq accent tilde
234: .It \\(AE
235: .Pq upper-case AE
236: .It \\(ae
237: .Pq lower-case AE
238: .It \\(OE
239: .Pq upper-case OE
240: .It \\(oe
241: .Pq lower-case OE
242: .It \\('A
243: .Pq upper-case acute A
244: .It \\('E
245: .Pq upper-case acute E
246: .It \\('I
247: .Pq upper-case acute I
248: .It \\('O
249: .Pq upper-case acute O
250: .It \\('U
251: .Pq upper-case acute U
252: .It \\('a
253: .Pq lower-case acute a
254: .It \\('e
255: .Pq lower-case acute e
256: .It \\('i
257: .Pq lower-case acute i
258: .It \\('o
259: .Pq lower-case acute o
260: .It \\('u
261: .Pq lower-case acute u
262: .It \\(`A
263: .Pq upper-case grave A
264: .It \\(`E
265: .Pq upper-case grave E
266: .It \\(`I
267: .Pq upper-case grave I
268: .It \\(`O
269: .Pq upper-case grave O
270: .It \\(`U
271: .Pq upper-case grave U
272: .It \\(`a
273: .Pq lower-case grave a
274: .It \\(`e
275: .Pq lower-case grave e
276: .It \\(`i
277: .Pq lower-case grave i
278: .It \\(`o
279: .Pq lower-case grave o
280: .It \\(`u
281: .Pq lower-case grave u
282: .It \\(~A
283: .Pq upper-case tilde A
284: .It \\(~N
285: .Pq upper-case tilde N
286: .It \\(~O
287: .Pq upper-case tilde O
288: .It \\(~a
289: .Pq lower-case tilde a
290: .It \\(~n
291: .Pq lower-case tilde n
292: .It \\(~o
293: .Pq lower-case tilde o
294: .It \\(:A
295: .Pq upper-case dieresis A
296: .It \\(:E
297: .Pq upper-case dieresis E
298: .It \\(:I
299: .Pq upper-case dieresis I
300: .It \\(:O
301: .Pq upper-case dieresis O
302: .It \\(:U
303: .Pq upper-case dieresis U
304: .It \\(:a
305: .Pq lower-case dieresis a
306: .It \\(:e
307: .Pq lower-case dieresis e
308: .It \\(:i
309: .Pq lower-case dieresis i
310: .It \\(:o
311: .Pq lower-case dieresis o
312: .It \\(:u
313: .Pq lower-case dieresis u
314: .It \\(:y
315: .Pq lower-case dieresis y
1.1 kristaps 316: .El
317: .\" PARAGRAPH
318: .Pp
319: Special symbols:
320: .Bl -tag -width 12n -offset "XXXX" -compact
321: .It \\(bu
322: .Pq bullet
323: .It \\(ba
324: .Pq bar
325: .It \\(Ba
326: .Pq bar, deprecated
327: .It \\(co
328: .Pq copyright
1.5 kristaps 329: .It \\(rg
330: .Pq registered
331: .It \\(tm
332: .Pq trademarked
1.1 kristaps 333: .It \\&
334: .Pq non-breaking space
335: .It \\e
336: .Pq escape
337: .It \\(Am
338: .Pq ampersand, deprecated
339: .El
340: .\" SECTION
1.2 kristaps 341: .Sh ONTOLOGY
1.1 kristaps 342: Macros are classified in an ontology described by scope rules.
1.4 kristaps 343: .\" SUB-SECTION
344: .Ss Scope
1.2 kristaps 345: .Bl -inset
1.1 kristaps 346: .\" LIST-ITEM
347: .It Em Block
1.2 kristaps 348: macros enclose other block macros, in-line macros or text, and
1.4 kristaps 349: may span multiple lines.
1.2 kristaps 350: .Bl -inset -offset XXXX
1.1 kristaps 351: .\" LIST-ITEM
352: .It Em Full-block
1.5 kristaps 353: macros always span multiple lines. They consist of zero or
1.2 kristaps 354: more
1.1 kristaps 355: .Qq heads ,
1.5 kristaps 356: subsequent macros or text on the same line following invocation; an
357: optional
1.1 kristaps 358: .Qq body ,
359: which spans subsequent lines of text or macros; and an optional
360: .Qq tail ,
361: macros or text on the same line following closure.
362: .\" LIST-ITEM
363: .It Em Partial-block
1.5 kristaps 364: macros may span multiple lines. They consists of a optional
1.1 kristaps 365: .Qq head ,
366: text immediately following invocation; always a
367: .Qq body ,
368: text or macros following the head on the same and subsequent lines; and
369: optionally a
370: .Qq tail ,
371: text immediately following closure.
372: .\" LIST-ITEM
373: .It Em In-line
1.4 kristaps 374: macros may only enclose text and span at most a single line.
375: .El
376: .El
377: .\" SUB-SECTION
378: .Ss Closure
379: Closure of a macro's scope depends first on its classification, then
380: on whether it's parsable. In this table,
381: .Sq BFE
382: refers to block full-explicit and so on.
383: .\" PARAGRAPH
384: .Pp
385: .Bl -tag -width 12n -offset XXXX -compact
386: .It BPE , BFE
387: corresponding explicit closure macro
388: .It BFI
389: end-of-file or a corresponding implicit closure macro
390: .It BPI
391: end-of-line (body may be closed by >0 space-separated
392: .Sx Reserved Characters ,
393: although block scope will still be open)
394: .It INL
395: end-of-line
1.1 kristaps 396: .El
1.4 kristaps 397: .\" PARAGRAPH
398: .Pp
399: If a macro (block or in-line) is parsable, it may also be closed out by
400: one of the following scenarios (unless specifically noted otherwise):
401: .\" PARAGRAPH
402: .Pp
403: .Bl -dash -offset XXXX -compact
404: .It
405: a sequence of >0 space-separated
406: .Sx Reserved Characters ,
407: .It
408: another macro,
409: .It
410: end-of-line, or
411: .It
412: completion of a set number of arguments.
413: .El
414: .\" PARAGRAPH
415: .Pp
416: If >0 space-separated
417: .Sx Reserved Characters
418: are followed by non-reserved characters, the behaviour differs per
419: macro. In general, scope of the macro is closed and re-opened:
420: subsequent tokens are interpreted as if the scope had just been opened.
421: In other circumstances, scope is simply closed out.
1.1 kristaps 422: .\" SECTION
1.2 kristaps 423: .Sh SYNTAX
1.3 kristaps 424: Macros are generally two and at times three characters in length. The
425: syntax of macro invocation depends on its classification.
1.2 kristaps 426: .Qq \-arg
427: refers to the macro arguments (which may contain zero or more values).
428: In these illustrations,
429: .Sq \&.Yo
430: opens the scope of a macro, and if specified,
431: .Sq \&.Yc
432: closes it out (closure may be implicit at end-of-line or end-of-file).
1.4 kristaps 433: .\" PARAGRAPH
1.2 kristaps 434: .Pp
1.4 kristaps 435: Block full-explicit (may contain head, body, tail).
1.2 kristaps 436: .Bd -literal -offset XXXX
1.4 kristaps 437: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
438: \(lBbody...\(rB
439: \&.Yc \(lBtail...\(rB
1.2 kristaps 440: .Ed
1.4 kristaps 441: .\" PARAGRAPH
1.2 kristaps 442: .Pp
1.4 kristaps 443: Block full-implicit (may contain zero or more heads, body, no tail).
1.2 kristaps 444: .Bd -literal -offset XXXX
1.4 kristaps 445: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
446: \(lBbody...\(rB
1.2 kristaps 447: \&.Yc
448: .Ed
1.4 kristaps 449: .\" PARAGRAPH
1.2 kristaps 450: .Pp
1.4 kristaps 451: Block partial-explicit (may contain head, multi-line body, tail).
1.2 kristaps 452: .Bd -literal -offset XXXX
453: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
1.4 kristaps 454: \(lBbody...\(rB
455: \&.Yc \(lBtail...\(rB
1.2 kristaps 456:
457: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
1.4 kristaps 458: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2 kristaps 459: .Ed
1.4 kristaps 460: .\" PARAGRAPH
1.2 kristaps 461: .Pp
1.4 kristaps 462: Block partial-implicit (no head, body, no tail). Note that the body
463: section may be followed by zero or more
464: .Sx Reserved Words .
465: These are in the block scope, but not in the body scope.
1.2 kristaps 466: .Bd -literal -offset XXXX
1.4 kristaps 467: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
1.2 kristaps 468: .Ed
1.4 kristaps 469: .\" PARAGRAPH
1.2 kristaps 470: .Pp
1.4 kristaps 471: In-lines have \(>=0 scoped arguments.
1.2 kristaps 472: .Bd -literal -offset XXX
1.4 kristaps 473: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
1.2 kristaps 474:
475: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
476: .Ed
477: .\"
1.1 kristaps 478: .Sh MACROS
479: This section contains a complete list of all
480: .Nm
1.2 kristaps 481: macros, arranged ontologically. A
1.1 kristaps 482: .Qq callable
483: macro is may be invoked subsequent to the initial macro-line macro. A
484: .Qq parsable
1.2 kristaps 485: macro may be followed by further (ostensibly callable) macros.
1.1 kristaps 486: .\" SUB-SECTION
487: .Ss Block full-implicit
488: The head of these macros follows invocation; the body is the content of
489: subsequent lines prior to closure. None of these macros have tails;
490: some
491: .Po
492: .Sq \&It \-bullet ,
493: .Sq \-hyphen ,
494: .Sq \-dash ,
1.2 kristaps 495: .Sq \-enum ,
496: .Sq \-item
1.1 kristaps 497: .Pc
498: don't have heads.
499: .Pp
500: .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
501: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
502: .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
503: .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
504: .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
505: .El
506: .\" SUB-SECTION
507: .Ss Block full-explicit
508: None of these macros are callable or parsed. The last column indicates
509: the explicit scope rules. All contains bodies, some may contain heads
510: .Pq So \&Bf Sc .
511: .Pp
512: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
513: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
514: .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
515: .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
516: .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
517: .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
518: .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
519: .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
1.2 kristaps 520: .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
521: .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
1.1 kristaps 522: .El
523: .\" SUB-SECTION
524: .Ss Block partial-implicit
525: All of these are callable and parsed for further macros. Their scopes
526: close at the invocation's end-of-line.
527: .Pp
528: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
529: .It Em Macro Ta Em Callable Ta Em Parsable
530: .It \&.Aq Ta Yes Ta Yes
531: .It \&.Op Ta Yes Ta Yes
532: .It \&.Bq Ta Yes Ta Yes
533: .It \&.Dq Ta Yes Ta Yes
534: .It \&.Pq Ta Yes Ta Yes
535: .It \&.Qq Ta Yes Ta Yes
536: .It \&.Sq Ta Yes Ta Yes
537: .It \&.Brq Ta Yes Ta Yes
1.2 kristaps 538: .It \&.D1 Ta \&No Ta \&Yes
539: .It \&.Dl Ta \&No Ta Yes
540: .It \&.Ql Ta Yes Ta Yes
1.1 kristaps 541: .El
542: .\" SUB-SECTION
543: .Ss Block partial-explicit
544: Each of these contains at least a body and, in limited circumstances, a
545: head
546: .Pq So \&Fo Sc , So \&Eo Sc
547: and/or tail
548: .Pq So \&Ec Sc .
549: .Pp
550: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
551: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
552: .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
553: .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
554: .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
555: .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
556: .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
557: .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
558: .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
559: .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
560: .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
561: .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
562: .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
563: .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
564: .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
565: .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
566: .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
567: .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
568: .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
569: .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
570: .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
571: .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
572: .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
573: .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
1.2 kristaps 574: .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
575: .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
1.1 kristaps 576: .El
577: .\" SUB-SECTION
1.2 kristaps 578: .Ss In-line
1.3 kristaps 579: In-line macros have only text children. If a number (or inequality) of
580: arguments is
581: .Pq n ,
582: then the macro accepts an arbitrary number of arguments.
1.2 kristaps 583: .Pp
584: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
585: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.3 kristaps 586: .It \&.Dd Ta \&No Ta \&No Ta >0
587: .It \&.Dt Ta \&No Ta \&No Ta n
588: .It \&.Os Ta \&No Ta \&No Ta n
1.2 kristaps 589: .It \&.Pp Ta \&No Ta \&No Ta 0
1.3 kristaps 590: .It \&.Ad Ta Yes Ta Yes Ta n
591: .It \&.An Ta \&No Ta Yes Ta n
592: .It \&.Ar Ta Yes Ta Yes Ta n
593: .It \&.Cd Ta Yes Ta \&No Ta >0
594: .It \&.Cm Ta Yes Ta Yes Ta n
595: .It \&.Dv Ta Yes Ta Yes Ta >0
596: .It \&.Er Ta Yes Ta Yes Ta >0
597: .It \&.Ev Ta Yes Ta Yes Ta >0
598: .It \&.Ex Ta \&No Ta \&No Ta 0
599: .It \&.Fa Ta Yes Ta Yes Ta >0
600: .It \&.Fd Ta \&No Ta \&No Ta >0
601: .It \&.Fl Ta Yes Ta Yes Ta n
602: .It \&.Fn Ta Yes Ta Yes Ta >0
603: .It \&.Ft Ta \&No Ta Yes Ta n
604: .It \&.Ic Ta Yes Ta Yes Ta >0
605: .It \&.In Ta \&No Ta \&No Ta n
606: .It \&.Li Ta Yes Ta Yes Ta >0
607: .It \&.Nd Ta \&No Ta \&No Ta n
608: .It \&.Nm Ta Yes Ta Yes Ta n
609: .It \&.Ot Ta \&No Ta \&No Ta n
610: .It \&.Pa Ta Yes Ta Yes Ta n
611: .It \&.Rv Ta \&No Ta \&No Ta 0
612: .It \&.St Ta \&No Ta Yes Ta 1
613: .It \&.Va Ta Yes Ta Yes Ta >0
614: .It \&.Vt Ta Yes Ta Yes Ta >0
615: .It \&.Xr Ta Yes Ta Yes Ta >0, <3
616: .It \&.%A Ta \&No Ta \&No Ta >0
617: .It \&.%B Ta \&No Ta \&No Ta >0
618: .It \&.%C Ta \&No Ta \&No Ta >0
619: .It \&.%D Ta \&No Ta \&No Ta >0
620: .It \&.%I Ta \&No Ta \&No Ta >0
621: .It \&.%J Ta \&No Ta \&No Ta >0
622: .It \&.%N Ta \&No Ta \&No Ta >0
623: .It \&.%O Ta \&No Ta \&No Ta >0
624: .It \&.%P Ta \&No Ta \&No Ta >0
625: .It \&.%R Ta \&No Ta \&No Ta >0
626: .It \&.%T Ta \&No Ta \&No Ta >0
627: .It \&.%V Ta \&No Ta \&No Ta >0
628: .It \&.At Ta Yes Ta Yes Ta 1
629: .It \&.Bsx Ta Yes Ta Yes Ta n
630: .It \&.Bx Ta Yes Ta Yes Ta n
631: .It \&.Db Ta \&No Ta \&No Ta 1
632: .It \&.Em Ta Yes Ta Yes Ta >0
633: .It \&.Fx Ta Yes Ta Yes Ta n
634: .It \&.Ms Ta \&No Ta Yes Ta >0
635: .It \&.No Ta Yes Ta Yes Ta 0
636: .It \&.Ns Ta Yes Ta Yes Ta 0
637: .It \&.Nx Ta Yes Ta Yes Ta n
638: .It \&.Ox Ta Yes Ta Yes Ta n
639: .It \&.Pf Ta \&No Ta Yes Ta 1
640: .It \&.Sm Ta \&No Ta \&No Ta 1
641: .It \&.Sx Ta Yes Ta Yes Ta >0
642: .It \&.Sy Ta Yes Ta Yes Ta >0
643: .It \&.Tn Ta Yes Ta Yes Ta >0
644: .It \&.Ux Ta Yes Ta Yes Ta n
1.6 ! kristaps 645: .It \&.Dx Ta Yes Ta Yes Ta n
1.3 kristaps 646: .It \&.Bt Ta \&No Ta \&No Ta 0
647: .It \&.Hf Ta \&No Ta \&No Ta n
648: .It \&.Fr Ta \&No Ta \&No Ta n
649: .It \&.Ud Ta \&No Ta \&No Ta 0
650: .It \&.Lb Ta \&No Ta \&No Ta 1
651: .It \&.Ap Ta Yes Ta Yes Ta 0
652: .It \&.Lp Ta \&No Ta \&No Ta 0
653: .It \&.Lk Ta \&No Ta Yes Ta >0
654: .It \&.Mt Ta \&No Ta Yes Ta >0
1.6 ! kristaps 655: .It \&.Es Ta \&No Ta \&No Ta 0
! 656: .It \&.En Ta \&No Ta \&No Ta 0
1.1 kristaps 657: .El
1.6 ! kristaps 658: .Pp
! 659: The
! 660: .Sq \&Ot ,
! 661: .Sq \&Fr ,
! 662: .Sq \&Es
! 663: and
! 664: .Sq \&En ,
! 665: macros are obsolete.
1.2 kristaps 666: .\" SECTION
1.4 kristaps 667: .Sh COMPATIBILITY
668: The mdoc language was traditionally a
669: .Qq roff
670: macro package; most existing manuals were written with mdoc syntax
671: dictated by system-dependent roff installations. This section documents
672: compatibility with these systems.
673: .Pp
674: .Bl -dash -compact
675: .\" LIST-ITEM
676: .It
1.5 kristaps 677: .Sq \&Fo
678: and
679: .Sq \&St
680: historically weren't always callable. Both are now correctly callable.
681: .\" LIST-ITEM
682: .It
1.4 kristaps 683: .Sq \&It \-nested
684: is assumed for all lists: any list may be nested and
685: .Sq \-enum
686: lists will restart the sequence only for the sub-list.
687: .\" LIST-ITEM
688: .It
689: .Sq \&It \-column
690: syntax where column widths may be preceeded by other arguments (instead
691: of proceeded) is not supported.
692: .\" LIST-ITEM
693: .It
694: The
695: .Sq \&At
696: macro only accepts a single parameter.
697: .\" LIST-ITEM
698: .It
699: The system-name macros (
700: .Ns Sq \&At ,
701: .Sq \&Bsx ,
702: .Sq \&Bx ,
703: .Sq \&Fx ,
704: .Sq \&Nx ,
705: .Sq \&Ox ,
706: and
707: .Sq \&Ux )
708: are callable.
709: .\" LIST-ITEM
710: .It
711: Some manuals use
712: .Sq \&Li
713: incorrectly by following it with a reserved character and expecting the
714: delimiter to render. This is not supported.
715: .\" LIST-ITEM
716: .It
717: .Sq \&Cd
718: is callable.
719: .El
720: .\" SECTION
1.2 kristaps 721: .Sh SEE ALSO
722: .Xr mdoctree 1 ,
723: .Xr mdoclint 1 ,
724: .Xr mdocterm 1 ,
725: .Xr mdoc 3
726: .\" SECTION
727: .Sh AUTHORS
728: The
729: .Nm
730: utility was written by
1.6 ! kristaps 731: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
1.5 kristaps 732: .\" SECTION
733: .Sh CAVEATS
734: There are several ambiguous parts of mdoc.
735: .Pp
736: .Bl -dash -compact
737: .\" LIST-ITEM
738: .It
739: .Sq \&Fa
740: should be
741: .Sq \&Va
742: as function arguments are variables.
743: .\" LIST-ITEM
744: .It
745: .Sq \&Ft
746: should be
747: .Sq \&Vt
748: as function return types are still types. Furthermore, the
749: .Sq \&Ft
750: should be removed and
751: .Sq \&Fo ,
752: which ostensibly follows it, should follow the same convention as
753: .Sq \&Va .
754: .\" LIST-ITEM
755: .It
756: .Sq \&Va
757: should formalise that only one or two arguments are acceptable: a
758: variable name and optional, preceeding type.
759: .\" LIST-ITEM
760: .It
761: .Sq \&Fd
762: is ambiguous. It's commonly used to indicate an include file in the
763: synopsis section.
764: .Sq \&In
765: should be used, instead.
766: .\" LIST-ITEM
767: .It
768: Only the
769: .Sq \-literal
770: argument to
771: .Sq \&Bd
772: makes sense. The remaining ones should be removed.
773: .\" LIST-ITEM
774: .It
775: The
776: .Sq \&Xo
777: and
778: .Sq \&Xc
779: macros should be deprecated.
780: .\" LIST-ITEM
781: .It
782: The
783: .Sq \&Dt
784: macro lacks clarity. It should be absolutely clear which title will
785: render when formatting the manual page.
1.6 ! kristaps 786: .\" LIST-ITEM
! 787: .It
! 788: A
! 789: .Sq \&Lx
! 790: should be provided for Linux (\(`a la
! 791: .Sq \&Ox ,
! 792: .Sq \&Nx
! 793: etc.).
1.5 kristaps 794: .El
CVSweb