Annotation of mandoc/mdoc.7, Revision 1.8
1.8 ! kristaps 1: .\" $Id: mdoc.7,v 1.7 2009/03/19 11:49:00 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
1.8 ! kristaps 120: .It \\(r!
! 121: .Pq upside-down exclamation
! 122: .It \\(r?
! 123: .Pq upside-down question
1.1 kristaps 124: .El
125: .\" PARAGRAPH
126: .Pp
127: Enclosures:
128: .Bl -tag -width 12n -offset "XXXX" -compact
1.5 kristaps 129: .It \\(lh
130: .Pq left hand
131: .It \\(rh
132: .Pq right hand
133: .It \\(<<
1.7 kristaps 134: .Pq left guillemet
135: .It \\(Fc
136: .Pq right guillemet
137: .It \\(Fo
138: .Pq left guilsing
139: .It \\(fc
140: .Pq right guilsing
141: .It \\(fo
142: .Pq right guilsing
1.1 kristaps 143: .It \\(rC
144: .Pq right brace
145: .It \\(lC
146: .Pq left brace
147: .It \\(ra
148: .Pq right angle
149: .It \\(la
150: .Pq left angle
151: .It \\(rB
152: .Pq right bracket
153: .It \\(lB
154: .Pq left bracket
155: .It \\q
156: .Pq double-quote
157: .It \\(lq
158: .Pq left double-quote
159: .It \\(Lq
160: .Pq left double-quote, deprecated
161: .It \\(rq
162: .Pq right double-quote
163: .It \\(Rq
164: .Pq right double-quote, deprecated
165: .It \\(oq
166: .Pq left single-quote
167: .It \\(aq
168: .Pq right single-quote
1.8 ! kristaps 169: .It \\(Bq
! 170: .Pq right low double-quote
! 171: .It \\(bq
! 172: .Pq right low single-quote
1.1 kristaps 173: .El
174: .\" PARAGRAPH
175: .Pp
176: Indicatives:
177: .Bl -tag -width 12n -offset "XXXX" -compact
178: .It \\(<-
179: .Pq left arrow
180: .It \\(->
181: .Pq right arrow
182: .It \\(ua
183: .Pq up arrow
184: .It \\(da
185: .Pq down arrow
1.5 kristaps 186: .It \\(<>
187: .Pq left-right arrow
188: .It \\(lA
189: .Pq left double-arrow
190: .It \\(rA
191: .Pq right double-arrow
192: .It \\(uA
193: .Pq up double-arrow
194: .It \\(dA
195: .Pq down double-arrow
196: .It \\(hA
197: .Pq left-right double-arrow
1.1 kristaps 198: .El
199: .\" PARAGRAPH
200: .Pp
201: Mathematical:
202: .Bl -tag -width 12n -offset "XXXX" -compact
203: .It \\(Gt
204: .Pq greater-than, deprecated
205: .It \\(Lt
206: .Pq less-than, deprecated
207: .It \\(<=
208: .Pq less-than-equal
209: .It \\(Le
210: .Pq less-than-equal, deprecated
211: .It \\(>=
212: .Pq greater-than-equal
213: .It \\(Ge
214: .Pq greater-than-equal
215: .It \\(==
216: .Pq equal
217: .It \\(!=
218: .Pq not equal
219: .It \\(Ne
220: .Pq not equal, deprecated
221: .It \\(if
222: .Pq infinity
223: .It \\(If
224: .Pq infinity, deprecated
225: .It \\(na
226: .Pq NaN , an extension
227: .It \\(Na
228: .Pq NaN, deprecated
229: .It \\(+-
230: .Pq plus-minus
231: .It \\(Pm
232: .Pq plus-minus, deprecated
233: .It \\(**
234: .Pq asterisk
235: .El
236: .\" PARAGRAPH
237: .Pp
1.7 kristaps 238: Ligatures:
1.1 kristaps 239: .Bl -tag -width 12n -offset "XXXX" -compact
1.7 kristaps 240: .It \\(ss
241: .Pq German eszett
1.5 kristaps 242: .It \\(AE
243: .Pq upper-case AE
244: .It \\(ae
245: .Pq lower-case AE
246: .It \\(OE
247: .Pq upper-case OE
248: .It \\(oe
249: .Pq lower-case OE
1.7 kristaps 250: .It \\(ff
251: .Pq ff ligature
252: .It \\(fi
253: .Pq fi ligature
254: .It \\(fl
255: .Pq fl ligature
256: .It \\(Fi
257: .Pq ffi ligature
258: .It \\(Fl
259: .Pq ffl ligature
260: .El
261: .\" PARAGRAPH
262: .Pp
263: Diacritics and letters:
264: .Bl -tag -width 12n -offset "XXXX" -compact
265: .It \\(ga
266: .Pq grave accent
267: .It \\(aa
268: .Pq accute accent
1.8 ! kristaps 269: .It \\(a"
! 270: .Pq umlaut accent
1.7 kristaps 271: .It \\(ad
272: .Pq dieresis accent
273: .It \\(a~
274: .Pq tilde accent
275: .It \\(a^
276: .Pq circumflex accent
277: .It \\(ac
278: .Pq cedilla accent
279: .It \\(ad
280: .Pq dieresis accent
281: .It \\(ah
282: .Pq caron accent
283: .It \\(ao
284: .Pq ring accent
285: .It \\(ho
286: .Pq hook accent
287: .It \\(ab
288: .Pq breve accent
289: .It \\(a-
290: .Pq macron accent
291: .It \\(-D
292: .Pq upper-case eth
293: .It \\(Sd
294: .Pq lower-case eth
295: .It \\(TP
296: .Pq upper-case thorn
297: .It \\(Tp
298: .Pq lower-case thorn
1.5 kristaps 299: .It \\('A
300: .Pq upper-case acute A
301: .It \\('E
302: .Pq upper-case acute E
303: .It \\('I
304: .Pq upper-case acute I
305: .It \\('O
306: .Pq upper-case acute O
307: .It \\('U
308: .Pq upper-case acute U
309: .It \\('a
310: .Pq lower-case acute a
311: .It \\('e
312: .Pq lower-case acute e
313: .It \\('i
314: .Pq lower-case acute i
315: .It \\('o
316: .Pq lower-case acute o
317: .It \\('u
318: .Pq lower-case acute u
319: .It \\(`A
320: .Pq upper-case grave A
321: .It \\(`E
322: .Pq upper-case grave E
323: .It \\(`I
324: .Pq upper-case grave I
325: .It \\(`O
326: .Pq upper-case grave O
327: .It \\(`U
328: .Pq upper-case grave U
329: .It \\(`a
330: .Pq lower-case grave a
331: .It \\(`e
332: .Pq lower-case grave e
333: .It \\(`i
334: .Pq lower-case grave i
335: .It \\(`o
336: .Pq lower-case grave o
337: .It \\(`u
338: .Pq lower-case grave u
339: .It \\(~A
340: .Pq upper-case tilde A
341: .It \\(~N
342: .Pq upper-case tilde N
343: .It \\(~O
344: .Pq upper-case tilde O
345: .It \\(~a
346: .Pq lower-case tilde a
347: .It \\(~n
348: .Pq lower-case tilde n
349: .It \\(~o
350: .Pq lower-case tilde o
351: .It \\(:A
352: .Pq upper-case dieresis A
353: .It \\(:E
354: .Pq upper-case dieresis E
355: .It \\(:I
356: .Pq upper-case dieresis I
357: .It \\(:O
358: .Pq upper-case dieresis O
359: .It \\(:U
360: .Pq upper-case dieresis U
361: .It \\(:a
362: .Pq lower-case dieresis a
363: .It \\(:e
364: .Pq lower-case dieresis e
365: .It \\(:i
366: .Pq lower-case dieresis i
367: .It \\(:o
368: .Pq lower-case dieresis o
369: .It \\(:u
370: .Pq lower-case dieresis u
371: .It \\(:y
372: .Pq lower-case dieresis y
1.7 kristaps 373: .It \\(^A
374: .Pq upper-case circumflex A
375: .It \\(^E
376: .Pq upper-case circumflex E
377: .It \\(^I
378: .Pq upper-case circumflex I
379: .It \\(^O
380: .Pq upper-case circumflex O
381: .It \\(^U
382: .Pq upper-case circumflex U
383: .It \\(^a
384: .Pq lower-case circumflex a
385: .It \\(^e
386: .Pq lower-case circumflex e
387: .It \\(^i
388: .Pq lower-case circumflex i
389: .It \\(^o
390: .Pq lower-case circumflex o
391: .It \\(^u
392: .Pq lower-case circumflex u
393: .It \\(,C
394: .Pq upper-case cedilla C
395: .It \\(,c
396: .Pq lower-case cedilla c
397: .It \\(/L
398: .Pq upper-case stroke L
399: .It \\(/l
400: .Pq lower-case stroke l
401: .It \\(/O
402: .Pq upper-case stroke O
403: .It \\(/o
404: .Pq lower-case stroke o
405: .It \\(oA
406: .Pq upper-case ring A
407: .It \\(oa
408: .Pq lower-case ring a
409: .El
410: .\" PARAGRAPH
411: .Pp
412: Monetary:
413: .Bl -tag -width 12n -offset "XXXX" -compact
414: .It \\(Cs
415: .Pq Scandinavian
416: .It \\(Do
417: .Pq dollar
418: .It \\(Po
419: .Pq pound
420: .It \\(Ye
421: .Pq yen
422: .It \\(Fn
423: .Pq florin
424: .It \\(ct
425: .Pq cent
1.1 kristaps 426: .El
427: .\" PARAGRAPH
428: .Pp
429: Special symbols:
430: .Bl -tag -width 12n -offset "XXXX" -compact
431: .It \\(bu
432: .Pq bullet
1.8 ! kristaps 433: .It \\(ci
! 434: .Pq circle
1.1 kristaps 435: .It \\(ba
436: .Pq bar
1.8 ! kristaps 437: .It \\(bb
! 438: .Pq broken bar
1.1 kristaps 439: .It \\(Ba
440: .Pq bar, deprecated
441: .It \\(co
442: .Pq copyright
1.5 kristaps 443: .It \\(rg
444: .Pq registered
445: .It \\(tm
446: .Pq trademarked
1.1 kristaps 447: .It \\&
448: .Pq non-breaking space
449: .It \\e
450: .Pq escape
451: .It \\(Am
452: .Pq ampersand, deprecated
453: .El
454: .\" SECTION
1.2 kristaps 455: .Sh ONTOLOGY
1.1 kristaps 456: Macros are classified in an ontology described by scope rules.
1.4 kristaps 457: .\" SUB-SECTION
458: .Ss Scope
1.2 kristaps 459: .Bl -inset
1.1 kristaps 460: .\" LIST-ITEM
461: .It Em Block
1.2 kristaps 462: macros enclose other block macros, in-line macros or text, and
1.4 kristaps 463: may span multiple lines.
1.2 kristaps 464: .Bl -inset -offset XXXX
1.1 kristaps 465: .\" LIST-ITEM
466: .It Em Full-block
1.5 kristaps 467: macros always span multiple lines. They consist of zero or
1.2 kristaps 468: more
1.1 kristaps 469: .Qq heads ,
1.5 kristaps 470: subsequent macros or text on the same line following invocation; an
471: optional
1.1 kristaps 472: .Qq body ,
473: which spans subsequent lines of text or macros; and an optional
474: .Qq tail ,
475: macros or text on the same line following closure.
476: .\" LIST-ITEM
477: .It Em Partial-block
1.5 kristaps 478: macros may span multiple lines. They consists of a optional
1.1 kristaps 479: .Qq head ,
480: text immediately following invocation; always a
481: .Qq body ,
482: text or macros following the head on the same and subsequent lines; and
483: optionally a
484: .Qq tail ,
485: text immediately following closure.
486: .\" LIST-ITEM
487: .It Em In-line
1.4 kristaps 488: macros may only enclose text and span at most a single line.
489: .El
490: .El
491: .\" SUB-SECTION
492: .Ss Closure
493: Closure of a macro's scope depends first on its classification, then
494: on whether it's parsable. In this table,
495: .Sq BFE
496: refers to block full-explicit and so on.
497: .\" PARAGRAPH
498: .Pp
499: .Bl -tag -width 12n -offset XXXX -compact
500: .It BPE , BFE
501: corresponding explicit closure macro
502: .It BFI
503: end-of-file or a corresponding implicit closure macro
504: .It BPI
505: end-of-line (body may be closed by >0 space-separated
506: .Sx Reserved Characters ,
507: although block scope will still be open)
508: .It INL
509: end-of-line
1.1 kristaps 510: .El
1.4 kristaps 511: .\" PARAGRAPH
512: .Pp
513: If a macro (block or in-line) is parsable, it may also be closed out by
514: one of the following scenarios (unless specifically noted otherwise):
515: .\" PARAGRAPH
516: .Pp
517: .Bl -dash -offset XXXX -compact
518: .It
519: a sequence of >0 space-separated
520: .Sx Reserved Characters ,
521: .It
522: another macro,
523: .It
524: end-of-line, or
525: .It
526: completion of a set number of arguments.
527: .El
528: .\" PARAGRAPH
529: .Pp
530: If >0 space-separated
531: .Sx Reserved Characters
532: are followed by non-reserved characters, the behaviour differs per
533: macro. In general, scope of the macro is closed and re-opened:
534: subsequent tokens are interpreted as if the scope had just been opened.
535: In other circumstances, scope is simply closed out.
1.1 kristaps 536: .\" SECTION
1.2 kristaps 537: .Sh SYNTAX
1.3 kristaps 538: Macros are generally two and at times three characters in length. The
539: syntax of macro invocation depends on its classification.
1.2 kristaps 540: .Qq \-arg
541: refers to the macro arguments (which may contain zero or more values).
542: In these illustrations,
543: .Sq \&.Yo
544: opens the scope of a macro, and if specified,
545: .Sq \&.Yc
546: closes it out (closure may be implicit at end-of-line or end-of-file).
1.4 kristaps 547: .\" PARAGRAPH
1.2 kristaps 548: .Pp
1.4 kristaps 549: Block full-explicit (may contain head, body, tail).
1.2 kristaps 550: .Bd -literal -offset XXXX
1.4 kristaps 551: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
552: \(lBbody...\(rB
553: \&.Yc \(lBtail...\(rB
1.2 kristaps 554: .Ed
1.4 kristaps 555: .\" PARAGRAPH
1.2 kristaps 556: .Pp
1.4 kristaps 557: Block full-implicit (may contain zero or more heads, body, no tail).
1.2 kristaps 558: .Bd -literal -offset XXXX
1.4 kristaps 559: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
560: \(lBbody...\(rB
1.2 kristaps 561: \&.Yc
562: .Ed
1.4 kristaps 563: .\" PARAGRAPH
1.2 kristaps 564: .Pp
1.4 kristaps 565: Block partial-explicit (may contain head, multi-line body, tail).
1.2 kristaps 566: .Bd -literal -offset XXXX
567: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
1.4 kristaps 568: \(lBbody...\(rB
569: \&.Yc \(lBtail...\(rB
1.2 kristaps 570:
571: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
1.4 kristaps 572: \(lBbody...\(rB \&Yc \(lBtail...\(rB
1.2 kristaps 573: .Ed
1.4 kristaps 574: .\" PARAGRAPH
1.2 kristaps 575: .Pp
1.4 kristaps 576: Block partial-implicit (no head, body, no tail). Note that the body
577: section may be followed by zero or more
578: .Sx Reserved Words .
579: These are in the block scope, but not in the body scope.
1.2 kristaps 580: .Bd -literal -offset XXXX
1.4 kristaps 581: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
1.2 kristaps 582: .Ed
1.4 kristaps 583: .\" PARAGRAPH
1.2 kristaps 584: .Pp
1.4 kristaps 585: In-lines have \(>=0 scoped arguments.
1.2 kristaps 586: .Bd -literal -offset XXX
1.4 kristaps 587: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
1.2 kristaps 588:
589: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
590: .Ed
591: .\"
1.1 kristaps 592: .Sh MACROS
593: This section contains a complete list of all
594: .Nm
1.2 kristaps 595: macros, arranged ontologically. A
1.1 kristaps 596: .Qq callable
597: macro is may be invoked subsequent to the initial macro-line macro. A
598: .Qq parsable
1.2 kristaps 599: macro may be followed by further (ostensibly callable) macros.
1.1 kristaps 600: .\" SUB-SECTION
601: .Ss Block full-implicit
602: The head of these macros follows invocation; the body is the content of
603: subsequent lines prior to closure. None of these macros have tails;
604: some
605: .Po
606: .Sq \&It \-bullet ,
607: .Sq \-hyphen ,
608: .Sq \-dash ,
1.2 kristaps 609: .Sq \-enum ,
610: .Sq \-item
1.1 kristaps 611: .Pc
612: don't have heads.
613: .Pp
614: .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
615: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
616: .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
617: .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
618: .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
619: .El
620: .\" SUB-SECTION
621: .Ss Block full-explicit
622: None of these macros are callable or parsed. The last column indicates
623: the explicit scope rules. All contains bodies, some may contain heads
624: .Pq So \&Bf Sc .
625: .Pp
626: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
627: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
628: .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
629: .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
630: .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
631: .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
632: .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
633: .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
1.2 kristaps 634: .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
635: .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
1.1 kristaps 636: .El
637: .\" SUB-SECTION
638: .Ss Block partial-implicit
639: All of these are callable and parsed for further macros. Their scopes
640: close at the invocation's end-of-line.
641: .Pp
642: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
643: .It Em Macro Ta Em Callable Ta Em Parsable
644: .It \&.Aq Ta Yes Ta Yes
645: .It \&.Op Ta Yes Ta Yes
646: .It \&.Bq Ta Yes Ta Yes
647: .It \&.Dq Ta Yes Ta Yes
648: .It \&.Pq Ta Yes Ta Yes
649: .It \&.Qq Ta Yes Ta Yes
650: .It \&.Sq Ta Yes Ta Yes
651: .It \&.Brq Ta Yes Ta Yes
1.2 kristaps 652: .It \&.D1 Ta \&No Ta \&Yes
653: .It \&.Dl Ta \&No Ta Yes
654: .It \&.Ql Ta Yes Ta Yes
1.1 kristaps 655: .El
656: .\" SUB-SECTION
657: .Ss Block partial-explicit
658: Each of these contains at least a body and, in limited circumstances, a
659: head
660: .Pq So \&Fo Sc , So \&Eo Sc
661: and/or tail
662: .Pq So \&Ec Sc .
663: .Pp
664: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
665: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
666: .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
667: .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
668: .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
669: .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
670: .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
671: .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
672: .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
673: .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
674: .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
675: .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
676: .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
677: .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
678: .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
679: .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
680: .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
681: .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
682: .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
683: .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
684: .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
685: .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
686: .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
687: .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
1.2 kristaps 688: .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
689: .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
1.1 kristaps 690: .El
691: .\" SUB-SECTION
1.2 kristaps 692: .Ss In-line
1.3 kristaps 693: In-line macros have only text children. If a number (or inequality) of
694: arguments is
695: .Pq n ,
696: then the macro accepts an arbitrary number of arguments.
1.2 kristaps 697: .Pp
698: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
699: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
1.3 kristaps 700: .It \&.Dd Ta \&No Ta \&No Ta >0
701: .It \&.Dt Ta \&No Ta \&No Ta n
702: .It \&.Os Ta \&No Ta \&No Ta n
1.2 kristaps 703: .It \&.Pp Ta \&No Ta \&No Ta 0
1.3 kristaps 704: .It \&.Ad Ta Yes Ta Yes Ta n
705: .It \&.An Ta \&No Ta Yes Ta n
706: .It \&.Ar Ta Yes Ta Yes Ta n
707: .It \&.Cd Ta Yes Ta \&No Ta >0
708: .It \&.Cm Ta Yes Ta Yes Ta n
709: .It \&.Dv Ta Yes Ta Yes Ta >0
710: .It \&.Er Ta Yes Ta Yes Ta >0
711: .It \&.Ev Ta Yes Ta Yes Ta >0
712: .It \&.Ex Ta \&No Ta \&No Ta 0
713: .It \&.Fa Ta Yes Ta Yes Ta >0
714: .It \&.Fd Ta \&No Ta \&No Ta >0
715: .It \&.Fl Ta Yes Ta Yes Ta n
716: .It \&.Fn Ta Yes Ta Yes Ta >0
717: .It \&.Ft Ta \&No Ta Yes Ta n
718: .It \&.Ic Ta Yes Ta Yes Ta >0
719: .It \&.In Ta \&No Ta \&No Ta n
720: .It \&.Li Ta Yes Ta Yes Ta >0
721: .It \&.Nd Ta \&No Ta \&No Ta n
722: .It \&.Nm Ta Yes Ta Yes Ta n
723: .It \&.Ot Ta \&No Ta \&No Ta n
724: .It \&.Pa Ta Yes Ta Yes Ta n
725: .It \&.Rv Ta \&No Ta \&No Ta 0
726: .It \&.St Ta \&No Ta Yes Ta 1
727: .It \&.Va Ta Yes Ta Yes Ta >0
728: .It \&.Vt Ta Yes Ta Yes Ta >0
729: .It \&.Xr Ta Yes Ta Yes Ta >0, <3
730: .It \&.%A Ta \&No Ta \&No Ta >0
731: .It \&.%B Ta \&No Ta \&No Ta >0
732: .It \&.%C Ta \&No Ta \&No Ta >0
733: .It \&.%D Ta \&No Ta \&No Ta >0
734: .It \&.%I Ta \&No Ta \&No Ta >0
735: .It \&.%J Ta \&No Ta \&No Ta >0
736: .It \&.%N Ta \&No Ta \&No Ta >0
737: .It \&.%O Ta \&No Ta \&No Ta >0
738: .It \&.%P Ta \&No Ta \&No Ta >0
739: .It \&.%R Ta \&No Ta \&No Ta >0
740: .It \&.%T Ta \&No Ta \&No Ta >0
741: .It \&.%V Ta \&No Ta \&No Ta >0
742: .It \&.At Ta Yes Ta Yes Ta 1
743: .It \&.Bsx Ta Yes Ta Yes Ta n
744: .It \&.Bx Ta Yes Ta Yes Ta n
745: .It \&.Db Ta \&No Ta \&No Ta 1
746: .It \&.Em Ta Yes Ta Yes Ta >0
747: .It \&.Fx Ta Yes Ta Yes Ta n
748: .It \&.Ms Ta \&No Ta Yes Ta >0
749: .It \&.No Ta Yes Ta Yes Ta 0
750: .It \&.Ns Ta Yes Ta Yes Ta 0
751: .It \&.Nx Ta Yes Ta Yes Ta n
752: .It \&.Ox Ta Yes Ta Yes Ta n
753: .It \&.Pf Ta \&No Ta Yes Ta 1
754: .It \&.Sm Ta \&No Ta \&No Ta 1
755: .It \&.Sx Ta Yes Ta Yes Ta >0
756: .It \&.Sy Ta Yes Ta Yes Ta >0
757: .It \&.Tn Ta Yes Ta Yes Ta >0
758: .It \&.Ux Ta Yes Ta Yes Ta n
1.6 kristaps 759: .It \&.Dx Ta Yes Ta Yes Ta n
1.3 kristaps 760: .It \&.Bt Ta \&No Ta \&No Ta 0
761: .It \&.Hf Ta \&No Ta \&No Ta n
762: .It \&.Fr Ta \&No Ta \&No Ta n
763: .It \&.Ud Ta \&No Ta \&No Ta 0
764: .It \&.Lb Ta \&No Ta \&No Ta 1
765: .It \&.Ap Ta Yes Ta Yes Ta 0
766: .It \&.Lp Ta \&No Ta \&No Ta 0
767: .It \&.Lk Ta \&No Ta Yes Ta >0
768: .It \&.Mt Ta \&No Ta Yes Ta >0
1.6 kristaps 769: .It \&.Es Ta \&No Ta \&No Ta 0
770: .It \&.En Ta \&No Ta \&No Ta 0
1.1 kristaps 771: .El
1.6 kristaps 772: .Pp
773: The
774: .Sq \&Ot ,
775: .Sq \&Fr ,
776: .Sq \&Es
777: and
778: .Sq \&En ,
779: macros are obsolete.
1.2 kristaps 780: .\" SECTION
1.4 kristaps 781: .Sh COMPATIBILITY
782: The mdoc language was traditionally a
783: .Qq roff
784: macro package; most existing manuals were written with mdoc syntax
785: dictated by system-dependent roff installations. This section documents
786: compatibility with these systems.
787: .Pp
788: .Bl -dash -compact
789: .\" LIST-ITEM
790: .It
1.5 kristaps 791: .Sq \&Fo
792: and
793: .Sq \&St
794: historically weren't always callable. Both are now correctly callable.
795: .\" LIST-ITEM
796: .It
1.4 kristaps 797: .Sq \&It \-nested
798: is assumed for all lists: any list may be nested and
799: .Sq \-enum
800: lists will restart the sequence only for the sub-list.
801: .\" LIST-ITEM
802: .It
803: .Sq \&It \-column
804: syntax where column widths may be preceeded by other arguments (instead
805: of proceeded) is not supported.
806: .\" LIST-ITEM
807: .It
808: The
809: .Sq \&At
810: macro only accepts a single parameter.
811: .\" LIST-ITEM
812: .It
813: The system-name macros (
814: .Ns Sq \&At ,
815: .Sq \&Bsx ,
816: .Sq \&Bx ,
817: .Sq \&Fx ,
818: .Sq \&Nx ,
819: .Sq \&Ox ,
820: and
821: .Sq \&Ux )
822: are callable.
823: .\" LIST-ITEM
824: .It
825: Some manuals use
826: .Sq \&Li
827: incorrectly by following it with a reserved character and expecting the
828: delimiter to render. This is not supported.
829: .\" LIST-ITEM
830: .It
831: .Sq \&Cd
832: is callable.
833: .El
834: .\" SECTION
1.2 kristaps 835: .Sh SEE ALSO
836: .Xr mdoctree 1 ,
837: .Xr mdoclint 1 ,
838: .Xr mdocterm 1 ,
839: .Xr mdoc 3
840: .\" SECTION
841: .Sh AUTHORS
842: The
843: .Nm
844: utility was written by
1.6 kristaps 845: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
1.5 kristaps 846: .\" SECTION
847: .Sh CAVEATS
848: There are several ambiguous parts of mdoc.
849: .Pp
850: .Bl -dash -compact
851: .\" LIST-ITEM
852: .It
853: .Sq \&Fa
854: should be
855: .Sq \&Va
856: as function arguments are variables.
857: .\" LIST-ITEM
858: .It
859: .Sq \&Ft
860: should be
861: .Sq \&Vt
862: as function return types are still types. Furthermore, the
863: .Sq \&Ft
864: should be removed and
865: .Sq \&Fo ,
866: which ostensibly follows it, should follow the same convention as
867: .Sq \&Va .
868: .\" LIST-ITEM
869: .It
870: .Sq \&Va
871: should formalise that only one or two arguments are acceptable: a
872: variable name and optional, preceeding type.
873: .\" LIST-ITEM
874: .It
875: .Sq \&Fd
876: is ambiguous. It's commonly used to indicate an include file in the
877: synopsis section.
878: .Sq \&In
879: should be used, instead.
880: .\" LIST-ITEM
881: .It
882: Only the
883: .Sq \-literal
884: argument to
885: .Sq \&Bd
886: makes sense. The remaining ones should be removed.
887: .\" LIST-ITEM
888: .It
889: The
890: .Sq \&Xo
891: and
892: .Sq \&Xc
893: macros should be deprecated.
894: .\" LIST-ITEM
895: .It
896: The
897: .Sq \&Dt
898: macro lacks clarity. It should be absolutely clear which title will
899: render when formatting the manual page.
1.6 kristaps 900: .\" LIST-ITEM
901: .It
902: A
903: .Sq \&Lx
904: should be provided for Linux (\(`a la
905: .Sq \&Ox ,
906: .Sq \&Nx
907: etc.).
1.5 kristaps 908: .El
CVSweb