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