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