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