Annotation of src/usr.bin/mandoc/mdoc.7, Revision 1.7
1.7 ! schwarze 1: .\" $Id: mdoc.7,v 1.6 2009/06/24 00:16:52 schwarze Exp $
1.1 kristaps 2: .\"
1.2 schwarze 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.2 schwarze 6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
1.1 kristaps 8: .\"
1.2 schwarze 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 kristaps 16: .\"
1.7 ! schwarze 17: .Dd $Mdocdate: June 24 2009 $
1.2 schwarze 18: .Dt MDOC 7
1.1 kristaps 19: .Os
20: .\" SECTION
21: .Sh NAME
22: .Nm mdoc
23: .Nd mdoc language reference
24: .\" SECTION
25: .Sh DESCRIPTION
26: The
27: .Nm mdoc
28: language is used to format
29: .Bx
30: .Ux
1.7 ! schwarze 31: manuals. In this reference document, we describe the syntax and
! 32: structure of the
1.1 kristaps 33: .Nm
1.3 schwarze 34: language. Our reference implementation is
35: .Xr mandoc 1 .
36: The
37: .Sx COMPATIBILITY
38: section describes compatibility with
39: .Xr groff 1 .
1.1 kristaps 40: .\" PARAGRAPH
41: .Pp
42: An
43: .Nm
44: document follows simple rules: lines beginning with the control
45: character
46: .Sq \.
47: are parsed for macros. Other lines are interpreted within the scope of
48: prior macros:
49: .Bd -literal -offset XXX
50: \&.Sh Macro lines change control state.
51: Other lines are interpreted within the current state.
52: .Ed
53: .\" SECTION
54: .Sh INPUT ENCODING
55: .Nm
56: documents may contain only graphable 7-bit ASCII characters, the space
57: character
58: .Sq \ ,
59: and, in certain circumstances, the tab character
60: .Sq \et .
61: All manuals must have
62: .Sq \en
63: line termination.
64: .Pp
65: The only time a blank line is acceptable is within
66: the context of
67: .Sq \&.Bd \-literal
68: or
69: .Sq \&.Bd \-unfilled .
70: .Pp
71: Tab characters
72: .Pq \et
73: are only acceptable when delimiting
74: .Sq \&.Bl \-column
75: and in
76: .Sq \&.Bd \-literal
77: or
78: .Sq \&.Bd \-unfilled
79: contexts.
1.4 schwarze 80: .\" SUB-SECTION
81: .Ss Comments
82: Anything following a
83: .Sq \e"
84: delimiter is considered a comment (unless the
85: .Sq \e
86: itself has been escaped) and is ignored to the end of line.
87: Furthermore, a macro line with only a control character
88: .Sq \. ,
89: optionally followed by whitespace, is ignored.
1.1 kristaps 90: .\" SUB-SECTION
91: .Ss Reserved Characters
92: Within a macro line, the following characters are reserved:
1.5 schwarze 93: .Bl -tag -width Ds -offset XXXX -compact
1.1 kristaps 94: .It \&.
95: .Pq period
96: .It \&,
97: .Pq comma
98: .It \&:
99: .Pq colon
100: .It \&;
101: .Pq semicolon
102: .It \&(
103: .Pq left-parenthesis
104: .It \&)
105: .Pq right-parenthesis
106: .It \&[
107: .Pq left-bracket
108: .It \&]
109: .Pq right-bracket
110: .It \&?
111: .Pq question
112: .It \&!
113: .Pq exclamation
1.3 schwarze 114: .It \&|
115: .Pq vertical bar
1.1 kristaps 116: .El
117: .\" PARAGRAPH
118: .Pp
119: Use of reserved characters is described in
120: .Sx Closure .
121: For general non-reserved use, characters must either be escaped with a
122: non-breaking space
123: .Pq Sq \e&
124: or, if applicable, an appropriate escape-sequence used.
125: .\" SUB-SECTION
126: .Ss Special Characters
127: Special character sequences begin with the escape character
128: .Sq \e
129: followed by either an open-parenthesis
130: .Sq \&(
131: for two-character sequences; an open-bracket
132: .Sq \&[
133: for n-character sequences (terminated at a close-bracket
134: .Sq \&] ) ;
135: or a single one-character sequence.
136: .Pp
137: Characters may alternatively be escaped by a slash-asterisk,
138: .Sq \e* ,
1.7 ! schwarze 139: with the same combinations as described above.
! 140: .Pp
! 141: Terms may also be text-decorated using the
! 142: .Sq \ef
! 143: escape followed by a text-decoration letter: B (bold), I, (italic), or P
! 144: and R (Roman, or reset). This form is not recommended.
! 145: .\" SUB-SECTION
! 146: .Ss Whitespace
! 147: Unless in literal mode or specifically escaped, consecutive blocks of
! 148: whitespace are pruned from input. These are later re-added, if
! 149: applicable, by a front-end utility such as
! 150: .Xr mandoc 1 .
1.1 kristaps 151: .\" SECTION
152: .Sh STRUCTURE
1.6 schwarze 153: Each
154: .Nm
155: document must begin with the document prologue, containing, in order,
156: .Sq \&.Dd ,
157: .Sq \&.Dt ,
158: and
159: .Sq \&.Os .
160: Following these, the document body must begin with the NAME section
161: containing at least one
162: .Sq \&.Nm
163: followed by a
164: .Sq \&.Nd
165: macro.
166: .Pp
1.7 ! schwarze 167: At least one free-form or macro line must follow this prologue.
! 168: .\"
! 169: .Ss Classification
! 170: Macros are classified by their scope rules. Some macros are allowed to
! 171: deviate from their classifications to preserve backward-compatibility
! 172: with old macro combinations still found in the manual corpus. These are
! 173: specifically noted on a per-macro basis.
1.1 kristaps 174: .\" SUB-SECTION
175: .Ss Scope
176: .Bl -inset
177: .\" LIST-ITEM
178: .It Em Block
179: macros enclose other block macros, in-line macros or text, and
180: may span multiple lines.
181: .Bl -inset -offset XXXX
182: .\" LIST-ITEM
183: .It Em Full-block
184: macros always span multiple lines. They consist of zero or
185: more
186: .Qq heads ,
187: subsequent macros or text on the same line following invocation; an
188: optional
189: .Qq body ,
190: which spans subsequent lines of text or macros; and an optional
191: .Qq tail ,
192: macros or text on the same line following closure.
193: .\" LIST-ITEM
194: .It Em Partial-block
195: macros may span multiple lines. They consists of a optional
196: .Qq head ,
197: text immediately following invocation; always a
198: .Qq body ,
199: text or macros following the head on the same and subsequent lines; and
200: optionally a
201: .Qq tail ,
202: text immediately following closure.
203: .\" LIST-ITEM
204: .It Em In-line
205: macros may only enclose text and span at most a single line.
206: .El
207: .El
208: .\" SUB-SECTION
209: .Ss Closure
210: Closure of a macro's scope depends first on its classification, then
211: on whether it's parsable. In this table,
212: .Sq BFE
213: refers to block full-explicit and so on.
214: .\" PARAGRAPH
215: .Pp
216: .Bl -tag -width 12n -offset XXXX -compact
217: .It BPE , BFE
218: corresponding explicit closure macro
219: .It BFI
220: end-of-file or a corresponding implicit closure macro
221: .It BPI
222: end-of-line (body may be closed by >0 space-separated
223: .Sx Reserved Characters ,
224: although block scope will still be open)
225: .It INL
226: end-of-line
227: .El
228: .\" PARAGRAPH
229: .Pp
230: If a macro (block or in-line) is parsable, it may also be closed out by
231: one of the following scenarios (unless specifically noted otherwise):
232: .\" PARAGRAPH
233: .Pp
234: .Bl -dash -offset XXXX -compact
235: .It
236: a sequence of >0 space-separated
237: .Sx Reserved Characters ,
238: .It
239: another macro,
240: .It
241: end-of-line, or
242: .It
243: completion of a set number of arguments.
244: .El
245: .\" PARAGRAPH
246: .Pp
247: If >0 space-separated
248: .Sx Reserved Characters
249: are followed by non-reserved characters, the behaviour differs per
250: macro. In general, scope of the macro is closed and re-opened:
251: subsequent tokens are interpreted as if the scope had just been opened.
252: In other circumstances, scope is simply closed out.
253: .\" SECTION
254: .Sh SYNTAX
255: Macros are two or three characters in length. The syntax of macro
256: invocation depends on its classification.
257: .Qq \-arg
258: refers to the macro arguments (which may contain zero or more values).
259: In these illustrations,
260: .Sq \&.Yo
261: opens the scope of a macro, and if specified,
262: .Sq \&.Yc
263: closes it out (closure may be implicit at end-of-line or end-of-file).
264: .\" PARAGRAPH
265: .Pp
266: Block full-explicit (may contain head, body, tail).
267: .Bd -literal -offset XXXX
268: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
269: \(lBbody...\(rB
270: \&.Yc \(lBtail...\(rB
271: .Ed
272: .\" PARAGRAPH
273: .Pp
274: Block full-implicit (may contain zero or more heads, body, no tail).
275: .Bd -literal -offset XXXX
276: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
277: \(lBbody...\(rB
278: \&.Yc
279: .Ed
280: .\" PARAGRAPH
281: .Pp
282: Block partial-explicit (may contain head, multi-line body, tail).
283: .Bd -literal -offset XXXX
284: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
285: \(lBbody...\(rB
286: \&.Yc \(lBtail...\(rB
287:
288: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
289: \(lBbody...\(rB \&Yc \(lBtail...\(rB
290: .Ed
291: .\" PARAGRAPH
292: .Pp
293: Block partial-implicit (no head, body, no tail). Note that the body
294: section may be followed by zero or more
295: .Sx Reserved Words .
296: These are in the block scope, but not in the body scope.
297: .Bd -literal -offset XXXX
298: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
299: .Ed
300: .\" PARAGRAPH
301: .Pp
302: In-lines have \(>=0 scoped arguments.
303: .Bd -literal -offset XXX
304: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
305:
306: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
307: .Ed
1.6 schwarze 308: .\" SECTION
1.1 kristaps 309: .Sh MACROS
310: This section contains a complete list of all
311: .Nm
1.7 ! schwarze 312: macros, arranged by classification. A
1.1 kristaps 313: .Qq callable
314: macro is invoked subsequent to the initial macro-line macro. A
315: .Qq parsable
316: macro may be followed by further (ostensibly callable) macros.
317: .\" SUB-SECTION
318: .Ss Block full-implicit
319: The head of these macros follows invocation; the body is the content of
320: subsequent lines prior to closure. None of these macros have tails;
321: some
322: .Po
323: .Sq \&.It \-bullet ,
324: .Sq \-hyphen ,
325: .Sq \-dash ,
326: .Sq \-enum ,
327: .Sq \-item
328: .Pc
329: don't have heads.
330: .Pp
1.5 schwarze 331: .Bl -column -compact -offset XXXX "MacroX" "CallableX" "ParsableX" "Closing"
1.1 kristaps 332: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
333: .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
334: .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
335: .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
336: .El
337: .\" SUB-SECTION
338: .Ss Block full-explicit
339: None of these macros are callable or parsed. The last column indicates
340: the explicit scope rules. All contains bodies, some may contain heads
341: .Pq So \&Bf Sc .
342: .Pp
1.5 schwarze 343: .Bl -column -compact -offset XXXX "MacroX" "CallableX" "ParsableX" "closed by XXX"
1.1 kristaps 344: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
345: .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
346: .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
347: .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
348: .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
349: .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
350: .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
351: .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
352: .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
353: .El
354: .\" SUB-SECTION
355: .Ss Block partial-implicit
356: All of these are callable and parsed for further macros. Their scopes
357: close at the invocation's end-of-line.
358: .Pp
359: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
360: .It Em Macro Ta Em Callable Ta Em Parsable
361: .It \&.Aq Ta Yes Ta Yes
362: .It \&.Op Ta Yes Ta Yes
363: .It \&.Bq Ta Yes Ta Yes
364: .It \&.Dq Ta Yes Ta Yes
365: .It \&.Pq Ta Yes Ta Yes
366: .It \&.Qq Ta Yes Ta Yes
367: .It \&.Sq Ta Yes Ta Yes
368: .It \&.Brq Ta Yes Ta Yes
369: .It \&.D1 Ta \&No Ta \&Yes
370: .It \&.Dl Ta \&No Ta Yes
371: .It \&.Ql Ta Yes Ta Yes
372: .El
373: .\" PARAGRAPH
374: .Pp
375: The
376: .Sq \&.Op
377: may be broken by
378: .Sq \&.Oc
379: as in the following example:
380: .Bd -literal -offset XXXX
381: \&.Oo
382: \&.Op Fl a Oc
383: .Ed
384: .Pp
385: In the above example, the scope of
386: .Sq \&.Op
387: is technically broken by
388: .Sq \&.Oc ,
389: however, due to the overwhelming existence of this sequence, it's
390: allowed.
391: .\" SUB-SECTION
392: .Ss Block partial-explicit
393: Each of these contains at least a body and, in limited circumstances, a
394: head
395: .Pq So \&.Fo Sc , So \&.Eo Sc
396: and/or tail
397: .Pq So \&.Ec Sc .
398: .Pp
399: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
400: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
401: .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
402: .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
403: .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
404: .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
405: .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
406: .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
407: .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
408: .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
409: .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
410: .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
411: .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
412: .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
413: .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
414: .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
415: .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
416: .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
417: .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
418: .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
419: .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
420: .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
421: .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
422: .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
423: .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
424: .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
425: .El
426: .\" SUB-SECTION
427: .Ss In-line
428: In-line macros have only text children. If a number (or inequality) of
429: arguments is
430: .Pq n ,
431: then the macro accepts an arbitrary number of arguments.
432: .Pp
433: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
434: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
435: .It \&.Dd Ta \&No Ta \&No Ta >0
436: .It \&.Dt Ta \&No Ta \&No Ta n
437: .It \&.Os Ta \&No Ta \&No Ta n
438: .It \&.Pp Ta \&No Ta \&No Ta 0
439: .It \&.Ad Ta Yes Ta Yes Ta n
1.3 schwarze 440: .It \&.An Ta Yes Ta Yes Ta n
1.1 kristaps 441: .It \&.Ar Ta Yes Ta Yes Ta n
442: .It \&.Cd Ta Yes Ta \&No Ta >0
443: .It \&.Cm Ta Yes Ta Yes Ta n
444: .It \&.Dv Ta Yes Ta Yes Ta n
445: .It \&.Er Ta Yes Ta Yes Ta >0
446: .It \&.Ev Ta Yes Ta Yes Ta n
447: .It \&.Ex Ta \&No Ta \&No Ta 0
448: .It \&.Fa Ta Yes Ta Yes Ta n
449: .It \&.Fd Ta \&No Ta \&No Ta >0
450: .It \&.Fl Ta Yes Ta Yes Ta n
451: .It \&.Fn Ta Yes Ta Yes Ta >0
1.3 schwarze 452: .It \&.Ft Ta Yes Ta Yes Ta n
1.1 kristaps 453: .It \&.Ic Ta Yes Ta Yes Ta >0
454: .It \&.In Ta \&No Ta \&No Ta n
455: .It \&.Li Ta Yes Ta Yes Ta n
456: .It \&.Nd Ta \&No Ta \&No Ta n
457: .It \&.Nm Ta Yes Ta Yes Ta n
458: .It \&.Ot Ta \&No Ta \&No Ta n
459: .It \&.Pa Ta Yes Ta Yes Ta n
460: .It \&.Rv Ta \&No Ta \&No Ta 0
461: .It \&.St Ta \&No Ta Yes Ta 1
462: .It \&.Va Ta Yes Ta Yes Ta n
463: .It \&.Vt Ta Yes Ta Yes Ta >0
464: .It \&.Xr Ta Yes Ta Yes Ta >0, <3
465: .It \&.%A Ta \&No Ta \&No Ta >0
466: .It \&.%B Ta \&No Ta \&No Ta >0
467: .It \&.%C Ta \&No Ta \&No Ta >0
468: .It \&.%D Ta \&No Ta \&No Ta >0
469: .It \&.%I Ta \&No Ta \&No Ta >0
470: .It \&.%J Ta \&No Ta \&No Ta >0
471: .It \&.%N Ta \&No Ta \&No Ta >0
472: .It \&.%O Ta \&No Ta \&No Ta >0
473: .It \&.%P Ta \&No Ta \&No Ta >0
474: .It \&.%R Ta \&No Ta \&No Ta >0
475: .It \&.%T Ta \&No Ta \&No Ta >0
476: .It \&.%V Ta \&No Ta \&No Ta >0
477: .It \&.At Ta Yes Ta Yes Ta 1
478: .It \&.Bsx Ta Yes Ta Yes Ta n
479: .It \&.Bx Ta Yes Ta Yes Ta n
480: .It \&.Db Ta \&No Ta \&No Ta 1
481: .It \&.Em Ta Yes Ta Yes Ta >0
482: .It \&.Fx Ta Yes Ta Yes Ta n
1.3 schwarze 483: .It \&.Ms Ta Yes Ta Yes Ta >0
1.1 kristaps 484: .It \&.No Ta Yes Ta Yes Ta 0
485: .It \&.Ns Ta Yes Ta Yes Ta 0
486: .It \&.Nx Ta Yes Ta Yes Ta n
487: .It \&.Ox Ta Yes Ta Yes Ta n
488: .It \&.Pf Ta \&No Ta Yes Ta 1
489: .It \&.Sm Ta \&No Ta \&No Ta 1
490: .It \&.Sx Ta Yes Ta Yes Ta >0
491: .It \&.Sy Ta Yes Ta Yes Ta >0
492: .It \&.Tn Ta Yes Ta Yes Ta >0
493: .It \&.Ux Ta Yes Ta Yes Ta n
494: .It \&.Dx Ta Yes Ta Yes Ta n
495: .It \&.Bt Ta \&No Ta \&No Ta 0
496: .It \&.Hf Ta \&No Ta \&No Ta n
497: .It \&.Fr Ta \&No Ta \&No Ta n
498: .It \&.Ud Ta \&No Ta \&No Ta 0
499: .It \&.Lb Ta \&No Ta \&No Ta 1
500: .It \&.Ap Ta Yes Ta Yes Ta 0
501: .It \&.Lp Ta \&No Ta \&No Ta 0
1.3 schwarze 502: .It \&.Lk Ta Yes Ta Yes Ta n
503: .It \&.Mt Ta Yes Ta Yes Ta >0
1.1 kristaps 504: .It \&.Es Ta \&No Ta \&No Ta 0
505: .It \&.En Ta \&No Ta \&No Ta 0
506: .El
507: .Pp
508: The
509: .Sq \&.Ot ,
510: .Sq \&.Fr ,
511: .Sq \&.Es
512: and
513: .Sq \&.En ,
514: macros are obsolete.
515: .\" SECTION
516: .Sh COMPATIBILITY
1.3 schwarze 517: This section documents compatibility with other roff implementations, at
518: this time limited to
519: .Xr groff 1 .
520: The term
521: .Qq historic groff
522: refers to those versions before the
523: .Pa doc.tmac
524: file re-write
525: .Pq somewhere between 1.15 and 1.19 .
1.1 kristaps 526: .Pp
527: .Bl -dash -compact
528: .\" LIST-ITEM
529: .It
1.7 ! schwarze 530: Some character sequences in groff are not handled depending on escape
! 531: style, e.g.,
! 532: .Sq \e(ba
! 533: and
! 534: .Sq \e*(Ba
! 535: may not be interchanged. This is no longer the case: all character
! 536: sequences resolve to the same symbol, regardless the escape style.
! 537: .\" LIST-ITEM
! 538: .It
! 539: Blocks of whitespace are stripped from both macro and free-form text
! 540: lines (except when in literal mode), while groff would retain whitespace
! 541: in free-form text lines.
! 542: .\" LIST-ITEM
! 543: .It
1.3 schwarze 544: Historic groff has many un-callable macros. Most of these (excluding
545: some block-level macros) are now callable, conforming to the
546: non-historic groff version.
547: .\" LIST-ITEM
548: .It
549: The vertical bar
1.7 ! schwarze 550: .Sq \(ba
1.3 schwarze 551: made historic groff
552: .Qq go orbital
553: but is a proper delimiter in this implementation.
1.1 kristaps 554: .\" LIST-ITEM
555: .It
556: .Sq \&.It \-nested
1.3 schwarze 557: is assumed for all lists (it wasn't in historic groff): any list may be
558: nested and
1.1 kristaps 559: .Sq \-enum
560: lists will restart the sequence only for the sub-list.
561: .\" LIST-ITEM
562: .It
563: .Sq \&.It \-column
1.3 schwarze 564: syntax where column widths may be preceded by other arguments (instead
1.1 kristaps 565: of proceeded) is not supported.
566: .\" LIST-ITEM
567: .It
568: The
569: .Sq \&.At
570: macro only accepts a single parameter.
571: .\" LIST-ITEM
572: .It
573: Some manuals use
574: .Sq \&.Li
575: incorrectly by following it with a reserved character and expecting the
576: delimiter to render. This is not supported.
577: .\" LIST-ITEM
578: .It
1.7 ! schwarze 579: If an special-character control character is escaped
! 580: .Sq \e\e ,
! 581: it will obviously not render the subsequent sequence. Even newer
! 582: versions of groff seem to dither on this.
1.1 kristaps 583: .El
584: .\" SECTION
585: .Sh SEE ALSO
586: .Xr mandoc 1 ,
587: .Xr mandoc_char 7
588: .\" SECTION
589: .Sh AUTHORS
590: The
591: .Nm
592: utility was written by
1.2 schwarze 593: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 594: .\" SECTION
595: .Sh CAVEATS
1.2 schwarze 596: There are many ambiguous parts of mdoc.
1.1 kristaps 597: .Pp
598: .Bl -dash -compact
599: .\" LIST-ITEM
600: .It
601: .Sq \&.Fa
602: should be
603: .Sq \&.Va
604: as function arguments are variables.
605: .\" LIST-ITEM
606: .It
607: .Sq \&.Ft
608: should be
609: .Sq \&.Vt
610: as function return types are still types. Furthermore, the
611: .Sq \&.Ft
612: should be removed and
613: .Sq \&.Fo ,
614: which ostensibly follows it, should follow the same convention as
615: .Sq \&.Va .
616: .\" LIST-ITEM
617: .It
618: .Sq \&.Va
619: should formalise that only one or two arguments are acceptable: a
1.2 schwarze 620: variable name and optional, preceding type.
1.1 kristaps 621: .\" LIST-ITEM
622: .It
623: .Sq \&.Fd
624: is ambiguous. It's commonly used to indicate an include file in the
625: synopsis section.
626: .Sq \&.In
627: should be used, instead.
628: .\" LIST-ITEM
629: .It
630: Only the
631: .Sq \-literal
632: argument to
633: .Sq \&.Bd
634: makes sense. The remaining ones should be removed.
635: .\" LIST-ITEM
636: .It
637: The
638: .Sq \&.Xo
639: and
640: .Sq \&.Xc
641: macros should be deprecated.
642: .\" LIST-ITEM
643: .It
644: The
645: .Sq \&.Dt
646: macro lacks clarity. It should be absolutely clear which title will
647: render when formatting the manual page.
648: .\" LIST-ITEM
649: .It
650: A
651: .Sq \&.Lx
652: should be provided for Linux (\(`a la
653: .Sq \&.Ox ,
654: .Sq \&.Nx
655: etc.).
656: .\" LIST-ITEM
657: .It
658: There's no way to refer to references in
659: .Sq \&.Rs/.Re
660: blocks.
1.6 schwarze 661: .\" LIST-ITEM
662: .It
663: The \-split and \-nosplit arguments to
664: .Sq \&.An
665: are inane.
1.1 kristaps 666: .El
![[BACK]](/icons/back.gif){kind=icon}
Return to mdoc.7 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc