Annotation of src/usr.bin/mandoc/mdoc.7, Revision 1.2
1.2 ! schwarze 1: .\" $Id: mdoc.7,v 1.28 2009/06/12 12:40:44 kristaps 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: .\"
17: .Dd $Mdocdate$
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
34: language.
35: .\" PARAGRAPH
36: .Pp
37: An
38: .Nm
39: document follows simple rules: lines beginning with the control
40: character
41: .Sq \.
42: are parsed for macros. Other lines are interpreted within the scope of
43: prior macros:
44: .Bd -literal -offset XXX
45: \&.Sh Macro lines change control state.
46: Other lines are interpreted within the current state.
47: .Ed
48: .\" SECTION
49: .Sh INPUT ENCODING
50: .Nm
51: documents may contain only graphable 7-bit ASCII characters, the space
52: character
53: .Sq \ ,
54: and, in certain circumstances, the tab character
55: .Sq \et .
56: All manuals must have
57: .Sq \en
58: line termination.
59: .Pp
60: The only time a blank line is acceptable is within
61: the context of
62: .Sq \&.Bd \-literal
63: or
64: .Sq \&.Bd \-unfilled .
65: .Pp
66: Tab characters
67: .Pq \et
68: are only acceptable when delimiting
69: .Sq \&.Bl \-column
70: and in
71: .Sq \&.Bd \-literal
72: or
73: .Sq \&.Bd \-unfilled
74: contexts.
75: .\" SUB-SECTION
76: .Ss Reserved Characters
77: Within a macro line, the following characters are reserved:
78: .Bl -tag -width 12n -offset XXXX -compact
79: .It \&.
80: .Pq period
81: .It \&,
82: .Pq comma
83: .It \&:
84: .Pq colon
85: .It \&;
86: .Pq semicolon
87: .It \&(
88: .Pq left-parenthesis
89: .It \&)
90: .Pq right-parenthesis
91: .It \&[
92: .Pq left-bracket
93: .It \&]
94: .Pq right-bracket
95: .It \&?
96: .Pq question
97: .It \&!
98: .Pq exclamation
99: .El
100: .\" PARAGRAPH
101: .Pp
102: Use of reserved characters is described in
103: .Sx Closure .
104: For general non-reserved use, characters must either be escaped with a
105: non-breaking space
106: .Pq Sq \e&
107: or, if applicable, an appropriate escape-sequence used.
108: .\" SUB-SECTION
109: .Ss Special Characters
110: Special character sequences begin with the escape character
111: .Sq \e
112: followed by either an open-parenthesis
113: .Sq \&(
114: for two-character sequences; an open-bracket
115: .Sq \&[
116: for n-character sequences (terminated at a close-bracket
117: .Sq \&] ) ;
118: or a single one-character sequence.
119: .Pp
120: Characters may alternatively be escaped by a slash-asterisk,
121: .Sq \e* ,
122: with the same combinations as described above. This form is deprecated.
123: .\" SECTION
124: .Sh STRUCTURE
125: Macros are classified in an ontology described by their scope rules.
126: Some macros are allowed to deviate from their classifications to
127: preserve backward-compatibility with old macro combinations still found
128: in the manual corpus. These are specifically noted on a per-macro
129: basis.
130: .\" SUB-SECTION
131: .Ss Scope
132: .Bl -inset
133: .\" LIST-ITEM
134: .It Em Block
135: macros enclose other block macros, in-line macros or text, and
136: may span multiple lines.
137: .Bl -inset -offset XXXX
138: .\" LIST-ITEM
139: .It Em Full-block
140: macros always span multiple lines. They consist of zero or
141: more
142: .Qq heads ,
143: subsequent macros or text on the same line following invocation; an
144: optional
145: .Qq body ,
146: which spans subsequent lines of text or macros; and an optional
147: .Qq tail ,
148: macros or text on the same line following closure.
149: .\" LIST-ITEM
150: .It Em Partial-block
151: macros may span multiple lines. They consists of a optional
152: .Qq head ,
153: text immediately following invocation; always a
154: .Qq body ,
155: text or macros following the head on the same and subsequent lines; and
156: optionally a
157: .Qq tail ,
158: text immediately following closure.
159: .\" LIST-ITEM
160: .It Em In-line
161: macros may only enclose text and span at most a single line.
162: .El
163: .El
164: .\" SUB-SECTION
165: .Ss Closure
166: Closure of a macro's scope depends first on its classification, then
167: on whether it's parsable. In this table,
168: .Sq BFE
169: refers to block full-explicit and so on.
170: .\" PARAGRAPH
171: .Pp
172: .Bl -tag -width 12n -offset XXXX -compact
173: .It BPE , BFE
174: corresponding explicit closure macro
175: .It BFI
176: end-of-file or a corresponding implicit closure macro
177: .It BPI
178: end-of-line (body may be closed by >0 space-separated
179: .Sx Reserved Characters ,
180: although block scope will still be open)
181: .It INL
182: end-of-line
183: .El
184: .\" PARAGRAPH
185: .Pp
186: If a macro (block or in-line) is parsable, it may also be closed out by
187: one of the following scenarios (unless specifically noted otherwise):
188: .\" PARAGRAPH
189: .Pp
190: .Bl -dash -offset XXXX -compact
191: .It
192: a sequence of >0 space-separated
193: .Sx Reserved Characters ,
194: .It
195: another macro,
196: .It
197: end-of-line, or
198: .It
199: completion of a set number of arguments.
200: .El
201: .\" PARAGRAPH
202: .Pp
203: If >0 space-separated
204: .Sx Reserved Characters
205: are followed by non-reserved characters, the behaviour differs per
206: macro. In general, scope of the macro is closed and re-opened:
207: subsequent tokens are interpreted as if the scope had just been opened.
208: In other circumstances, scope is simply closed out.
209: .\" SECTION
210: .Sh SYNTAX
211: Macros are two or three characters in length. The syntax of macro
212: invocation depends on its classification.
213: .Qq \-arg
214: refers to the macro arguments (which may contain zero or more values).
215: In these illustrations,
216: .Sq \&.Yo
217: opens the scope of a macro, and if specified,
218: .Sq \&.Yc
219: closes it out (closure may be implicit at end-of-line or end-of-file).
220: .\" PARAGRAPH
221: .Pp
222: Block full-explicit (may contain head, body, tail).
223: .Bd -literal -offset XXXX
224: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
225: \(lBbody...\(rB
226: \&.Yc \(lBtail...\(rB
227: .Ed
228: .\" PARAGRAPH
229: .Pp
230: Block full-implicit (may contain zero or more heads, body, no tail).
231: .Bd -literal -offset XXXX
232: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
233: \(lBbody...\(rB
234: \&.Yc
235: .Ed
236: .\" PARAGRAPH
237: .Pp
238: Block partial-explicit (may contain head, multi-line body, tail).
239: .Bd -literal -offset XXXX
240: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
241: \(lBbody...\(rB
242: \&.Yc \(lBtail...\(rB
243:
244: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
245: \(lBbody...\(rB \&Yc \(lBtail...\(rB
246: .Ed
247: .\" PARAGRAPH
248: .Pp
249: Block partial-implicit (no head, body, no tail). Note that the body
250: section may be followed by zero or more
251: .Sx Reserved Words .
252: These are in the block scope, but not in the body scope.
253: .Bd -literal -offset XXXX
254: \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
255: .Ed
256: .\" PARAGRAPH
257: .Pp
258: In-lines have \(>=0 scoped arguments.
259: .Bd -literal -offset XXX
260: \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
261:
262: \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
263: .Ed
264: .\"
265: .Sh MACROS
266: This section contains a complete list of all
267: .Nm
268: macros, arranged ontologically. A
269: .Qq callable
270: macro is invoked subsequent to the initial macro-line macro. A
271: .Qq parsable
272: macro may be followed by further (ostensibly callable) macros.
273: .\" SUB-SECTION
274: .Ss Block full-implicit
275: The head of these macros follows invocation; the body is the content of
276: subsequent lines prior to closure. None of these macros have tails;
277: some
278: .Po
279: .Sq \&.It \-bullet ,
280: .Sq \-hyphen ,
281: .Sq \-dash ,
282: .Sq \-enum ,
283: .Sq \-item
284: .Pc
285: don't have heads.
286: .Pp
287: .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
288: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
289: .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
290: .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
291: .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
292: .El
293: .\" SUB-SECTION
294: .Ss Block full-explicit
295: None of these macros are callable or parsed. The last column indicates
296: the explicit scope rules. All contains bodies, some may contain heads
297: .Pq So \&Bf Sc .
298: .Pp
299: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
300: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
301: .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
302: .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
303: .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
304: .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
305: .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
306: .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
307: .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
308: .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
309: .El
310: .\" SUB-SECTION
311: .Ss Block partial-implicit
312: All of these are callable and parsed for further macros. Their scopes
313: close at the invocation's end-of-line.
314: .Pp
315: .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
316: .It Em Macro Ta Em Callable Ta Em Parsable
317: .It \&.Aq Ta Yes Ta Yes
318: .It \&.Op Ta Yes Ta Yes
319: .It \&.Bq Ta Yes Ta Yes
320: .It \&.Dq Ta Yes Ta Yes
321: .It \&.Pq Ta Yes Ta Yes
322: .It \&.Qq Ta Yes Ta Yes
323: .It \&.Sq Ta Yes Ta Yes
324: .It \&.Brq Ta Yes Ta Yes
325: .It \&.D1 Ta \&No Ta \&Yes
326: .It \&.Dl Ta \&No Ta Yes
327: .It \&.Ql Ta Yes Ta Yes
328: .El
329: .\" PARAGRAPH
330: .Pp
331: The
332: .Sq \&.Op
333: may be broken by
334: .Sq \&.Oc
335: as in the following example:
336: .Bd -literal -offset XXXX
337: \&.Oo
338: \&.Op Fl a Oc
339: .Ed
340: .Pp
341: In the above example, the scope of
342: .Sq \&.Op
343: is technically broken by
344: .Sq \&.Oc ,
345: however, due to the overwhelming existence of this sequence, it's
346: allowed.
347: .\" SUB-SECTION
348: .Ss Block partial-explicit
349: Each of these contains at least a body and, in limited circumstances, a
350: head
351: .Pq So \&.Fo Sc , So \&.Eo Sc
352: and/or tail
353: .Pq So \&.Ec Sc .
354: .Pp
355: .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
356: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
357: .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
358: .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
359: .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
360: .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
361: .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
362: .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
363: .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
364: .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
365: .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
366: .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
367: .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
368: .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
369: .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
370: .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
371: .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
372: .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
373: .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
374: .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
375: .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
376: .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
377: .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
378: .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
379: .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
380: .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
381: .El
382: .\" SUB-SECTION
383: .Ss In-line
384: In-line macros have only text children. If a number (or inequality) of
385: arguments is
386: .Pq n ,
387: then the macro accepts an arbitrary number of arguments.
388: .Pp
389: .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
390: .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
391: .It \&.Dd Ta \&No Ta \&No Ta >0
392: .It \&.Dt Ta \&No Ta \&No Ta n
393: .It \&.Os Ta \&No Ta \&No Ta n
394: .It \&.Pp Ta \&No Ta \&No Ta 0
395: .It \&.Ad Ta Yes Ta Yes Ta n
396: .It \&.An Ta \&No Ta Yes Ta n
397: .It \&.Ar Ta Yes Ta Yes Ta n
398: .It \&.Cd Ta Yes Ta \&No Ta >0
399: .It \&.Cm Ta Yes Ta Yes Ta n
400: .It \&.Dv Ta Yes Ta Yes Ta n
401: .It \&.Er Ta Yes Ta Yes Ta >0
402: .It \&.Ev Ta Yes Ta Yes Ta n
403: .It \&.Ex Ta \&No Ta \&No Ta 0
404: .It \&.Fa Ta Yes Ta Yes Ta n
405: .It \&.Fd Ta \&No Ta \&No Ta >0
406: .It \&.Fl Ta Yes Ta Yes Ta n
407: .It \&.Fn Ta Yes Ta Yes Ta >0
408: .It \&.Ft Ta \&No Ta Yes Ta n
409: .It \&.Ic Ta Yes Ta Yes Ta >0
410: .It \&.In Ta \&No Ta \&No Ta n
411: .It \&.Li Ta Yes Ta Yes Ta n
412: .It \&.Nd Ta \&No Ta \&No Ta n
413: .It \&.Nm Ta Yes Ta Yes Ta n
414: .It \&.Ot Ta \&No Ta \&No Ta n
415: .It \&.Pa Ta Yes Ta Yes Ta n
416: .It \&.Rv Ta \&No Ta \&No Ta 0
417: .It \&.St Ta \&No Ta Yes Ta 1
418: .It \&.Va Ta Yes Ta Yes Ta n
419: .It \&.Vt Ta Yes Ta Yes Ta >0
420: .It \&.Xr Ta Yes Ta Yes Ta >0, <3
421: .It \&.%A Ta \&No Ta \&No Ta >0
422: .It \&.%B Ta \&No Ta \&No Ta >0
423: .It \&.%C Ta \&No Ta \&No Ta >0
424: .It \&.%D Ta \&No Ta \&No Ta >0
425: .It \&.%I Ta \&No Ta \&No Ta >0
426: .It \&.%J Ta \&No Ta \&No Ta >0
427: .It \&.%N Ta \&No Ta \&No Ta >0
428: .It \&.%O Ta \&No Ta \&No Ta >0
429: .It \&.%P Ta \&No Ta \&No Ta >0
430: .It \&.%R Ta \&No Ta \&No Ta >0
431: .It \&.%T Ta \&No Ta \&No Ta >0
432: .It \&.%V Ta \&No Ta \&No Ta >0
433: .It \&.At Ta Yes Ta Yes Ta 1
434: .It \&.Bsx Ta Yes Ta Yes Ta n
435: .It \&.Bx Ta Yes Ta Yes Ta n
436: .It \&.Db Ta \&No Ta \&No Ta 1
437: .It \&.Em Ta Yes Ta Yes Ta >0
438: .It \&.Fx Ta Yes Ta Yes Ta n
439: .It \&.Ms Ta \&No Ta Yes Ta >0
440: .It \&.No Ta Yes Ta Yes Ta 0
441: .It \&.Ns Ta Yes Ta Yes Ta 0
442: .It \&.Nx Ta Yes Ta Yes Ta n
443: .It \&.Ox Ta Yes Ta Yes Ta n
444: .It \&.Pf Ta \&No Ta Yes Ta 1
445: .It \&.Sm Ta \&No Ta \&No Ta 1
446: .It \&.Sx Ta Yes Ta Yes Ta >0
447: .It \&.Sy Ta Yes Ta Yes Ta >0
448: .It \&.Tn Ta Yes Ta Yes Ta >0
449: .It \&.Ux Ta Yes Ta Yes Ta n
450: .It \&.Dx Ta Yes Ta Yes Ta n
451: .It \&.Bt Ta \&No Ta \&No Ta 0
452: .It \&.Hf Ta \&No Ta \&No Ta n
453: .It \&.Fr Ta \&No Ta \&No Ta n
454: .It \&.Ud Ta \&No Ta \&No Ta 0
455: .It \&.Lb Ta \&No Ta \&No Ta 1
456: .It \&.Ap Ta Yes Ta Yes Ta 0
457: .It \&.Lp Ta \&No Ta \&No Ta 0
458: .It \&.Lk Ta \&No Ta Yes Ta >0
459: .It \&.Mt Ta \&No Ta Yes Ta >0
460: .It \&.Es Ta \&No Ta \&No Ta 0
461: .It \&.En Ta \&No Ta \&No Ta 0
462: .El
463: .Pp
464: The
465: .Sq \&.Ot ,
466: .Sq \&.Fr ,
467: .Sq \&.Es
468: and
469: .Sq \&.En ,
470: macros are obsolete.
471: .\" SECTION
472: .Sh COMPATIBILITY
473: The mdoc language was traditionally a
474: .Qq roff
475: macro package; most existing manuals were written with mdoc syntax
476: dictated by system-dependent roff installations. This section documents
477: compatibility with these systems.
478: .Pp
479: .Bl -dash -compact
480: .\" LIST-ITEM
481: .It
482: .Sq \&.Fo
483: and
484: .Sq \&.St
485: historically weren't always callable. Both are now correctly callable.
486: .\" LIST-ITEM
487: .It
488: .Sq \&.It \-nested
489: is assumed for all lists: any list may be nested and
490: .Sq \-enum
491: lists will restart the sequence only for the sub-list.
492: .\" LIST-ITEM
493: .It
494: .Sq \&.It \-column
495: syntax where column widths may be preceeded by other arguments (instead
496: of proceeded) is not supported.
497: .\" LIST-ITEM
498: .It
499: The
500: .Sq \&.At
501: macro only accepts a single parameter.
502: .\" LIST-ITEM
503: .It
504: The system-name macros (
505: .Ns Sq \&.At ,
506: .Sq \&.Bsx ,
507: .Sq \&.Bx ,
508: .Sq \&.Fx ,
509: .Sq \&.Nx ,
510: .Sq \&.Ox ,
511: and
512: .Sq \&.Ux )
513: are callable.
514: .\" LIST-ITEM
515: .It
516: Some manuals use
517: .Sq \&.Li
518: incorrectly by following it with a reserved character and expecting the
519: delimiter to render. This is not supported.
520: .\" LIST-ITEM
521: .It
522: .Sq \&.Cd
523: is callable.
524: .El
525: .\" SECTION
526: .Sh SEE ALSO
527: .Xr mandoc 1 ,
528: .Xr mandoc_char 7
529: .\" SECTION
530: .Sh AUTHORS
531: The
532: .Nm
533: utility was written by
1.2 ! schwarze 534: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 535: .\" SECTION
536: .Sh CAVEATS
1.2 ! schwarze 537: There are many ambiguous parts of mdoc.
1.1 kristaps 538: .Pp
539: .Bl -dash -compact
540: .\" LIST-ITEM
541: .It
542: .Sq \&.Fa
543: should be
544: .Sq \&.Va
545: as function arguments are variables.
546: .\" LIST-ITEM
547: .It
548: .Sq \&.Ft
549: should be
550: .Sq \&.Vt
551: as function return types are still types. Furthermore, the
552: .Sq \&.Ft
553: should be removed and
554: .Sq \&.Fo ,
555: which ostensibly follows it, should follow the same convention as
556: .Sq \&.Va .
557: .\" LIST-ITEM
558: .It
559: .Sq \&.Va
560: should formalise that only one or two arguments are acceptable: a
1.2 ! schwarze 561: variable name and optional, preceding type.
1.1 kristaps 562: .\" LIST-ITEM
563: .It
564: .Sq \&.Fd
565: is ambiguous. It's commonly used to indicate an include file in the
566: synopsis section.
567: .Sq \&.In
568: should be used, instead.
569: .\" LIST-ITEM
570: .It
571: Only the
572: .Sq \-literal
573: argument to
574: .Sq \&.Bd
575: makes sense. The remaining ones should be removed.
576: .\" LIST-ITEM
577: .It
578: The
579: .Sq \&.Xo
580: and
581: .Sq \&.Xc
582: macros should be deprecated.
583: .\" LIST-ITEM
584: .It
585: The
586: .Sq \&.Dt
587: macro lacks clarity. It should be absolutely clear which title will
588: render when formatting the manual page.
589: .\" LIST-ITEM
590: .It
591: A
592: .Sq \&.Lx
593: should be provided for Linux (\(`a la
594: .Sq \&.Ox ,
595: .Sq \&.Nx
596: etc.).
597: .\" LIST-ITEM
598: .It
599: There's no way to refer to references in
600: .Sq \&.Rs/.Re
601: blocks.
602: .El