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