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