Annotation of src/usr.bin/mandoc/mdoc.7, Revision 1.6
1.6 ! schwarze 1: .\" $Id: mdoc.7,v 1.5 2009/06/21 19:09:58 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.6 ! schwarze 17: .Dd $Mdocdate: June 21 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
31: manuals. In this reference document, we describe the syntax, ontology
32: and structure of the
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* ,
139: with the same combinations as described above. This form is deprecated.
140: .\" SECTION
141: .Sh STRUCTURE
1.6 ! schwarze 142: Each
! 143: .Nm
! 144: document must begin with the document prologue, containing, in order,
! 145: .Sq \&.Dd ,
! 146: .Sq \&.Dt ,
! 147: and
! 148: .Sq \&.Os .
! 149: Following these, the document body must begin with the NAME section
! 150: containing at least one
! 151: .Sq \&.Nm
! 152: followed by a
! 153: .Sq \&.Nd
! 154: macro.
! 155: .Pp
1.1 kristaps 156: Macros are classified in an ontology described by their scope rules.
157: Some macros are allowed to deviate from their classifications to
158: preserve backward-compatibility with old macro combinations still found
159: in the manual corpus. These are specifically noted on a per-macro
160: basis.
161: .\" SUB-SECTION
162: .Ss Scope
163: .Bl -inset
164: .\" LIST-ITEM
165: .It Em Block
166: macros enclose other block macros, in-line macros or text, and
167: may span multiple lines.
168: .Bl -inset -offset XXXX
169: .\" LIST-ITEM
170: .It Em Full-block
171: macros always span multiple lines. They consist of zero or
172: more
173: .Qq heads ,
174: subsequent macros or text on the same line following invocation; an
175: optional
176: .Qq body ,
177: which spans subsequent lines of text or macros; and an optional
178: .Qq tail ,
179: macros or text on the same line following closure.
180: .\" LIST-ITEM
181: .It Em Partial-block
182: macros may span multiple lines. They consists of a optional
183: .Qq head ,
184: text immediately following invocation; always a
185: .Qq body ,
186: text or macros following the head on the same and subsequent lines; and
187: optionally a
188: .Qq tail ,
189: text immediately following closure.
190: .\" LIST-ITEM
191: .It Em In-line
192: macros may only enclose text and span at most a single line.
193: .El
194: .El
195: .\" SUB-SECTION
196: .Ss Closure
197: Closure of a macro's scope depends first on its classification, then
198: on whether it's parsable. In this table,
199: .Sq BFE
200: refers to block full-explicit and so on.
201: .\" PARAGRAPH
202: .Pp
203: .Bl -tag -width 12n -offset XXXX -compact
204: .It BPE , BFE
205: corresponding explicit closure macro
206: .It BFI
207: end-of-file or a corresponding implicit closure macro
208: .It BPI
209: end-of-line (body may be closed by >0 space-separated
210: .Sx Reserved Characters ,
211: although block scope will still be open)
212: .It INL
213: end-of-line
214: .El
215: .\" PARAGRAPH
216: .Pp
217: If a macro (block or in-line) is parsable, it may also be closed out by
218: one of the following scenarios (unless specifically noted otherwise):
219: .\" PARAGRAPH
220: .Pp
221: .Bl -dash -offset XXXX -compact
222: .It
223: a sequence of >0 space-separated
224: .Sx Reserved Characters ,
225: .It
226: another macro,
227: .It
228: end-of-line, or
229: .It
230: completion of a set number of arguments.
231: .El
232: .\" PARAGRAPH
233: .Pp
234: If >0 space-separated
235: .Sx Reserved Characters
236: are followed by non-reserved characters, the behaviour differs per
237: macro. In general, scope of the macro is closed and re-opened:
238: subsequent tokens are interpreted as if the scope had just been opened.
239: In other circumstances, scope is simply closed out.
240: .\" SECTION
241: .Sh SYNTAX
242: Macros are two or three characters in length. The syntax of macro
243: invocation depends on its classification.
244: .Qq \-arg
245: refers to the macro arguments (which may contain zero or more values).
246: In these illustrations,
247: .Sq \&.Yo
248: opens the scope of a macro, and if specified,
249: .Sq \&.Yc
250: closes it out (closure may be implicit at end-of-line or end-of-file).
251: .\" PARAGRAPH
252: .Pp
253: Block full-explicit (may contain head, body, tail).
254: .Bd -literal -offset XXXX
255: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
256: \(lBbody...\(rB
257: \&.Yc \(lBtail...\(rB
258: .Ed
259: .\" PARAGRAPH
260: .Pp
261: Block full-implicit (may contain zero or more heads, body, no tail).
262: .Bd -literal -offset XXXX
263: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
264: \(lBbody...\(rB
265: \&.Yc
266: .Ed
267: .\" PARAGRAPH
268: .Pp
269: Block partial-explicit (may contain head, multi-line body, tail).
270: .Bd -literal -offset XXXX
271: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
272: \(lBbody...\(rB
273: \&.Yc \(lBtail...\(rB
274:
275: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
276: \(lBbody...\(rB \&Yc \(lBtail...\(rB
277: .Ed
278: .\" PARAGRAPH
279: .Pp
280: Block partial-implicit (no head, body, no tail). Note that the body
281: section may be followed by zero or more
282: .Sx Reserved Words .
283: These are in the block scope, but not in the body scope.
284: .Bd -literal -offset XXXX
285: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
286: .Ed
287: .\" PARAGRAPH
288: .Pp
289: In-lines have \(>=0 scoped arguments.
290: .Bd -literal -offset XXX
291: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
292:
293: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
294: .Ed
1.6 ! schwarze 295: .\" SECTION
1.1 kristaps 296: .Sh MACROS
297: This section contains a complete list of all
298: .Nm
299: macros, arranged ontologically. A
300: .Qq callable
301: macro is invoked subsequent to the initial macro-line macro. A
302: .Qq parsable
303: macro may be followed by further (ostensibly callable) macros.
304: .\" SUB-SECTION
305: .Ss Block full-implicit
306: The head of these macros follows invocation; the body is the content of
307: subsequent lines prior to closure. None of these macros have tails;
308: some
309: .Po
310: .Sq \&.It \-bullet ,
311: .Sq \-hyphen ,
312: .Sq \-dash ,
313: .Sq \-enum ,
314: .Sq \-item
315: .Pc
316: don't have heads.
317: .Pp
1.5 schwarze 318: .Bl -column -compact -offset XXXX "MacroX" "CallableX" "ParsableX" "Closing"
1.1 kristaps 319: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
320: .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
321: .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
322: .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
323: .El
324: .\" SUB-SECTION
325: .Ss Block full-explicit
326: None of these macros are callable or parsed. The last column indicates
327: the explicit scope rules. All contains bodies, some may contain heads
328: .Pq So \&Bf Sc .
329: .Pp
1.5 schwarze 330: .Bl -column -compact -offset XXXX "MacroX" "CallableX" "ParsableX" "closed by XXX"
1.1 kristaps 331: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
332: .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
333: .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
334: .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
335: .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
336: .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
337: .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
338: .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
339: .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
340: .El
341: .\" SUB-SECTION
342: .Ss Block partial-implicit
343: All of these are callable and parsed for further macros. Their scopes
344: close at the invocation's end-of-line.
345: .Pp
346: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
347: .It Em Macro Ta Em Callable Ta Em Parsable
348: .It \&.Aq Ta Yes Ta Yes
349: .It \&.Op Ta Yes Ta Yes
350: .It \&.Bq Ta Yes Ta Yes
351: .It \&.Dq Ta Yes Ta Yes
352: .It \&.Pq Ta Yes Ta Yes
353: .It \&.Qq Ta Yes Ta Yes
354: .It \&.Sq Ta Yes Ta Yes
355: .It \&.Brq Ta Yes Ta Yes
356: .It \&.D1 Ta \&No Ta \&Yes
357: .It \&.Dl Ta \&No Ta Yes
358: .It \&.Ql Ta Yes Ta Yes
359: .El
360: .\" PARAGRAPH
361: .Pp
362: The
363: .Sq \&.Op
364: may be broken by
365: .Sq \&.Oc
366: as in the following example:
367: .Bd -literal -offset XXXX
368: \&.Oo
369: \&.Op Fl a Oc
370: .Ed
371: .Pp
372: In the above example, the scope of
373: .Sq \&.Op
374: is technically broken by
375: .Sq \&.Oc ,
376: however, due to the overwhelming existence of this sequence, it's
377: allowed.
378: .\" SUB-SECTION
379: .Ss Block partial-explicit
380: Each of these contains at least a body and, in limited circumstances, a
381: head
382: .Pq So \&.Fo Sc , So \&.Eo Sc
383: and/or tail
384: .Pq So \&.Ec Sc .
385: .Pp
386: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
387: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
388: .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
389: .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
390: .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
391: .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
392: .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
393: .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
394: .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
395: .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
396: .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
397: .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
398: .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
399: .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
400: .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
401: .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
402: .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
403: .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
404: .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
405: .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
406: .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
407: .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
408: .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
409: .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
410: .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
411: .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
412: .El
413: .\" SUB-SECTION
414: .Ss In-line
415: In-line macros have only text children. If a number (or inequality) of
416: arguments is
417: .Pq n ,
418: then the macro accepts an arbitrary number of arguments.
419: .Pp
420: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
421: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
422: .It \&.Dd Ta \&No Ta \&No Ta >0
423: .It \&.Dt Ta \&No Ta \&No Ta n
424: .It \&.Os Ta \&No Ta \&No Ta n
425: .It \&.Pp Ta \&No Ta \&No Ta 0
426: .It \&.Ad Ta Yes Ta Yes Ta n
1.3 schwarze 427: .It \&.An Ta Yes Ta Yes Ta n
1.1 kristaps 428: .It \&.Ar Ta Yes Ta Yes Ta n
429: .It \&.Cd Ta Yes Ta \&No Ta >0
430: .It \&.Cm Ta Yes Ta Yes Ta n
431: .It \&.Dv Ta Yes Ta Yes Ta n
432: .It \&.Er Ta Yes Ta Yes Ta >0
433: .It \&.Ev Ta Yes Ta Yes Ta n
434: .It \&.Ex Ta \&No Ta \&No Ta 0
435: .It \&.Fa Ta Yes Ta Yes Ta n
436: .It \&.Fd Ta \&No Ta \&No Ta >0
437: .It \&.Fl Ta Yes Ta Yes Ta n
438: .It \&.Fn Ta Yes Ta Yes Ta >0
1.3 schwarze 439: .It \&.Ft Ta Yes Ta Yes Ta n
1.1 kristaps 440: .It \&.Ic Ta Yes Ta Yes Ta >0
441: .It \&.In Ta \&No Ta \&No Ta n
442: .It \&.Li Ta Yes Ta Yes Ta n
443: .It \&.Nd Ta \&No Ta \&No Ta n
444: .It \&.Nm Ta Yes Ta Yes Ta n
445: .It \&.Ot Ta \&No Ta \&No Ta n
446: .It \&.Pa Ta Yes Ta Yes Ta n
447: .It \&.Rv Ta \&No Ta \&No Ta 0
448: .It \&.St Ta \&No Ta Yes Ta 1
449: .It \&.Va Ta Yes Ta Yes Ta n
450: .It \&.Vt Ta Yes Ta Yes Ta >0
451: .It \&.Xr Ta Yes Ta Yes Ta >0, <3
452: .It \&.%A Ta \&No Ta \&No Ta >0
453: .It \&.%B Ta \&No Ta \&No Ta >0
454: .It \&.%C Ta \&No Ta \&No Ta >0
455: .It \&.%D Ta \&No Ta \&No Ta >0
456: .It \&.%I Ta \&No Ta \&No Ta >0
457: .It \&.%J Ta \&No Ta \&No Ta >0
458: .It \&.%N Ta \&No Ta \&No Ta >0
459: .It \&.%O Ta \&No Ta \&No Ta >0
460: .It \&.%P Ta \&No Ta \&No Ta >0
461: .It \&.%R Ta \&No Ta \&No Ta >0
462: .It \&.%T Ta \&No Ta \&No Ta >0
463: .It \&.%V Ta \&No Ta \&No Ta >0
464: .It \&.At Ta Yes Ta Yes Ta 1
465: .It \&.Bsx Ta Yes Ta Yes Ta n
466: .It \&.Bx Ta Yes Ta Yes Ta n
467: .It \&.Db Ta \&No Ta \&No Ta 1
468: .It \&.Em Ta Yes Ta Yes Ta >0
469: .It \&.Fx Ta Yes Ta Yes Ta n
1.3 schwarze 470: .It \&.Ms Ta Yes Ta Yes Ta >0
1.1 kristaps 471: .It \&.No Ta Yes Ta Yes Ta 0
472: .It \&.Ns Ta Yes Ta Yes Ta 0
473: .It \&.Nx Ta Yes Ta Yes Ta n
474: .It \&.Ox Ta Yes Ta Yes Ta n
475: .It \&.Pf Ta \&No Ta Yes Ta 1
476: .It \&.Sm Ta \&No Ta \&No Ta 1
477: .It \&.Sx Ta Yes Ta Yes Ta >0
478: .It \&.Sy Ta Yes Ta Yes Ta >0
479: .It \&.Tn Ta Yes Ta Yes Ta >0
480: .It \&.Ux Ta Yes Ta Yes Ta n
481: .It \&.Dx Ta Yes Ta Yes Ta n
482: .It \&.Bt Ta \&No Ta \&No Ta 0
483: .It \&.Hf Ta \&No Ta \&No Ta n
484: .It \&.Fr Ta \&No Ta \&No Ta n
485: .It \&.Ud Ta \&No Ta \&No Ta 0
486: .It \&.Lb Ta \&No Ta \&No Ta 1
487: .It \&.Ap Ta Yes Ta Yes Ta 0
488: .It \&.Lp Ta \&No Ta \&No Ta 0
1.3 schwarze 489: .It \&.Lk Ta Yes Ta Yes Ta n
490: .It \&.Mt Ta Yes Ta Yes Ta >0
1.1 kristaps 491: .It \&.Es Ta \&No Ta \&No Ta 0
492: .It \&.En Ta \&No Ta \&No Ta 0
493: .El
494: .Pp
495: The
496: .Sq \&.Ot ,
497: .Sq \&.Fr ,
498: .Sq \&.Es
499: and
500: .Sq \&.En ,
501: macros are obsolete.
502: .\" SECTION
503: .Sh COMPATIBILITY
1.3 schwarze 504: This section documents compatibility with other roff implementations, at
505: this time limited to
506: .Xr groff 1 .
507: The term
508: .Qq historic groff
509: refers to those versions before the
510: .Pa doc.tmac
511: file re-write
512: .Pq somewhere between 1.15 and 1.19 .
1.1 kristaps 513: .Pp
514: .Bl -dash -compact
515: .\" LIST-ITEM
516: .It
1.3 schwarze 517: Historic groff has many un-callable macros. Most of these (excluding
518: some block-level macros) are now callable, conforming to the
519: non-historic groff version.
520: .\" LIST-ITEM
521: .It
522: The vertical bar
523: .Sq \(Ba
524: made historic groff
525: .Qq go orbital
526: but is a proper delimiter in this implementation.
1.1 kristaps 527: .\" LIST-ITEM
528: .It
529: .Sq \&.It \-nested
1.3 schwarze 530: is assumed for all lists (it wasn't in historic groff): any list may be
531: nested and
1.1 kristaps 532: .Sq \-enum
533: lists will restart the sequence only for the sub-list.
534: .\" LIST-ITEM
535: .It
536: .Sq \&.It \-column
1.3 schwarze 537: syntax where column widths may be preceded by other arguments (instead
1.1 kristaps 538: of proceeded) is not supported.
539: .\" LIST-ITEM
540: .It
541: The
542: .Sq \&.At
543: macro only accepts a single parameter.
544: .\" LIST-ITEM
545: .It
546: Some manuals use
547: .Sq \&.Li
548: incorrectly by following it with a reserved character and expecting the
549: delimiter to render. This is not supported.
550: .\" LIST-ITEM
551: .It
1.3 schwarze 552: If an special-character control character
553: .Sq \e
554: is escaped, it will
555: obviously not render the sequence. Even newer versions of groff seem to
556: dither on this.
1.1 kristaps 557: .El
558: .\" SECTION
559: .Sh SEE ALSO
560: .Xr mandoc 1 ,
561: .Xr mandoc_char 7
562: .\" SECTION
563: .Sh AUTHORS
564: The
565: .Nm
566: utility was written by
1.2 schwarze 567: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 568: .\" SECTION
569: .Sh CAVEATS
1.2 schwarze 570: There are many ambiguous parts of mdoc.
1.1 kristaps 571: .Pp
572: .Bl -dash -compact
573: .\" LIST-ITEM
574: .It
575: .Sq \&.Fa
576: should be
577: .Sq \&.Va
578: as function arguments are variables.
579: .\" LIST-ITEM
580: .It
581: .Sq \&.Ft
582: should be
583: .Sq \&.Vt
584: as function return types are still types. Furthermore, the
585: .Sq \&.Ft
586: should be removed and
587: .Sq \&.Fo ,
588: which ostensibly follows it, should follow the same convention as
589: .Sq \&.Va .
590: .\" LIST-ITEM
591: .It
592: .Sq \&.Va
593: should formalise that only one or two arguments are acceptable: a
1.2 schwarze 594: variable name and optional, preceding type.
1.1 kristaps 595: .\" LIST-ITEM
596: .It
597: .Sq \&.Fd
598: is ambiguous. It's commonly used to indicate an include file in the
599: synopsis section.
600: .Sq \&.In
601: should be used, instead.
602: .\" LIST-ITEM
603: .It
604: Only the
605: .Sq \-literal
606: argument to
607: .Sq \&.Bd
608: makes sense. The remaining ones should be removed.
609: .\" LIST-ITEM
610: .It
611: The
612: .Sq \&.Xo
613: and
614: .Sq \&.Xc
615: macros should be deprecated.
616: .\" LIST-ITEM
617: .It
618: The
619: .Sq \&.Dt
620: macro lacks clarity. It should be absolutely clear which title will
621: render when formatting the manual page.
622: .\" LIST-ITEM
623: .It
624: A
625: .Sq \&.Lx
626: should be provided for Linux (\(`a la
627: .Sq \&.Ox ,
628: .Sq \&.Nx
629: etc.).
630: .\" LIST-ITEM
631: .It
632: There's no way to refer to references in
633: .Sq \&.Rs/.Re
634: blocks.
1.6 ! schwarze 635: .\" LIST-ITEM
! 636: .It
! 637: The \-split and \-nosplit arguments to
! 638: .Sq \&.An
! 639: are inane.
1.1 kristaps 640: .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