1 MANDOC(1) User Commands MANDOC(1)
2
3 NAME
4 mandoc - format manual pages
5
6 SYNOPSIS
7 mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
8 [-T output] [-W level] [file ...]
9
10 DESCRIPTION
11 The mandoc utility formats manual pages for display.
12
13 By default, mandoc reads mdoc(5) or man(5) text from stdin and produces
14 -T locale output.
15
16 The options are as follows:
17
18 -a If the standard output is a terminal device and -c is not
19 specified, use more(1) to paginate the output, just like man(1)
20 would.
21
22 -c Copy the formatted manual pages to the standard output without
23 using more(1) to paginate them. This is the default. It can be
24 specified to override -a.
25
26 -I os=name
27 Override the default operating system name for the mdoc(5) Os and
28 for the man(5) TH macro.
29
30 -K encoding
31 Specify the input encoding. The supported encoding arguments are
32 us-ascii, iso-8859-1, and utf-8. If not specified, autodetection
33 uses the first match in the following list:
34
35 1. If the first three bytes of the input file are the UTF-8
36 byte order mark (BOM, 0xefbbbf), input is interpreted as
37 utf-8.
38
39 2. If the first or second line of the input file matches the
40 emacs mode line format
41
42 .\" -*- [...;] coding: encoding; -*-
43
44 then input is interpreted according to encoding.
45
46 3. If the first non-ASCII byte in the file introduces a valid
47 UTF-8 sequence, input is interpreted as utf-8.
48
49 4. Otherwise, input is interpreted as iso-8859-1.
50
51 -mdoc | -man
52 With -mdoc, all input files are interpreted as mdoc(5). With
53 -man, all input files are interpreted as man(5). By default, the
54 input language is automatically detected for each file: if the
55 first macro is Dd or Dt, the mdoc(5) parser is used; otherwise,
56 the man(5) parser is used. With other arguments, -m is silently
57 ignored.
58
59 -O options
60 Comma-separated output options. See the descriptions of the
61 individual output formats for supported options.
62
63 -T output
64 Select the output format. Supported values for the output
65 argument are ascii, html, the default of locale, man, markdown,
66 pdf, ps, tree, and utf8.
67
68 The special -T lint mode only parses the input and produces no
69 output. It implies -W all and redirects parser messages, which
70 usually appear on standard error output, to standard output.
71
72 -W level
73 Specify the minimum message level to be reported on the standard
74 error output and to affect the exit status. The level can be
75 base, style, warning, error, or unsupp. The base level
76 automatically derives the operating system from the contents of
77 the Os macro, from the -Ios command line option, or from the
78 uname(2) return value. The levels openbsd and netbsd are
79 variants of base that bypass autodetection and request validation
80 of base system conventions for a particular operating system.
81 The level all is an alias for base. By default, mandoc is
82 silent. See EXIT STATUS and DIAGNOSTICS for details.
83
84 The special option -W stop tells mandoc to exit after parsing a
85 file that causes warnings or errors of at least the requested
86 level. No formatted output will be produced from that file. If
87 both a level and stop are requested, they can be joined with a
88 comma, for example -W error,stop.
89
90 file Read from the given input file. If multiple files are specified,
91 they are processed in the given order. If unspecified, mandoc
92 reads from standard input.
93
94 ASCII Output
95 Use -T ascii to force text output in 7-bit ASCII character encoding
96 documented in the ascii(5) manual page, ignoring the locale(1) set in the
97 environment.
98
99 Font styles are applied by using back-spaced encoding such that an
100 underlined character `c' is rendered as `_\[bs]c', where `\[bs]' is the
101 back-space character number 8. Emboldened characters are rendered as
102 `c\[bs]c'.
103
104 The special characters documented in mandoc_char(5) are rendered best-
105 effort in an ASCII equivalent.
106
107 The following -O arguments are accepted:
108
109 indent=indent
110 The left margin for normal text is set to indent blank characters
111 instead of the default of five for mdoc(5) and seven for man(5).
112 Increasing this is not recommended; it may result in degraded
113 formatting, for example overfull lines or ugly line breaks. When
114 output is to a pager on a terminal that is less than 66 columns
115 wide, the default is reduced to three columns.
116
117 mdoc Format man(5) input files in mdoc(5) output style. Specifically,
118 this suppresses the two additional blank lines near the top and
119 the bottom of each page, and it implies -O indent=5. One useful
120 application is for checking that -T man output formats in the
121 same way as the mdoc(5) source it was generated from.
122
123 width=width
124 The output width is set to width instead of the default of 78.
125 When output is to a pager on a terminal that is less than 79
126 columns wide, the default is reduced to one less than the
127 terminal width. In any case, lines that are output in literal
128 mode are never wrapped and may exceed the output width.
129
130 HTML Output
131 Output produced by -T html conforms to HTML5 using optional self-closing
132 tags. Default styles use only CSS1. Equations rendered from eqn(5)
133 blocks use MathML.
134
135 The mandoc.css file documents style-sheet classes available for
136 customising output. If a style-sheet is not specified with -O style, -T
137 html defaults to simple output (via an embedded style-sheet) readable in
138 any graphical or text-based web browser.
139
140 Non-ASCII characters are rendered as hexadecimal Unicode character
141 references.
142
143 The following -O arguments are accepted:
144
145 fragment
146 Omit the <!DOCTYPE> declaration and the <html>, <head>, and
147 <body> elements and only emit the subtree below the <body>
148 element. The style argument will be ignored. This is useful
149 when embedding manual content within existing documents.
150
151 includes=fmt
152 The string fmt, for example, ../src/%I.html, is used as a
153 template for linked header files (usually via the In macro).
154 Instances of `%I' are replaced with the include filename. The
155 default is not to present a hyperlink.
156
157 man=fmt
158 The string fmt, for example, ../html%S/%N.%S.html, is used as a
159 template for linked manuals (usually via the Xr macro).
160 Instances of `%N' and `%S' are replaced with the linked manual's
161 name and section, respectively. If no section is included,
162 section 1 is assumed. The default is not to present a hyperlink.
163
164 style=style.css
165 The file style.css is used for an external style-sheet. This
166 must be a valid absolute or relative URI.
167
168 Locale Output
169 By default, mandoc automatically selects UTF-8 or ASCII output according
170 to the current locale(1). If any of the environment variables LC_ALL,
171 LC_CTYPE, or LANG are set and the first one that is set selects the UTF-8
172 character encoding, it produces UTF-8 Output; otherwise, it falls back to
173 ASCII Output. This output mode can also be selected explicitly with -T
174 locale.
175
176 Man Output
177 Use -T man to translate mdoc(5) input into man(5) output format. This is
178 useful for distributing manual sources to legacy systems lacking mdoc(5)
179 formatters.
180
181 If the input format of a file is man(5), the input is copied to the
182 output, expanding any mandoc_roff(5) so requests. The parser is also
183 run, and as usual, the -W level controls which DIAGNOSTICS are displayed
184 before copying the input to the output.
185
186 Markdown Output
187 Use -T markdown to translate mdoc(5) input to the markdown format
188 conforming to John Gruber's 2004 specification:
189 http://daringfireball.net/projects/markdown/syntax.text. The output also
190 almost conforms to the CommonMark: http://commonmark.org/ specification.
191
192 The character set used for the markdown output is ASCII. Non-ASCII
193 characters are encoded as HTML entities. Since that is not possible in
194 literal font contexts, because these are rendered as code spans and code
195 blocks in the markdown output, non-ASCII characters are transliterated to
196 ASCII approximations in these contexts.
197
198 Markdown is a very weak markup language, so all semantic markup is lost,
199 and even part of the presentational markup may be lost. Do not use this
200 as an intermediate step in converting to HTML; instead, use -T html
201 directly.
202
203 The man(5), tbl(5), and eqn(5) input languages are not supported by -T
204 markdown output mode.
205
206 PDF Output
207 PDF-1.1 output may be generated by -T pdf. See PostScript Output for -O
208 arguments and defaults.
209
210 PostScript Output
211 PostScript "Adobe-3.0" Level-2 pages may be generated by -T ps. Output
212 pages default to letter sized and are rendered in the Times font family,
213 11-point. Margins are calculated as 1/9 the page length and width.
214 Line-height is 1.4m.
215
216 Special characters are rendered as in ASCII Output.
217
218 The following -O arguments are accepted:
219
220 paper=name
221 The paper size name may be one of a3, a4, a5, legal, or letter.
222 You may also manually specify dimensions as NNxNN, width by
223 height in millimetres. If an unknown value is encountered,
224 letter is used.
225
226 UTF-8 Output
227 Use -T utf8 to force text output in UTF-8 multi-byte character encoding,
228 ignoring the locale(1) settings in the environment. See ASCII Output
229 regarding font styles and -O arguments.
230
231 On operating systems lacking locale or wide character support, and on
232 those where the internal character representation is not UCS-4, mandoc
233 always falls back to ASCII Output.
234
235 Syntax tree output
236 Use -T tree to show a human readable representation of the syntax tree.
237 It is useful for debugging the source code of manual pages. The exact
238 format is subject to change, so don't write parsers for it.
239
240 The first paragraph shows meta data found in the mdoc(5) prologue, on the
241 man(5) TH line, or the fallbacks used.
242
243 In the tree dump, each output line shows one syntax tree node. Child
244 nodes are indented with respect to their parent node. The columns are:
245
246 1. For macro nodes, the macro name; for text and tbl(5) nodes, the
247 content. There is a special format for eqn(5) nodes.
248 2. Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
249 3. Flags:
250 - An opening parenthesis if the node is an opening delimiter.
251 - An asterisk if the node starts a new input line.
252 - The input line number (starting at one).
253 - A colon.
254 - The input column number (starting at one).
255 - A closing parenthesis if the node is a closing delimiter.
256 - A full stop if the node ends a sentence.
257 - BROKEN if the node is a block broken by another block.
258 - NOSRC if the node is not in the input file, but automatically
259 generated from macros.
260 - NOPRT if the node is not supposed to generate output for any
261 output format.
262
263 The following -O argument is accepted:
264
265 noval Skip validation and show the unvalidated syntax tree. This can
266 help to find out whether a given behaviour is caused by the
267 parser or by the validator. Meta data is not available in this
268 case.
269
270 ENVIRONMENT
271 LC_CTYPE The character encoding locale(1). When Locale Output is
272 selected, it decides whether to use ASCII or UTF-8
273 output format. It never affects the interpretation of
274 input files.
275
276 EXIT STATUS
277 The mandoc utility exits with one of the following values, controlled by
278 the message level associated with the -W option:
279
280 0 No base system convention violations, style suggestions,
281 warnings, or errors occurred, or those that did were ignored
282 because they were lower than the requested level.
283 1 At least one base system convention violation or style suggestion
284 occurred, but no warning or error, and -W base or -W style was
285 specified.
286 2 At least one warning occurred, but no error, and -W warning or a
287 lower level was requested.
288 3 At least one parsing error occurred, but no unsupported feature
289 was encountered, and -W error or a lower level was requested.
290 4 At least one unsupported feature was encountered, and -W unsupp
291 or a lower level was requested.
292 5 Invalid command line arguments were specified. No input files
293 have been read.
294 6 An operating system error occurred, for example exhaustion of
295 memory, file descriptors, or process table entries. Such errors
296 cause mandoc to exit at once, possibly in the middle of parsing
297 or formatting a file.
298
299 Note that selecting -T lint output mode implies -W all.
300
301 EXAMPLES
302 To page manuals to the terminal:
303
304 $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
305
306 To produce HTML manuals with mandoc.css as the style-sheet:
307
308 $ mandoc -T html -Ostyle=mandoc.css mdoc.5 > mdoc.5.html
309
310 To check over a large set of manuals:
311
312 $ mandoc -T lint `find /usr/src -name \*\.[1-9]`
313
314 To produce a series of PostScript manuals for A4 paper:
315
316 $ mandoc -T ps -O paper=a4 mdoc.5 man.5 > manuals.ps
317
318 Convert a modern mdoc(5) manual to the older man(5) format, for use on
319 systems lacking an mdoc(5) parser:
320
321 $ mandoc -T man foo.mdoc > foo.man
322
323 DIAGNOSTICS
324 Messages displayed by mandoc follow this format:
325
326 mandoc: file:line:column: level: message: macro args (os)
327
328 Line and column numbers start at 1. Both are omitted for messages
329 referring to an input file as a whole. Macro names and arguments are
330 omitted where meaningless. The os operating system specifier is omitted
331 for messages that are relevant for all operating systems. Fatal messages
332 about invalid command line arguments or operating system errors, for
333 example when memory is exhausted, may also omit the file and level
334 fields.
335
336 Message levels have the following meanings:
337
338 unsupp An input file uses unsupported low-level mandoc_roff(5)
339 features. The output may be incomplete and/or misformatted, so
340 using GNU troff instead of mandoc to process the file may be
341 preferable.
342
343 error Indicates a risk of information loss or severe misformatting, in
344 most cases caused by serious syntax errors.
345
346 warning Indicates a risk that the information shown or its formatting
347 may mismatch the author's intent in minor ways. Additionally,
348 syntax errors are classified at least as warnings, even if they
349 do not usually cause misformatting.
350
351 style An input file uses dubious or discouraged style. This is not a
352 complaint about the syntax, and probably neither formatting nor
353 portability are in danger. While great care is taken to avoid
354 false positives on the higher message levels, the style level
355 tries to reduce the probability that issues go unnoticed, so it
356 may occasionally issue bogus suggestions. Please use your good
357 judgement to decide whether any particular style suggestion
358 really justifies a change to the input file.
359
360 base A convention used in the base system of a specific operating
361 system is not adhered to. These are not markup mistakes, and
362 neither the quality of formatting nor portability are in danger.
363 Messages of the base level are printed with the more intuitive
364 style level tag.
365
366 Messages of the base, style, warning, error, and unsupp levels except
367 those about non-existent or unreadable input files are hidden unless
368 their level, or a lower level, is requested using a -W option or -T lint
369 output mode.
370
371 As indicated below, all base and some style checks are only performed if
372 a specific operating system name occurs in the arguments of the -W
373 command line option, of the Os macro, of the -Ios command line option,
374 or, if neither are present, in the return value of the uname(3) function.
375
376 Conventions for base system manuals
377 Mdocdate found
378 (mdoc, NetBSD) The Dd macro uses CVS Mdocdate keyword substitution, which
379 is not supported by the NetBSD base system. Consider using the
380 conventional "Month dd, yyyy" format instead.
381
382 Mdocdate missing
383 (mdoc, OpenBSD) The Dd macro does not use CVS Mdocdate keyword
384 substitution, but using it is conventionally expected in the OpenBSD base
385 system.
386
387 unknown architecture
388 (mdoc, OpenBSD, NetBSD) The third argument of the Dt macro does not match
389 any of the architectures this operating system is running on.
390
391 operating system explicitly specified
392 (mdoc, OpenBSD, NetBSD) The Os macro has an argument. In the base
393 system, it is conventionally left blank.
394
395 RCS id missing
396 (OpenBSD, NetBSD) The manual page lacks the comment line with the RCS
397 identifier generated by CVS OpenBSD or NetBSD keyword substitution as
398 conventionally used in these operating systems.
399
400 referenced manual not found
401 (mdoc) An Xr macro references a manual page that is not found in the base
402 system. The path to look for base system manuals is configurable at
403 compile time and defaults to /usr/share/man: /usr/X11R6/man.
404
405 Style suggestions
406 legacy man(7) date format
407 (mdoc) The Dd macro uses the legacy man(5) date format "yyyy-dd-mm".
408 Consider using the conventional mdoc(5) date format "Month dd, yyyy"
409 instead.
410
411 normalizing date format to: ...
412 (mdoc, man) The Dd or TH macro provides an abbreviated month name or a
413 day number with a leading zero. In the formatted output, the month name
414 is written out in full and the leading zero is omitted.
415
416 lower case character in document title
417 (mdoc, man) The title is still used as given in the Dt or TH macro.
418
419 duplicate RCS id
420 A single manual page contains two copies of the RCS identifier for the
421 same operating system. Consider deleting the later instance and moving
422 the first one up to the top of the page.
423
424 possible typo in section name
425 (mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
426 similar, but not identical to a standard section name.
427
428 unterminated quoted argument
429 (roff) Macro arguments can be enclosed in double quote characters such
430 that space characters and macro names contained in the quoted argument
431 need not be escaped. The closing quote of the last argument of a macro
432 can be omitted. However, omitting it is not recommended because it makes
433 the code harder to read.
434
435 useless macro
436 (mdoc) A Bt, Tn, or Ud macro was found. Simply delete it: it serves no
437 useful purpose.
438
439 consider using OS macro
440 (mdoc) A string was found in plain text or in a Bx macro that could be
441 represented using Ox, Nx, Fx, or Dx.
442
443 errnos out of order
444 (mdoc, NetBSD) The Er items in a Bl list are not in alphabetical order.
445
446 duplicate errno
447 (mdoc, NetBSD) A Bl list contains two consecutive It entries describing
448 the same Er number.
449
450 trailing delimiter
451 (mdoc) The last argument of an Ex, Fo, Nd, Nm, Os, Sh, Ss, St, or Sx
452 macro ends with a trailing delimiter. This is usually bad style and
453 often indicates typos. Most likely, the delimiter can be removed.
454
455 no blank before trailing delimiter
456 (mdoc) The last argument of a macro that supports trailing delimiter
457 arguments is longer than one byte and ends with a trailing delimiter.
458 Consider inserting a blank such that the delimiter becomes a separate
459 argument, thus moving it out of the scope of the macro.
460
461 fill mode already enabled, skipping
462 (man) A fi request occurs even though the document is still in fill mode,
463 or already switched back to fill mode. It has no effect.
464
465 fill mode already disabled, skipping
466 (man) An nf request occurs even though the document already switched to
467 no-fill mode and did not switch back to fill mode yet. It has no effect.
468
469 verbatim "--", maybe consider using \(em
470 (mdoc) Even though the ASCII output device renders an em-dash as "--",
471 that is not a good way to write it in an input file because it renders
472 poorly on all other output devices.
473
474 function name without markup
475 (mdoc) A word followed by an empty pair of parentheses occurs on a text
476 line. Consider using an Fn or Xr macro.
477
478 whitespace at end of input line
479 (mdoc, man, roff) Whitespace at the end of input lines is almost never
480 semantically significant -- but in the odd case where it might be, it is
481 extremely confusing when reviewing and maintaining documents.
482
483 bad comment style
484 (roff) Comment lines start with a dot, a backslash, and a double-quote
485 character. The mandoc utility treats the line as a comment line even
486 without the backslash, but leaving out the backslash might not be
487 portable.
488
489 Warnings related to the document prologue
490 missing manual title, using UNTITLED
491 (mdoc) A Dt macro has no arguments, or there is no Dt macro before the
492 first non-prologue macro.
493
494 missing manual title, using ""
495 (man) There is no TH macro, or it has no arguments.
496
497 missing manual section, using ""
498 (mdoc, man) A Dt or TH macro lacks the mandatory section argument.
499
500 unknown manual section
501 (mdoc) The section number in a Dt line is invalid, but still used.
502
503 missing date, using today's date
504 (mdoc, man) The document was parsed as mdoc(5) and it has no Dd macro, or
505 the Dd macro has no arguments or only empty arguments; or the document
506 was parsed as man(5) and it has no TH macro, or the TH macro has less
507 than three arguments or its third argument is empty.
508
509 cannot parse date, using it verbatim
510 (mdoc, man) The date given in a Dd or TH macro does not follow the
511 conventional format.
512
513 date in the future, using it anyway
514 (mdoc, man) The date given in a Dd or TH macro is more than a day ahead
515 of the current system time(3).
516
517 missing Os macro, using ""
518 (mdoc) The default or current system is not shown in this case.
519
520 late prologue macro
521 (mdoc) A Dd or Os macro occurs after some non-prologue macro, but still
522 takes effect.
523
524 prologue macros out of order
525 (mdoc) The prologue macros are not given in the conventional order Dd,
526 Dt, Os. All three macros are used even when given in another order.
527
528 Warnings regarding document structure
529 .so is fragile, better use ln(1)
530 (roff) Including files only works when the parser program runs with the
531 correct current working directory.
532
533 no document body
534 (mdoc, man) The document body contains neither text nor macros. An empty
535 document is shown, consisting only of a header and a footer line.
536
537 content before first section header
538 (mdoc, man) Some macros or text precede the first Sh or SH section
539 header. The offending macros and text are parsed and added to the top
540 level of the syntax tree, outside any section block.
541
542 first section is not NAME
543 (mdoc) The argument of the first Sh macro is not `NAME'. This may
544 confuse apropos(1) or confuse man(1) when updating the whatis(1)
545 database.
546
547 NAME section without Nm before Nd
548 (mdoc) The NAME section does not contain any Nm child macro before the
549 first Nd macro.
550
551 NAME section without description
552 (mdoc) The NAME section lacks the mandatory Nd child macro.
553
554 description not at the end of NAME
555 (mdoc) The NAME section does contain an Nd child macro, but other content
556 follows it.
557
558 bad NAME section content
559 (mdoc) The NAME section contains plain text or macros other than Nm and
560 Nd.
561
562 missing comma before name
563 (mdoc) The NAME section contains an Nm macro that is neither the first
564 one nor preceded by a comma.
565
566 missing description line, using ""
567 (mdoc) The Nd macro lacks the required argument. The title line of the
568 manual will end after the dash.
569
570 description line outside NAME section
571 (mdoc) An Nd macro appears outside the NAME section. The arguments are
572 printed anyway and the following text is used for apropos(1), but none of
573 that behaviour is portable.
574
575 sections out of conventional order
576 (mdoc) A standard section occurs after another section it usually
577 precedes. All section titles are used as given, and the order of
578 sections is not changed.
579
580 duplicate section title
581 (mdoc) The same standard section title occurs more than once.
582
583 unexpected section
584 (mdoc) A standard section header occurs in a section of the manual where
585 it normally isn't useful.
586
587 cross reference to self
588 (mdoc) An Xr macro refers to a name and section matching the section of
589 the present manual page and a name mentioned in an Nm macro in the NAME
590 or SYNOPSIS section, or in an Fn or Fo macro in the SYNOPSIS. Consider
591 using Nm or Fn instead of Xr.
592
593 unusual Xr order
594 (mdoc) In the SEE ALSO section, an Xr macro with a lower section number
595 follows one with a higher number, or two Xr macros referring to the same
596 section are out of alphabetical order.
597
598 unusual Xr punctuation
599 (mdoc) In the SEE ALSO section, punctuation between two Xr macros differs
600 from a single comma, or there is trailing punctuation after the last Xr
601 macro.
602
603 AUTHORS section without An macro
604 (mdoc) An AUTHORS sections contains no An macros, or only empty ones.
605 Probably, there are author names lacking markup.
606
607 Warnings related to macros and nesting
608 obsolete macro
609 (mdoc) See the mdoc(5) manual for replacements.
610
611 macro neither callable nor escaped
612 (mdoc) The name of a macro that is not callable appears on a macro line.
613 It is printed verbatim. If the intention is to call it, move it to its
614 own input line; otherwise, escape it by prepending `\&'.
615
616 skipping paragraph macro
617 In mdoc(5) documents, this happens
618 - at the beginning and end of sections and subsections
619 - right before non-compact lists and displays
620 - at the end of items in non-column, non-compact lists
621 - and for multiple consecutive paragraph macros.
622 In man(5) documents, it happens
623 - for empty P, PP, and LP macros
624 - for IP macros having neither head nor body arguments
625 - for br or sp right after SH or SS
626
627 moving paragraph macro out of list
628 (mdoc) A list item in a Bl list contains a trailing paragraph macro. The
629 paragraph macro is moved after the end of the list.
630
631 skipping no-space macro
632 (mdoc) An input line begins with an Ns macro, or the next argument after
633 an Ns macro is an isolated closing delimiter. The macro is ignored.
634
635 blocks badly nested
636 (mdoc) If two blocks intersect, one should completely contain the other.
637 Otherwise, rendered output is likely to look strange in any output
638 format, and rendering in SGML-based output formats is likely to be
639 outright wrong because such languages do not support badly nested blocks
640 at all. Typical examples of badly nested blocks are "Ao Bo Ac Bc" and
641 "Ao Bq Ac". In these examples, Ac breaks Bo and Bq, respectively.
642
643 nested displays are not portable
644 (mdoc) A Bd, D1, or Dl display occurs nested inside another Bd display.
645 This works with mandoc, but fails with most other implementations.
646
647 moving content out of list
648 (mdoc) A Bl list block contains text or macros before the first It macro.
649 The offending children are moved before the beginning of the list.
650
651 first macro on line
652 Inside a Bl -column list, a Ta macro occurs as the first macro on a line,
653 which is not portable.
654
655 line scope broken
656 (man) While parsing the next-line scope of the previous macro, another
657 macro is found that prematurely terminates the previous one. The
658 previous, interrupted macro is deleted from the parse tree.
659
660 Warnings related to missing arguments
661 skipping empty request
662 (roff, eqn) The macro name is missing from a macro definition request, or
663 an eqn(5) control statement or operation keyword lacks its required
664 argument.
665
666 conditional request controls empty scope
667 (roff) A conditional request is only useful if any of the following
668 follows it on the same logical input line:
669 - The `\{' keyword to open a multi-line scope.
670 - A request or macro or some text, resulting in a single-line scope.
671 - The immediate end of the logical line without any intervening
672 whitespace, resulting in next-line scope.
673 Here, a conditional request is followed by trailing whitespace only, and
674 there is no other content on its logical input line. Note that it
675 doesn't matter whether the logical input line is split across multiple
676 physical input lines using `\' line continuation characters. This is one
677 of the rare cases where trailing whitespace is syntactically significant.
678 The conditional request controls a scope containing whitespace only, so
679 it is unlikely to have a significant effect, except that it may control a
680 following el clause.
681
682 skipping empty macro
683 (mdoc) The indicated macro has no arguments and hence no effect.
684
685 empty block
686 (mdoc, man) A Bd, Bk, Bl, D1, Dl, MT, RS, or UR block contains nothing in
687 its body and will produce no output.
688
689 empty argument, using 0n
690 (mdoc) The required width is missing after Bd or Bl -offset or -width.
691
692 missing display type, using -ragged
693 (mdoc) The Bd macro is invoked without the required display type.
694
695 list type is not the first argument
696 (mdoc) In a Bl macro, at least one other argument precedes the type
697 argument. The mandoc utility copes with any argument order, but some
698 other mdoc(5) implementations do not.
699
700 missing -width in -tag list, using 8n
701 (mdoc) Every Bl macro having the -tag argument requires -width, too.
702
703 missing utility name, using ""
704 (mdoc) The Ex -std macro is called without an argument before Nm has
705 first been called with an argument.
706
707 missing function name, using ""
708 (mdoc) The Fo macro is called without an argument. No function name is
709 printed.
710
711 empty head in list item
712 (mdoc) In a Bl -diag, -hang, -inset, -ohang, or -tag list, an It macro
713 lacks the required argument. The item head is left empty.
714
715 empty list item
716 (mdoc) In a Bl -bullet, -dash, -enum, or -hyphen list, an It block is
717 empty. An empty list item is shown.
718
719 missing argument, using next line
720 (mdoc) An It macro in a Bd -column list has no arguments. While mandoc
721 uses the text or macros of the following line, if any, for the cell,
722 other formatters may misformat the list.
723
724 missing font type, using \fR
725 (mdoc) A Bf macro has no argument. It switches to the default font.
726
727 unknown font type, using \fR
728 (mdoc) The Bf argument is invalid. The default font is used instead.
729
730 nothing follows prefix
731 (mdoc) A Pf macro has no argument, or only one argument and no macro
732 follows on the same input line. This defeats its purpose; in particular,
733 spacing is not suppressed before the text or macros following on the next
734 input line.
735
736 empty reference block
737 (mdoc) An Rs macro is immediately followed by an Re macro on the next
738 input line. Such an empty block does not produce any output.
739
740 missing section argument
741 (mdoc) An Xr macro lacks its second, section number argument. The first
742 argument, i.e. the name, is printed, but without subsequent parentheses.
743
744 missing -std argument, adding it
745 (mdoc) An Ex or Rv macro lacks the required -std argument. The mandoc
746 utility assumes -std even when it is not specified, but other
747 implementations may not.
748
749 missing option string, using ""
750 (man) The OP macro is invoked without any argument. An empty pair of
751 square brackets is shown.
752
753 missing resource identifier, using ""
754 (man) The MT or UR macro is invoked without any argument. An empty pair
755 of angle brackets is shown.
756
757 missing eqn box, using ""
758 (eqn) A diacritic mark or a binary operator is found, but there is
759 nothing to the left of it. An empty box is inserted.
760
761 Warnings related to bad macro arguments
762 duplicate argument
763 (mdoc) A Bd or Bl macro has more than one -compact, more than one
764 -offset, or more than one -width argument. All but the last instances of
765 these arguments are ignored.
766
767 skipping duplicate argument
768 (mdoc) An An macro has more than one -split or -nosplit argument. All
769 but the first of these arguments are ignored.
770
771 skipping duplicate display type
772 (mdoc) A Bd macro has more than one type argument; the first one is used.
773
774 skipping duplicate list type
775 (mdoc) A Bl macro has more than one type argument; the first one is used.
776
777 skipping -width argument
778 (mdoc) A Bl -column, -diag, -ohang, -inset, or -item list has a -width
779 argument. That has no effect.
780
781 wrong number of cells
782 In a line of a Bl -column list, the number of tabs or Ta macros is less
783 than the number expected from the list header line or exceeds the
784 expected number by more than one. Missing cells remain empty, and all
785 cells exceeding the number of columns are joined into one single cell.
786
787 unknown AT&T UNIX version
788 (mdoc) An At macro has an invalid argument. It is used verbatim, with
789 "AT&T UNIX " prefixed to it.
790
791 comma in function argument
792 (mdoc) An argument of an Fa or Fn macro contains a comma; it should
793 probably be split into two arguments.
794
795 parenthesis in function name
796 (mdoc) The first argument of an Fc or Fn macro contains an opening or
797 closing parenthesis; that's probably wrong, parentheses are added
798 automatically.
799
800 unknown library name
801 (mdoc, not on OpenBSD) An Lb macro has an unknown name argument and will
802 be rendered as "library "name"".
803
804 invalid content in Rs block
805 (mdoc) An Rs block contains plain text or non-% macros. The bogus
806 content is left in the syntax tree. Formatting may be poor.
807
808 invalid Boolean argument
809 (mdoc) An Sm macro has an argument other than on or off. The invalid
810 argument is moved out of the macro, which leaves the macro empty, causing
811 it to toggle the spacing mode.
812
813 unknown font, skipping request
814 (man, tbl) A mandoc_roff(5) ft request or a tbl(5) f layout modifier has
815 an unknown font argument.
816
817 odd number of characters in request
818 (roff) A tr request contains an odd number of characters. The last
819 character is mapped to the blank character.
820
821 Warnings related to plain text
822 blank line in fill mode, using .sp
823 (mdoc) The meaning of blank input lines is only well-defined in non-fill
824 mode: In fill mode, line breaks of text input lines are not supposed to
825 be significant. However, for compatibility with groff, blank lines in
826 fill mode are replaced with sp requests.
827
828 tab in filled text
829 (mdoc, man) The meaning of tab characters is only well-defined in non-
830 fill mode: In fill mode, whitespace is not supposed to be significant on
831 text input lines. As an implementation dependent choice, tab characters
832 on text lines are passed through to the formatters in any case. Given
833 that the text before the tab character will be filled, it is hard to
834 predict which tab stop position the tab will advance to.
835
836 new sentence, new line
837 (mdoc) A new sentence starts in the middle of a text line. Start it on a
838 new input line to help formatters produce correct spacing.
839
840 invalid escape sequence
841 (roff) An escape sequence has an invalid opening argument delimiter,
842 lacks the closing argument delimiter, or the argument has too few
843 characters. If the argument is incomplete, \* and \n expand to an empty
844 string, \B to the digit `0', and \w to the length of the incomplete
845 argument. All other invalid escape sequences are ignored.
846
847 undefined string, using ""
848 (roff) If a string is used without being defined before, its value is
849 implicitly set to the empty string. However, defining strings explicitly
850 before use keeps the code more readable.
851
852 Warnings related to tables
853 tbl line starts with span
854 (tbl) The first cell in a table layout line is a horizontal span (`s').
855 Data provided for this cell is ignored, and nothing is printed in the
856 cell.
857
858 tbl column starts with span
859 (tbl) The first line of a table layout specification requests a vertical
860 span (`^'). Data provided for this cell is ignored, and nothing is
861 printed in the cell.
862
863 skipping vertical bar in tbl layout
864 (tbl) A table layout specification contains more than two consecutive
865 vertical bars. A double bar is printed, all additional bars are
866 discarded.
867
868 Errors related to tables
869 non-alphabetic character in tbl options
870 (tbl) The table options line contains a character other than a letter,
871 blank, or comma where the beginning of an option name is expected. The
872 character is ignored.
873
874 skipping unknown tbl option
875 (tbl) The table options line contains a string of letters that does not
876 match any known option name. The word is ignored.
877
878 missing tbl option argument
879 (tbl) A table option that requires an argument is not followed by an
880 opening parenthesis, or the opening parenthesis is immediately followed
881 by a closing parenthesis. The option is ignored.
882
883 wrong tbl option argument size
884 (tbl) A table option argument contains an invalid number of characters.
885 Both the option and the argument are ignored.
886
887 empty tbl layout
888 (tbl) A table layout specification is completely empty, specifying zero
889 lines and zero columns. As a fallback, a single left-justified column is
890 used.
891
892 invalid character in tbl layout
893 (tbl) A table layout specification contains a character that can neither
894 be interpreted as a layout key character nor as a layout modifier, or a
895 modifier precedes the first key. The invalid character is discarded.
896
897 unmatched parenthesis in tbl layout
898 (tbl) A table layout specification contains an opening parenthesis, but
899 no matching closing parenthesis. The rest of the input line, starting
900 from the parenthesis, has no effect.
901
902 tbl without any data cells
903 (tbl) A table does not contain any data cells. It will probably produce
904 no output.
905
906 ignoring data in spanned tbl cell
907 (tbl) A table cell is marked as a horizontal span (`s') or vertical span
908 (`^') in the table layout, but it contains data. The data is ignored.
909
910 ignoring extra tbl data cells
911 (tbl) A data line contains more cells than the corresponding layout line.
912 The data in the extra cells is ignored.
913
914 data block open at end of tbl
915 (tbl) A data block is opened with T{, but never closed with a matching
916 T}. The remaining data lines of the table are all put into one cell, and
917 any remaining cells stay empty.
918
919 Errors related to roff, mdoc, and man code
920 duplicate prologue macro
921 (mdoc) One of the prologue macros occurs more than once. The last
922 instance overrides all previous ones.
923
924 skipping late title macro
925 (mdoc) The Dt macro appears after the first non-prologue macro.
926 Traditional formatters cannot handle this because they write the page
927 header before parsing the document body. Even though this technical
928 restriction does not apply to mandoc, traditional semantics is preserved.
929 The late macro is discarded including its arguments.
930
931 input stack limit exceeded, infinite loop?
932 (roff) Explicit recursion limits are implemented for the following
933 features, in order to prevent infinite loops:
934 - expansion of nested escape sequences including expansion of strings
935 and number registers,
936 - expansion of nested user-defined macros,
937 - and so file inclusion.
938 When a limit is hit, the output is incorrect, typically losing some
939 content, but the parser can continue.
940
941 skipping bad character
942 (mdoc, man, roff) The input file contains a byte that is not a printable
943 ascii(5) character. The message mentions the character number. The
944 offending byte is replaced with a question mark (`?'). Consider editing
945 the input file to replace the byte with an ASCII transliteration of the
946 intended character.
947
948 skipping unknown macro
949 (mdoc, man, roff) The first identifier on a request or macro line is
950 neither recognized as a mandoc_roff(5) request, nor as a user-defined
951 macro, nor, respectively, as an mdoc(5) or man(5) macro. It may be
952 mistyped or unsupported. The request or macro is discarded including its
953 arguments.
954
955 skipping insecure request
956 (roff) An input file attempted to run a shell command or to read or write
957 an external file. Such attempts are denied for security reasons.
958
959 skipping item outside list
960 (mdoc, eqn) An It macro occurs outside any Bl list, or an eqn(5) above
961 delimiter occurs outside any pile. It is discarded including its
962 arguments.
963
964 skipping column outside column list
965 (mdoc) A Ta macro occurs outside any Bl -column block. It is discarded
966 including its arguments.
967
968 skipping end of block that is not open
969 (mdoc, man, eqn, tbl, roff) Various syntax elements can only be used to
970 explicitly close blocks that have previously been opened. An mdoc(5)
971 block closing macro, a man(5) ME, RE or UE macro, an eqn(5) right
972 delimiter or closing brace, or the end of an equation, table, or
973 mandoc_roff(5) conditional request is encountered but no matching block
974 is open. The offending request or macro is discarded.
975
976 fewer RS blocks open, skipping
977 (man) The RE macro is invoked with an argument, but less than the
978 specified number of RS blocks is open. The RE macro is discarded.
979
980 inserting missing end of block
981 (mdoc, tbl) Various mdoc(5) macros as well as tables require explicit
982 closing by dedicated macros. A block that doesn't support bad nesting
983 ends before all of its children are properly closed. The open child
984 nodes are closed implicitly.
985
986 appending missing end of block
987 (mdoc, man, eqn, tbl, roff) At the end of the document, an explicit
988 mdoc(5) block, a man(5) next-line scope or MT, RS or UR block, an
989 equation, table, or mandoc_roff(5) conditional or ignore block is still
990 open. The open block is closed implicitly.
991
992 escaped character not allowed in a name
993 (roff) Macro, string and register identifiers consist of printable, non-
994 whitespace ASCII characters. Escape sequences and characters and strings
995 expressed in terms of them cannot form part of a name. The first
996 argument of an am, as, de, ds, nr, or rr request, or any argument of an
997 rm request, or the name of a request or user defined macro being called,
998 is terminated by an escape sequence. In the cases of as, ds, and nr, the
999 request has no effect at all. In the cases of am, de, rr, and rm, what
1000 was parsed up to this point is used as the arguments to the request, and
1001 the rest of the input line is discarded including the escape sequence.
1002 When parsing for a request or a user-defined macro name to be called,
1003 only the escape sequence is discarded. The characters preceding it are
1004 used as the request or macro name, the characters following it are used
1005 as the arguments to the request or macro.
1006
1007 NOT IMPLEMENTED: Bd -file
1008 (mdoc) For security reasons, the Bd macro does not support the -file
1009 argument. By requesting the inclusion of a sensitive file, a malicious
1010 document might otherwise trick a privileged user into inadvertently
1011 displaying the file on the screen, revealing the file content to
1012 bystanders. The argument is ignored including the file name following
1013 it.
1014
1015 skipping display without arguments
1016 (mdoc) A Bd block macro does not have any arguments. The block is
1017 discarded, and the block content is displayed in whatever mode was active
1018 before the block.
1019
1020 missing list type, using -item
1021 (mdoc) A Bl macro fails to specify the list type.
1022
1023 argument is not numeric, using 1
1024 (roff) The argument of a ce request is not a number.
1025
1026 missing manual name, using ""
1027 (mdoc) The first call to Nm, or any call in the NAME section, lacks the
1028 required argument.
1029
1030 uname(3) system call failed, using UNKNOWN
1031 (mdoc) The Os macro is called without arguments, and the uname(3) system
1032 call failed. As a workaround, mandoc can be compiled with
1033 -DOSNAME="\"string\"".
1034
1035 unknown standard specifier
1036 (mdoc) An St macro has an unknown argument and is discarded.
1037
1038 skipping request without numeric argument
1039 (roff, eqn) An it request or an eqn(5) size or gsize statement has a non-
1040 numeric or negative argument or no argument at all. The invalid request
1041 or statement is ignored.
1042
1043 NOT IMPLEMENTED: .so with absolute path or ".."
1044 (roff) For security reasons, mandoc allows so file inclusion requests
1045 only with relative paths and only without ascending to any parent
1046 directory. By requesting the inclusion of a sensitive file, a malicious
1047 document might otherwise trick a privileged user into inadvertently
1048 displaying the file on the screen, revealing the file content to
1049 bystanders. mandoc only shows the path as it appears behind so.
1050
1051 .so request failed
1052 (roff) Servicing a so request requires reading an external file, but the
1053 file could not be opened. mandoc only shows the path as it appears
1054 behind so.
1055
1056 skipping all arguments
1057 (mdoc, man, eqn, roff) An mdoc(5) Bt, Ed, Ef, Ek, El, Lp, Pp, Re, Rs, or
1058 Ud macro, an It macro in a list that don't support item heads, a man(5)
1059 LP, P, or PP macro, an eqn(5) EQ or EN macro, or a mandoc_roff(5) br, fi,
1060 or nf request or `..' block closing request is invoked with at least one
1061 argument. All arguments are ignored.
1062
1063 skipping excess arguments
1064 (mdoc, man, roff) A macro or request is invoked with too many arguments:
1065 - Fo, MT, PD, RS, UR, ft, or sp with more than one argument
1066 - An with another argument after -split or -nosplit
1067 - RE with more than one argument or with a non-integer argument
1068 - OP or a request of the de family with more than two arguments
1069 - Dt with more than three arguments
1070 - TH with more than five arguments
1071 - Bd, Bk, or Bl with invalid arguments
1072 The excess arguments are ignored.
1073
1074 Unsupported features
1075 input too large
1076 (mdoc, man) Currently, mandoc cannot handle input files larger than its
1077 arbitrary size limit of 2^31 bytes (2 Gigabytes). Since useful manuals
1078 are always small, this is not a problem in practice. Parsing is aborted
1079 as soon as the condition is detected.
1080
1081 unsupported control character
1082 (roff) An ASCII control character supported by other mandoc_roff(5)
1083 implementations but not by mandoc was found in an input file. It is
1084 replaced by a question mark.
1085
1086 unsupported roff request
1087 (roff) An input file contains a mandoc_roff(5) request supported by GNU
1088 troff or Heirloom troff but not by mandoc, and it is likely that this
1089 will cause information loss or considerable misformatting.
1090
1091 eqn delim option in tbl
1092 (eqn, tbl) The options line of a table defines equation delimiters. Any
1093 equation source code contained in the table will be printed unformatted.
1094
1095 unsupported table layout modifier
1096 (tbl) A table layout specification contains an `m' modifier. The
1097 modifier is discarded.
1098
1099 ignoring macro in table
1100 (tbl, mdoc, man) A table contains an invocation of an mdoc(5) or man(5)
1101 macro or of an undefined macro. The macro is ignored, and its arguments
1102 are handled as if they were a text line.
1103
1104 SEE ALSO
1105 eqn(5), man(5), mandoc_char(5), mandoc_roff(5), mdoc(5), tbl(5)
1106
1107 HISTORY
1108 The mandoc utility first appeared in OpenBSD 4.8. The option -I appeared
1109 in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
1110
1111 AUTHORS
1112 The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1113 is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1114
1115 illumos July 28, 2018 illumos