]> git.cameronkatri.com Git - mandoc.git/blob - mdoc.7
Added default print of `~' with empty `Pa' (not documented with OpenBSD, but still...
[mandoc.git] / mdoc.7
1 .\" $Id: mdoc.7,v 1.50 2009/07/20 13:45:11 kristaps Exp $
2 .\"
3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
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 above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
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.
16 .\"
17 .Dd $Mdocdate: July 20 2009 $
18 .Dt MDOC 7
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 its syntax, structure,
32 and usage. Our reference implementation is
33 .Xr mandoc 1 .
34 The
35 .Sx COMPATIBILITY
36 section describes compatibility with
37 .Xr groff 1 .
38 .\" PARAGRAPH------------
39 .Pp
40 An
41 .Nm
42 document follows simple rules: lines beginning with the control
43 character
44 .Sq \.
45 are parsed for macros. Other lines are interpreted within the scope of
46 prior macros:
47 .Bd -literal -offset indent
48 \&.Sh Macro lines change control state.
49 Other lines are interpreted within the current state.
50 .Ed
51 .\" SECTION---------------------------------------------
52 .Sh LANGUAGE SYNTAX
53 .Nm
54 documents may contain only graphable 7-bit ASCII characters, the space
55 character, and, in certain circumstances, the tab character. All
56 manuals must have
57 .Ux
58 line terminators.
59 .\" SUB-SECTION----------------------
60 .Ss Comments
61 Text following a
62 .Sq \e" ,
63 whether in a macro or free-form text line, is ignored to the end of
64 line. A macro line with only a control character and comment escape,
65 .Sq \&.\e" ,
66 is also ignored.
67 .\" SUB-SECTION----------------------
68 .Ss Reserved Characters
69 Within a macro line, the following characters are reserved:
70 .Bl -tag -width Ds -offset indent -compact
71 .It \&.
72 .Pq period
73 .It \&,
74 .Pq comma
75 .It \&:
76 .Pq colon
77 .It \&;
78 .Pq semicolon
79 .It \&(
80 .Pq left-parenthesis
81 .It \&)
82 .Pq right-parenthesis
83 .It \&[
84 .Pq left-bracket
85 .It \&]
86 .Pq right-bracket
87 .It \&?
88 .Pq question
89 .It \&!
90 .Pq exclamation
91 .It \&|
92 .Pq vertical bar
93 .El
94 .\" PARAGRAPH------------
95 .Pp
96 Use of reserved characters is described in
97 .Sx MACRO SYNTAX .
98 For general use in macro lines, these characters must either be escaped
99 with a non-breaking space
100 .Pq Sq \e&
101 or, if applicable, an appropriate escape sequence used.
102 .\" SUB-SECTION----------------------
103 .Ss Special Characters
104 Special characters may occur in both macro and free-form lines.
105 Sequences begin with the escape character
106 .Sq \e
107 followed by either an open-parenthesis
108 .Sq \&(
109 for two-character sequences; an open-bracket
110 .Sq \&[
111 for n-character sequences (terminated at a close-bracket
112 .Sq \&] ) ;
113 or a single one-character sequence. See
114 .Xr mandoc_char 1
115 for a complete list. Examples include
116 .Sq \e(em
117 .Pq em-dash
118 and
119 .Sq \ee
120 .Pq back-slash .
121 .\" PARAGRAPH------------
122 .Pp
123 An alternative escape sequence is
124 the slash-asterisk,
125 .Sq \e* ,
126 but this method is discouraged for compatibility reasons.
127 .\" PARAGRAPH------------
128 .Pp
129 Terms may
130 also be text-decorated using the
131 .Sq \ef
132 escape followed by an indicator: B (bold), I, (italic), or P and R
133 (Roman, or reset). This form is not recommended.
134 .\" SUB-SECTION----------------------
135 .Ss Whitespace
136 In non-literal free-form lines, consecutive blocks of whitespace are
137 pruned from input and added later in the output filter, if applicable:
138 .Bd -literal -offset indent
139 These spaces are pruned from input.
140 \&.Bd \-literal
141 These are not.
142 \&.Ed
143 .Ed
144 .\" PARAGRAPH------------
145 .Pp
146 In macro lines, whitespace delimits arguments and is discarded. If
147 arguments are quoted, whitespace within the quotes is retained.
148 .\" PARAGRAPH------------
149 .Pp
150 Blank lines are only permitted within literal contexts, as are lines
151 containing only whitespace. Tab characters are only acceptable when
152 delimiting
153 .Sq \&Bl \-column
154 or when in a literal context.
155 .\" SUB-SECTION----------------------
156 .Ss Quotation
157 Macro arguments may be quoted with a double-quote to group
158 space-delimited terms or to retain blocks of whitespace. A quoted
159 argument begins with a double-quote preceded by whitespace. The next
160 double-quote not pair-wise adjacent to another double-quote terminates
161 the literal, regardless of surrounding whitespace.
162 .\" PARAGRAPH------------
163 .Pp
164 This produces tokens
165 .Sq a" ,
166 .Sq b c ,
167 .Sq de ,
168 and
169 .Sq fg" .
170 Note that any quoted term, be it argument or macro, is indiscriminately
171 considered literal text. Thus, the following produces
172 .Sq \&Em a :
173 .Bd -literal -offset indent
174 \&.Em "Em a"
175 .Ed
176 .\" PARAGRAPH------------
177 .Pp
178 In free-form mode, quotes are regarded as opaque text.
179 .\" SECTION---------------------------------------------
180 .Sh MANUAL STRUCTURE
181 Each
182 .Nm
183 document must begin with a document prologue, containing, in order,
184 .Sq \&Dd ,
185 .Sq \&Dt ,
186 and
187 .Sq \&Os ,
188 then the NAME section containing at least one
189 .Sq \&Nm
190 followed by
191 .Sq \&Nd :
192 .Bd -literal -offset indent
193 \&.Dd $\&Mdocdate$
194 \&.Dt mdoc 7
195 \&.Os
196 \&.Sh NAME
197 \&.Nm mdoc
198 \&.Nd mdoc language reference
199 .Ed
200 .\" PARAGRAPH------------
201 .Pp
202 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
203 but non-compulsory.
204 .\" SECTION---------------------------------------------
205 .Sh MACRO SYNTAX
206 Every line beginning with the control character
207 .Sq \.
208 is processed for macros, two- or three-character sequences.
209 .\" PARAGRAPH------------
210 .Pp
211 The syntax of a macro depends on its classification. In this section,
212 .Sq \-arg
213 refers to macro arguments, which may be followed by zero or more
214 .Sq parm
215 parameters;
216 .Sq \&Yo
217 opens the scope of a macro; and if specified,
218 .Sq \&Yc
219 closes it out.
220 .\" PARAGRAPH------------
221 .Pp
222 The
223 .Em Callable
224 column indicates that the macro may be called subsequent to the initial
225 line-macro. The
226 .Em Parsable
227 column indicates whether the macro may be followed by further
228 (ostensibly callable) macros. The
229 .Em Scope
230 column, if applicable, describes closure rules.
231 .\" SUB-SECTION----------------------
232 .Ss Block full-explicit
233 Multi-line scope closed by an explicit closing macro. All macros
234 contains bodies; only
235 .Pq Sq \&Bf
236 contains a head.
237 .Bd -literal -offset indent
238 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
239 \(lBbody...\(rB
240 \&.Yc
241 .Ed
242 .\" PARAGRAPH------------
243 .Pp
244 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
245 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
246 .It \&Bd Ta \&No Ta \&No Ta closed by \&Ed
247 .It \&Bf Ta \&No Ta \&No Ta closed by \&Ef
248 .It \&Bk Ta \&No Ta \&No Ta closed by \&Ek
249 .It \&Bl Ta \&No Ta \&No Ta closed by \&El
250 .It \&Ed Ta \&No Ta \&No Ta opened by \&Bd
251 .It \&Ef Ta \&No Ta \&No Ta opened by \&Bf
252 .It \&Ek Ta \&No Ta \&No Ta opened by \&Bk
253 .It \&El Ta \&No Ta \&No Ta opened by \&Bl
254 .El
255 .\" SUB-SECTION----------------------
256 .Ss Block full-implicit
257 Multi-line scope closed by end-of-file or implicitly by another macro.
258 All macros have bodies; some
259 .Po
260 .Sq \&It \-bullet ,
261 .Sq \-hyphen ,
262 .Sq \-dash ,
263 .Sq \-enum ,
264 .Sq \-item
265 .Pc
266 don't have heads, while
267 .Sq \&It \-column
268 may have multiple heads.
269 .Bd -literal -offset indent
270 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
271 \(lBbody...\(rB
272 .Ed
273 .\" PARAGRAPH------------
274 .Pp
275 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
276 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
277 .It \&It Ta \&No Ta Yes Ta closed by \&It, \&El
278 .It \&Nd Ta \&No Ta \&No Ta closed by \&Sh
279 .It \&Sh Ta \&No Ta \&No Ta closed by \&Sh
280 .It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss
281 .El
282 .\" SUB-SECTION----------------------
283 .Ss Block partial-explicit
284 Like block full-explicit, but also with single-line scope. Each
285 has at least a body and, in limited circumstances, a head
286 .Pq So \&Fo Sc , So \&Eo Sc
287 and/or tail
288 .Pq So \&Ec Sc .
289 .Bd -literal -offset indent
290 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
291 \(lBbody...\(rB
292 \&.Yc \(lBtail...\(rB
293
294 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
295 \(lBbody...\(rB \&Yc \(lBtail...\(rB
296 .Ed
297 .\" PARAGRAPH------------
298 .Pp
299 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
300 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
301 .It \&Ac Ta Yes Ta Yes Ta opened by \&Ao
302 .It \&Ao Ta Yes Ta Yes Ta closed by \&Ac
303 .It \&Bc Ta Yes Ta Yes Ta closed by \&Bo
304 .It \&Bo Ta Yes Ta Yes Ta opened by \&Bc
305 .It \&Brc Ta Yes Ta Yes Ta opened by \&Bro
306 .It \&Bro Ta Yes Ta Yes Ta closed by \&Brc
307 .It \&Dc Ta Yes Ta Yes Ta opened by \&Do
308 .It \&Do Ta Yes Ta Yes Ta closed by \&Dc
309 .It \&Ec Ta Yes Ta Yes Ta opened by \&Eo
310 .It \&Eo Ta Yes Ta Yes Ta closed by \&Ec
311 .It \&Fc Ta Yes Ta Yes Ta opened by \&Fo
312 .It \&Fo Ta \&No Ta \&No Ta closed by \&Fc
313 .It \&Oc Ta Yes Ta Yes Ta closed by \&Oo
314 .It \&Oo Ta Yes Ta Yes Ta opened by \&Oc
315 .It \&Pc Ta Yes Ta Yes Ta closed by \&Po
316 .It \&Po Ta Yes Ta Yes Ta opened by \&Pc
317 .It \&Qc Ta Yes Ta Yes Ta opened by \&Oo
318 .It \&Qo Ta Yes Ta Yes Ta closed by \&Oc
319 .It \&Re Ta \&No Ta \&No Ta opened by \&Rs
320 .It \&Rs Ta \&No Ta \&No Ta closed by \&Re
321 .It \&Sc Ta Yes Ta Yes Ta opened by \&So
322 .It \&So Ta Yes Ta Yes Ta closed by \&Sc
323 .It \&Xc Ta Yes Ta Yes Ta opened by \&Xo
324 .It \&Xo Ta Yes Ta Yes Ta closed by \&Xc
325 .El
326 .\" SUB-SECTION----------------------
327 .Ss Block partial-implicit
328 Like block full-implicit, but with single-line scope closed by
329 .Sx Reserved Characters
330 or end of line.
331 .Bd -literal -offset indent
332 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
333 .Ed
334 .\" PARAGRAPH------------
335 .Pp
336 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
337 .It Em Macro Ta Em Callable Ta Em Parsable
338 .It \&Aq Ta Yes Ta Yes
339 .It \&Bq Ta Yes Ta Yes
340 .It \&Brq Ta Yes Ta Yes
341 .It \&D1 Ta \&No Ta \&Yes
342 .It \&Dl Ta \&No Ta Yes
343 .It \&Dq Ta Yes Ta Yes
344 .It \&Op Ta Yes Ta Yes
345 .It \&Pq Ta Yes Ta Yes
346 .It \&Ql Ta Yes Ta Yes
347 .It \&Qq Ta Yes Ta Yes
348 .It \&Sq Ta Yes Ta Yes
349 .El
350 .\" SUB-SECTION----------------------
351 .Ss In-line
352 Closed by
353 .Sx Reserved Characters ,
354 end of line, fixed argument lengths, and/or subsequent macros. In-line
355 macros have only text children. If a number (or inequality) of
356 arguments is
357 .Pq n ,
358 then the macro accepts an arbitrary number of arguments.
359 .Bd -literal -offset indent
360 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
361
362 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
363
364 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
365 .Ed
366 .\" PARAGRAPH------------
367 .Pp
368 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
369 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
370 .It \&%A Ta \&No Ta \&No Ta >0
371 .It \&%B Ta \&No Ta \&No Ta >0
372 .It \&%C Ta \&No Ta \&No Ta >0
373 .It \&%D Ta \&No Ta \&No Ta >0
374 .It \&%I Ta \&No Ta \&No Ta >0
375 .It \&%J Ta \&No Ta \&No Ta >0
376 .It \&%N Ta \&No Ta \&No Ta >0
377 .It \&%O Ta \&No Ta \&No Ta >0
378 .It \&%P Ta \&No Ta \&No Ta >0
379 .It \&%R Ta \&No Ta \&No Ta >0
380 .It \&%T Ta \&No Ta \&No Ta >0
381 .It \&%V Ta \&No Ta \&No Ta >0
382 .It \&Ad Ta Yes Ta Yes Ta n
383 .It \&An Ta Yes Ta Yes Ta n
384 .It \&Ap Ta Yes Ta Yes Ta 0
385 .It \&Ar Ta Yes Ta Yes Ta n
386 .It \&At Ta Yes Ta Yes Ta 1
387 .It \&Bsx Ta Yes Ta Yes Ta n
388 .It \&Bt Ta \&No Ta \&No Ta 0
389 .It \&Bx Ta Yes Ta Yes Ta n
390 .It \&Cd Ta Yes Ta Yes Ta >0
391 .It \&Cm Ta Yes Ta Yes Ta n
392 .It \&Db Ta \&No Ta \&No Ta 1
393 .It \&Dd Ta \&No Ta \&No Ta >0
394 .It \&Dt Ta \&No Ta \&No Ta n
395 .It \&Dv Ta Yes Ta Yes Ta n
396 .It \&Dx Ta Yes Ta Yes Ta n
397 .It \&Em Ta Yes Ta Yes Ta >0
398 .It \&En Ta \&No Ta \&No Ta 0
399 .It \&Er Ta Yes Ta Yes Ta >0
400 .It \&Es Ta \&No Ta \&No Ta 0
401 .It \&Ev Ta Yes Ta Yes Ta n
402 .It \&Ex Ta \&No Ta \&No Ta 0
403 .It \&Fa Ta Yes Ta Yes Ta n
404 .It \&Fd Ta \&No Ta \&No Ta >0
405 .It \&Fl Ta Yes Ta Yes Ta n
406 .It \&Fn Ta Yes Ta Yes Ta >0
407 .It \&Fr Ta \&No Ta \&No Ta n
408 .It \&Ft Ta Yes Ta Yes Ta n
409 .It \&Fx Ta Yes Ta Yes Ta n
410 .It \&Hf Ta \&No Ta \&No Ta n
411 .It \&Ic Ta Yes Ta Yes Ta >0
412 .It \&In Ta \&No Ta \&No Ta n
413 .It \&Lb Ta \&No Ta \&No Ta 1
414 .It \&Li Ta Yes Ta Yes Ta n
415 .It \&Lk Ta Yes Ta Yes Ta n
416 .It \&Lp Ta \&No Ta \&No Ta 0
417 .It \&Ms Ta Yes Ta Yes Ta >0
418 .It \&Mt Ta Yes Ta Yes Ta >0
419 .It \&Nm Ta Yes Ta Yes Ta n
420 .It \&No Ta Yes Ta Yes Ta 0
421 .It \&Ns Ta Yes Ta Yes Ta 0
422 .It \&Nx Ta Yes Ta Yes Ta n
423 .It \&Os Ta \&No Ta \&No Ta n
424 .It \&Ot Ta \&No Ta \&No Ta n
425 .It \&Ox Ta Yes Ta Yes Ta n
426 .It \&Pa Ta Yes Ta Yes Ta n
427 .It \&Pf Ta \&No Ta Yes Ta 1
428 .It \&Pp Ta \&No Ta \&No Ta 0
429 .It \&Rv Ta \&No Ta \&No Ta 0
430 .It \&Sm Ta \&No Ta \&No Ta 1
431 .It \&St Ta \&No Ta Yes Ta 1
432 .It \&Sx Ta Yes Ta Yes Ta >0
433 .It \&Sy Ta Yes Ta Yes Ta >0
434 .It \&Tn Ta Yes Ta Yes Ta >0
435 .It \&Ud Ta \&No Ta \&No Ta 0
436 .It \&Ux Ta Yes Ta Yes Ta n
437 .It \&Va Ta Yes Ta Yes Ta n
438 .It \&Vt Ta Yes Ta Yes Ta >0
439 .It \&Xr Ta Yes Ta Yes Ta >0, <3
440 .It \&br Ta \&No Ta \&No Ta 0
441 .It \&sp Ta \&No Ta \&No Ta 1
442 .El
443 .\" SECTION---------------------------------------------
444 .Sh COMPATIBILITY
445 This section documents compatibility with other roff implementations, at
446 this time limited to
447 .Xr groff 1 .
448 The term
449 .Qq historic groff
450 refers to those versions before the
451 .Pa doc.tmac
452 file re-write
453 .Pq somewhere between 1.15 and 1.19 .
454 .\" PARAGRAPH------------
455 .Pp
456 .Bl -dash -compact
457 .\" LIST-ITEM
458 .It
459 In quoted literals, groff allowed pair-wise double-quotes to produce a
460 standalone double-quote in formatted output. This idiosyncratic
461 behaviour is no longer applicable.
462 .\" LIST-ITEM
463 .It
464 The
465 .Sq \&sp
466 macro does not accept negative numbers.
467 .\" LIST-ITEM
468 .It
469 Some character sequences in groff are not handled depending on escape
470 style, e.g.,
471 .Sq \e(ba
472 and
473 .Sq \e*(Ba
474 may not be interchanged. This is no longer the case: all character
475 sequences resolve to the same symbol, regardless the escape style.
476 .\" LIST-ITEM
477 .It
478 Blocks of whitespace are stripped from both macro and free-form text
479 lines (except when in literal mode), while groff would retain whitespace
480 in free-form text lines.
481 .\" LIST-ITEM
482 .It
483 Historic groff has many un-callable macros. Most of these (excluding
484 some block-level macros) are now callable, conforming to the
485 non-historic groff version.
486 .\" LIST-ITEM
487 .It
488 The vertical bar
489 .Sq \(ba
490 made historic groff
491 .Qq go orbital
492 but is a proper delimiter in this implementation.
493 .\" LIST-ITEM
494 .It
495 .Sq \&It \-nested
496 is assumed for all lists (it wasn't in historic groff): any list may be
497 nested and
498 .Sq \-enum
499 lists will restart the sequence only for the sub-list.
500 .\" LIST-ITEM
501 .It
502 .Sq \&It \-column
503 syntax where column widths may be preceded by other arguments (instead
504 of proceeded) is not supported.
505 .\" LIST-ITEM
506 .It
507 The
508 .Sq \&At
509 macro only accepts a single parameter.
510 .\" LIST-ITEM
511 .It
512 Some manuals use
513 .Sq \&Li
514 incorrectly by following it with a reserved character and expecting the
515 delimiter to render. This is not supported.
516 .\" LIST-ITEM
517 .It
518 If an special-character control character is escaped
519 .Sq \e\e ,
520 it will obviously not render the subsequent sequence. Even newer
521 versions of groff seem to dither on this.
522 .\" LIST-ITEM
523 .It
524 In groff, the
525 .Sq \&Fo
526 macro only produces the first parameter. This is no longer the case.
527 .El
528 .\" SECTION---------------------------------------------
529 .Sh SEE ALSO
530 .Xr mandoc 1 ,
531 .Xr mandoc_char 7
532 .\" SECTION---------------------------------------------
533 .Sh AUTHORS
534 The
535 .Nm
536 reference was written by
537 .An Kristaps Dzonsons Aq kristaps@kth.se .
538 .\" SECTION---------------------------------------------
539 .Sh CAVEATS
540 There are many ambiguous parts of mdoc.
541 .\" PARAGRAPH------------
542 .Pp
543 .Bl -dash -compact
544 .\" LIST-ITEM
545 .It
546 .Sq \&Fa
547 should be
548 .Sq \&Va
549 as function arguments are variables.
550 .\" LIST-ITEM
551 .It
552 .Sq \&Ft
553 should be
554 .Sq \&Vt
555 as function return types are still types. Furthermore, the
556 .Sq \&Ft
557 should be removed and
558 .Sq \&Fo ,
559 which ostensibly follows it, should follow the same convention as
560 .Sq \&Va .
561 .\" LIST-ITEM
562 .It
563 .Sq \&Va
564 should formalise that only one or two arguments are acceptable: a
565 variable name and optional, preceding type.
566 .\" LIST-ITEM
567 .It
568 .Sq \&Fd
569 is ambiguous. It's commonly used to indicate an include file in the
570 synopsis section.
571 .Sq \&In
572 should be used, instead.
573 .\" LIST-ITEM
574 .It
575 Only the
576 .Sq \-literal
577 argument to
578 .Sq \&Bd
579 makes sense. The remaining ones should be removed.
580 .\" LIST-ITEM
581 .It
582 The
583 .Sq \&Xo
584 and
585 .Sq \&Xc
586 macros should be deprecated.
587 .\" LIST-ITEM
588 .It
589 The
590 .Sq \&Dt
591 macro lacks clarity. It should be absolutely clear which title will
592 render when formatting the manual page.
593 .\" LIST-ITEM
594 .It
595 A
596 .Sq \&Lx
597 should be provided for Linux (\(`a la
598 .Sq \&Ox ,
599 .Sq \&Nx
600 etc.).
601 .\" LIST-ITEM
602 .It
603 There's no way to refer to references in
604 .Sq \&Rs/Re
605 blocks.
606 .\" LIST-ITEM
607 .It
608 The \-split and \-nosplit arguments to
609 .Sq \&An
610 are inane.
611 .El