]> git.cameronkatri.com Git - mandoc.git/blob - mdoc.7
a7df1cb98accd611ed095d11af306decf687d6fc
[mandoc.git] / mdoc.7
1 .\" $Id: mdoc.7,v 1.41 2009/07/12 19:34:51 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 12 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 the syntax and
32 structure of the
33 .Nm
34 language. Our reference implementation is
35 .Xr mandoc 1 .
36 The
37 .Sx COMPATIBILITY
38 section describes compatibility with
39 .Xr groff 1 .
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 indent
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.
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.
90 .\" SUB-SECTION
91 .Ss Reserved Characters
92 Within a macro line, the following characters are reserved:
93 .Bl -tag -width Ds -offset indent -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
114 .It \&|
115 .Pq vertical bar
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.
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 .
151 .\" SECTION
152 .Sh STRUCTURE
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
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.
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 indent
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 indent -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 indent -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 indent
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 indent
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 indent
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 indent
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 indent
304 \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
305
306 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
307 .Ed
308 .\" SECTION
309 .Sh MACROS
310 This section contains a complete list of all
311 .Nm
312 macros, arranged by classification. A
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
331 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "Closing"
332 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
333 .It \&.Nd Ta \&No Ta \&No Ta \&.Sh
334 .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
335 .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
336 .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
337 .El
338 .\" SUB-SECTION
339 .Ss Block full-explicit
340 None of these macros are callable or parsed. The last column indicates
341 the explicit scope rules. All contains bodies, some may contain heads
342 .Pq So \&Bf Sc .
343 .Pp
344 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
345 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
346 .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
347 .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
348 .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
349 .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
350 .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
351 .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
352 .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
353 .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
354 .El
355 .\" SUB-SECTION
356 .Ss Block partial-implicit
357 All of these are callable and parsed for further macros. Their scopes
358 close at the invocation's end-of-line.
359 .Pp
360 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
361 .It Em Macro Ta Em Callable Ta Em Parsable
362 .It \&.Aq Ta Yes Ta Yes
363 .It \&.Op Ta Yes Ta Yes
364 .It \&.Bq Ta Yes Ta Yes
365 .It \&.Dq Ta Yes Ta Yes
366 .It \&.Pq Ta Yes Ta Yes
367 .It \&.Qq Ta Yes Ta Yes
368 .It \&.Sq Ta Yes Ta Yes
369 .It \&.Brq Ta Yes Ta Yes
370 .It \&.D1 Ta \&No Ta \&Yes
371 .It \&.Dl Ta \&No Ta Yes
372 .It \&.Ql Ta Yes Ta Yes
373 .El
374 .\" PARAGRAPH
375 .Pp
376 The
377 .Sq \&.Op
378 may be broken by
379 .Sq \&.Oc
380 as in the following example:
381 .Bd -literal -offset indent
382 \&.Oo
383 \&.Op Fl a Oc
384 .Ed
385 .Pp
386 In the above example, the scope of
387 .Sq \&.Op
388 is technically broken by
389 .Sq \&.Oc ,
390 however, due to the overwhelming existence of this sequence, it's
391 allowed.
392 .\" SUB-SECTION
393 .Ss Block partial-explicit
394 Each of these contains at least a body and, in limited circumstances, a
395 head
396 .Pq So \&.Fo Sc , So \&.Eo Sc
397 and/or tail
398 .Pq So \&.Ec Sc .
399 .Pp
400 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
401 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
402 .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
403 .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
404 .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
405 .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
406 .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
407 .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
408 .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
409 .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
410 .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
411 .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
412 .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
413 .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
414 .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
415 .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
416 .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
417 .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
418 .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
419 .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
420 .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
421 .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
422 .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
423 .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
424 .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
425 .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
426 .El
427 .\" SUB-SECTION
428 .Ss In-line
429 In-line macros have only text children. If a number (or inequality) of
430 arguments is
431 .Pq n ,
432 then the macro accepts an arbitrary number of arguments.
433 .Pp
434 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
435 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
436 .It \&.Dd Ta \&No Ta \&No Ta >0
437 .It \&.Dt Ta \&No Ta \&No Ta n
438 .It \&.Os Ta \&No Ta \&No Ta n
439 .It \&.Pp Ta \&No Ta \&No Ta 0
440 .It \&.Ad Ta Yes Ta Yes Ta n
441 .It \&.An Ta Yes Ta Yes Ta n
442 .It \&.Ar Ta Yes Ta Yes Ta n
443 .It \&.Cd Ta Yes Ta \&No Ta >0
444 .It \&.Cm Ta Yes Ta Yes Ta n
445 .It \&.Dv Ta Yes Ta Yes Ta n
446 .It \&.Er Ta Yes Ta Yes Ta >0
447 .It \&.Ev Ta Yes Ta Yes Ta n
448 .It \&.Ex Ta \&No Ta \&No Ta 0
449 .It \&.Fa Ta Yes Ta Yes Ta n
450 .It \&.Fd Ta \&No Ta \&No Ta >0
451 .It \&.Fl Ta Yes Ta Yes Ta n
452 .It \&.Fn Ta Yes Ta Yes Ta >0
453 .It \&.Ft Ta Yes Ta Yes Ta n
454 .It \&.Ic Ta Yes Ta Yes Ta >0
455 .It \&.In Ta \&No Ta \&No Ta n
456 .It \&.Li Ta Yes Ta Yes 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
483 .It \&.Ms Ta Yes Ta Yes Ta >0
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
502 .It \&.Lk Ta Yes Ta Yes Ta n
503 .It \&.Mt Ta Yes Ta Yes Ta >0
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
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 .
526 .Pp
527 .Bl -dash -compact
528 .\" LIST-ITEM
529 .It
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
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
550 .Sq \(ba
551 made historic groff
552 .Qq go orbital
553 but is a proper delimiter in this implementation.
554 .\" LIST-ITEM
555 .It
556 .Sq \&.It \-nested
557 is assumed for all lists (it wasn't in historic groff): any list may be
558 nested and
559 .Sq \-enum
560 lists will restart the sequence only for the sub-list.
561 .\" LIST-ITEM
562 .It
563 .Sq \&.It \-column
564 syntax where column widths may be preceded by other arguments (instead
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
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.
583 .\" LIST-ITEM
584 .It
585 In groff, the
586 .Sq \&.Fo
587 macro only produces the first parameter. This is no longer the case.
588 .El
589 .\" SECTION
590 .Sh SEE ALSO
591 .Xr mandoc 1 ,
592 .Xr mandoc_char 7
593 .\" SECTION
594 .Sh AUTHORS
595 The
596 .Nm
597 utility was written by
598 .An Kristaps Dzonsons Aq kristaps@kth.se .
599 .\" SECTION
600 .Sh CAVEATS
601 There are many ambiguous parts of mdoc.
602 .Pp
603 .Bl -dash -compact
604 .\" LIST-ITEM
605 .It
606 .Sq \&.Fa
607 should be
608 .Sq \&.Va
609 as function arguments are variables.
610 .\" LIST-ITEM
611 .It
612 .Sq \&.Ft
613 should be
614 .Sq \&.Vt
615 as function return types are still types. Furthermore, the
616 .Sq \&.Ft
617 should be removed and
618 .Sq \&.Fo ,
619 which ostensibly follows it, should follow the same convention as
620 .Sq \&.Va .
621 .\" LIST-ITEM
622 .It
623 .Sq \&.Va
624 should formalise that only one or two arguments are acceptable: a
625 variable name and optional, preceding type.
626 .\" LIST-ITEM
627 .It
628 .Sq \&.Fd
629 is ambiguous. It's commonly used to indicate an include file in the
630 synopsis section.
631 .Sq \&.In
632 should be used, instead.
633 .\" LIST-ITEM
634 .It
635 Only the
636 .Sq \-literal
637 argument to
638 .Sq \&.Bd
639 makes sense. The remaining ones should be removed.
640 .\" LIST-ITEM
641 .It
642 The
643 .Sq \&.Xo
644 and
645 .Sq \&.Xc
646 macros should be deprecated.
647 .\" LIST-ITEM
648 .It
649 The
650 .Sq \&.Dt
651 macro lacks clarity. It should be absolutely clear which title will
652 render when formatting the manual page.
653 .\" LIST-ITEM
654 .It
655 A
656 .Sq \&.Lx
657 should be provided for Linux (\(`a la
658 .Sq \&.Ox ,
659 .Sq \&.Nx
660 etc.).
661 .\" LIST-ITEM
662 .It
663 There's no way to refer to references in
664 .Sq \&.Rs/.Re
665 blocks.
666 .\" LIST-ITEM
667 .It
668 The \-split and \-nosplit arguments to
669 .Sq \&.An
670 are inane.
671 .\" LIST-ITEM
672 .It
673 The end-of-line whitespace warnings are superfluous holdovers from
674 historic groff.
675 .El