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