1MANDOC(1) BSD General Commands Manual MANDOC(1)
2
4 mandoc — format manual pages
5
7 mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
8 [-T output] [-W level] [file ...]
9
11 The mandoc utility formats manual pages for display.
12 By default, mandoc reads mdoc(7) or man(7) text from stdin and produces
14 -T locale output.
15 The options are as follows:
17 -a If the standard output is a terminal device and -c is not speci‐
19 fied, use less(1) to paginate the output, just like man(1) would.
20 -c Copy the formatted manual pages to the standard output without
22 using less(1) to paginate them. This is the default. It can be
23 specified to override -a.
24 -I os=name
26 Override the default operating system name for the mdoc(7) Os and
27 for the man(7) TH macro.
28 -K encoding
30 Specify the input encoding. The supported encoding arguments are
31 us-ascii, iso-8859-1, and utf-8. If not specified, autodetection
32 uses the first match in the following list:
33 1. If the first three bytes of the input file are the UTF-8
35 byte order mark (BOM, 0xefbbbf), input is interpreted as
36 utf-8.
37 2. If the first or second line of the input file matches the
39 emacs mode line format
40 .\" -*- [...;] coding: encoding; -*-
42 then input is interpreted according to encoding.
44 3. If the first non-ASCII byte in the file introduces a valid
46 UTF-8 sequence, input is interpreted as utf-8.
47 4. Otherwise, input is interpreted as iso-8859-1.
49 -mdoc | -man
51 With -mdoc, all input files are interpreted as mdoc(7). With
52 -man, all input files are interpreted as man(7). By default, the
53 input language is automatically detected for each file: if the
54 first macro is Dd or Dt, the mdoc(7) parser is used; otherwise,
55 the man(7) parser is used. With other arguments, -m is silently
56 ignored.
57 -O options
59 Comma-separated output options. See the descriptions of the in‐
60 dividual output formats for supported options.
61 -T output
63 Select the output format. Supported values for the output argu‐
64 ment are ascii, html, the default of locale, man, markdown, pdf,
65 ps, tree, and utf8.
66 The special -T lint mode only parses the input and produces no
68 output. It implies -W all and redirects parser messages, which
69 usually appear on standard error output, to standard output.
70 -W level
72 Specify the minimum message level to be reported on the standard
73 error output and to affect the exit status. The level can be
74 base, style, warning, error, or unsupp. The base level automati‐
75 cally derives the operating system from the contents of the Os
76 macro, from the -Ios command line option, or from the uname(3)
77 return value. The levels openbsd and netbsd are variants of base
78 that bypass autodetection and request validation of base system
79 conventions for a particular operating system. The level all is
80 an alias for base. By default, mandoc is silent. See EXIT
81 STATUS and DIAGNOSTICS for details.
82 The special option -W stop tells mandoc to exit after parsing a
84 file that causes warnings or errors of at least the requested
85 level. No formatted output will be produced from that file. If
86 both a level and stop are requested, they can be joined with a
87 comma, for example -W error,stop.
88 file Read from the given input file. If multiple files are specified,
90 they are processed in the given order. If unspecified, mandoc
91 reads from standard input.
92 The options -fhklw are also supported and are documented in man(1). In
94 -f and -k mode, mandoc also supports the options -CMmOSs described in the
95 apropos(1) manual. The options -fkl are mutually exclusive and override
96 each other.
97 ASCII Output
99 Use -T ascii to force text output in 7-bit ASCII character encoding docu‐
100 mented in the ascii(7) manual page, ignoring the locale(1) set in the en‐
101 vironment.
102 Font styles are applied by using back-spaced encoding such that an under‐
104 lined character ‘c’ is rendered as ‘_\[bs]c’, where ‘\[bs]’ is the back-
105 space character number 8. Emboldened characters are rendered as
106 ‘c\[bs]c’. This markup is typically converted to appropriate terminal
107 sequences by the pager or ul(1). To remove the markup, pipe the output
108 to col(1) -b instead.
109 The special characters documented in mandoc_char(7) are rendered best-ef‐
111 fort in an ASCII equivalent. In particular, opening and closing ‘single
112 quotes’ are represented as characters number 0x60 and 0x27, respectively,
113 which agrees with all ASCII standards from 1965 to the latest revision
114 (2012) and which matches the traditional way in which roff(7) formatters
115 represent single quotes in ASCII output. This correct ASCII rendering
116 may look strange with modern Unicode-compatible fonts because contrary to
117 ASCII, Unicode uses the code point U+0060 for the grave accent only,
118 never for an opening quote.
119 The following -O arguments are accepted:
121 indent=indent
123 The left margin for normal text is set to indent blank characters
124 instead of the default of five for mdoc(7) and seven for man(7).
125 Increasing this is not recommended; it may result in degraded
126 formatting, for example overfull lines or ugly line breaks. When
127 output is to a pager on a terminal that is less than 66 columns
128 wide, the default is reduced to three columns.
129 mdoc Format man(7) input files in mdoc(7) output style. This prints
131 the operating system name rather than the page title on the right
132 side of the footer line, and it implies -O indent=5. One useful
133 application is for checking that -T man output formats in the
134 same way as the mdoc(7) source it was generated from.
135 tag[=term]
137 If the formatted manual page is opened in a pager, go to the def‐
138 inition of the term rather than showing the manual page from the
139 beginning. If no term is specified, reuse the first command line
140 argument that is not a section number. If that argument is in
141 apropos(1) key=val format, only the val is used rather than the
142 argument as a whole. This is useful for commands like ‘man -akO
143 tag Ic=ulimit’ to search for a keyword and jump right to its def‐
144 inition in the matching manual pages.
145 width=width
147 The output width is set to width instead of the default of 78.
148 When output is to a pager on a terminal that is less than 79 col‐
149 umns wide, the default is reduced to one less than the terminal
150 width. In any case, lines that are output in literal mode are
151 never wrapped and may exceed the output width.
152 HTML Output
154 Output produced by -T html conforms to HTML5 using optional self-closing
155 tags. Default styles use only CSS1. Equations rendered from eqn(7)
156 blocks use MathML.
157 The file /usr/share/misc/mandoc.css documents style-sheet classes avail‐
159 able for customising output. If a style-sheet is not specified with -O
160 style, -T html defaults to simple output (via an embedded style-sheet)
161 readable in any graphical or text-based web browser.
162 Non-ASCII characters are rendered as hexadecimal Unicode character refer‐
164 ences.
165 The following -O arguments are accepted:
167 fragment
169 Omit the <!DOCTYPE> declaration and the <html>, <head>, and
170 <body> elements and only emit the subtree below the <body> ele‐
171 ment. The style argument will be ignored. This is useful when
172 embedding manual content within existing documents.
173 includes=fmt
175 The string fmt, for example, ../src/%I.html, is used as a tem‐
176 plate for linked header files (usually via the In macro). In‐
177 stances of ‘%I’ are replaced with the include filename. The de‐
178 fault is not to present a hyperlink.
179 man=fmt[;fmt]
181 The string fmt, for example, ../html%S/%N.%S.html, is used as a
182 template for linked manuals (usually via the Xr macro). In‐
183 stances of ‘%N’ and ‘%S’ are replaced with the linked manual's
184 name and section, respectively. If no section is included, sec‐
185 tion 1 is assumed. The default is not to present a hyperlink.
186 If two formats are given and a file %N.%S exists in the current
187 directory, the first format is used; otherwise, the second format
188 is used.
189 style=style.css
191 The file style.css is used for an external style-sheet. This
192 must be a valid absolute or relative URI.
193 tag[=term]
195 Same syntax and semantics as for ASCII Output. This is imple‐
196 mented by passing a file:// URI ending in a fragment identifier
197 to the pager rather than passing merely a file name. When using
198 this argument, use a pager supporting such URIs, for example
199 MANPAGER='lynx -force_html' man -T html -O tag=MANPAGER man
201 MANPAGER='w3m -T text/html' man -T html -O tag=toc mandoc
202 Consequently, for HTML output, this argument does not work with
204 more(1) or less(1). For example, ‘MANPAGER=less man -T html -O
205 tag=toc mandoc’ does not work because less(1) does not support
206 file:// URIs.
207 toc If an input file contains at least two non-standard sections,
209 print a table of contents near the beginning of the output.
210 Locale Output
212 By default, mandoc automatically selects UTF-8 or ASCII output according
213 to the current locale(1). If any of the environment variables LC_ALL,
214 LC_CTYPE, or LANG are set and the first one that is set selects the UTF-8
215 character encoding, it produces UTF-8 Output; otherwise, it falls back to
216 ASCII Output. This output mode can also be selected explicitly with -T
217 locale.
218 Man Output
220 Use -T man to translate mdoc(7) input into man(7) output format. This is
221 useful for distributing manual sources to legacy systems lacking mdoc(7)
222 formatters. Embedded eqn(7) and tbl(7) code is not supported.
223 If the input format of a file is man(7), the input is copied to the out‐
225 put. The parser is also run, and as usual, the -W level controls which
226 DIAGNOSTICS are displayed before copying the input to the output.
227 Markdown Output
229 Use -T markdown to translate mdoc(7) input to the markdown format con‐
230 forming to John Gruber's 2004 specification:
231 http://daringfireball.net/projects/markdown/syntax.text The output also
232 almost conforms to the CommonMark: http://commonmark.org/ specification.
233 The character set used for the markdown output is ASCII. Non-ASCII char‐
235 acters are encoded as HTML entities. Since that is not possible in lit‐
236 eral font contexts, because these are rendered as code spans and code
237 blocks in the markdown output, non-ASCII characters are transliterated to
238 ASCII approximations in these contexts.
239 Markdown is a very weak markup language, so all semantic markup is lost,
241 and even part of the presentational markup may be lost. Do not use this
242 as an intermediate step in converting to HTML; instead, use -T html di‐
243 rectly.
244 The man(7), tbl(7), and eqn(7) input languages are not supported by -T
246 markdown output mode.
247 PDF Output
249 PDF-1.1 output may be generated by -T pdf. See PostScript Output for -O
250 arguments and defaults.
251 PostScript Output
253 PostScript "Adobe-3.0" Level-2 pages may be generated by -T ps. Output
254 pages default to letter sized and are rendered in the Times font family,
255 11-point. Margins are calculated as 1/9 the page length and width.
256 Line-height is 1.4m.
257 Special characters are rendered as in ASCII Output.
259 The following -O arguments are accepted:
261 paper=name
263 The paper size name may be one of a3, a4, a5, legal, or letter.
264 You may also manually specify dimensions as NNxNN, width by
265 height in millimetres. If an unknown value is encountered,
266 letter is used.
267 UTF-8 Output
269 Use -T utf8 to force text output in UTF-8 multi-byte character encoding,
270 ignoring the locale(1) settings in the environment. See ASCII Output re‐
271 garding font styles and -O arguments.
272 On operating systems lacking locale or wide character support, and on
274 those where the internal character representation is not UCS-4, mandoc
275 always falls back to ASCII Output.
276 Syntax tree output
278 Use -T tree to show a human readable representation of the syntax tree.
279 It is useful for debugging the source code of manual pages. The exact
280 format is subject to change, so don't write parsers for it.
281 The first paragraph shows meta data found in the mdoc(7) prologue, on the
283 man(7) TH line, or the fallbacks used.
284 In the tree dump, each output line shows one syntax tree node. Child
286 nodes are indented with respect to their parent node. The columns are:
287 1. For macro nodes, the macro name; for text and tbl(7) nodes, the con‐
289 tent. There is a special format for eqn(7) nodes.
290 2. Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
291 3. Flags:
292 - An opening parenthesis if the node is an opening delimiter.
293 - An asterisk if the node starts a new input line.
294 - The input line number (starting at one).
295 - A colon.
296 - The input column number (starting at one).
297 - A closing parenthesis if the node is a closing delimiter.
298 - A full stop if the node ends a sentence.
299 - BROKEN if the node is a block broken by another block.
300 - NOSRC if the node is not in the input file, but automatically
301 generated from macros.
302 - NOPRT if the node is not supposed to generate output for any
303 output format.
304 The following -O argument is accepted:
306 noval Skip validation and show the unvalidated syntax tree. This can
308 help to find out whether a given behaviour is caused by the
309 parser or by the validator. Meta data is not available in this
310 case.
311
313 LC_CTYPE The character encoding locale(1). When Locale Output is se‐
314 lected, it decides whether to use ASCII or UTF-8 output format.
315 It never affects the interpretation of input files.
316 MANPAGER Any non-empty value of the environment variable MANPAGER is
318 used instead of the standard pagination program, less(1); see
319 man(1) for details. Only used if -a or -l is specified.
320 PAGER Specifies the pagination program to use when MANPAGER is not
322 defined. If neither PAGER nor MANPAGER is defined, less(1) is
323 used. Only used if -a or -l is specified.
324
326 The mandoc utility exits with one of the following values, controlled by
327 the message level associated with the -W option:
328 0 No base system convention violations, style suggestions, warn‐
330 ings, or errors occurred, or those that did were ignored because
331 they were lower than the requested level.
332 1 At least one base system convention violation or style suggestion
333 occurred, but no warning or error, and -W base or -W style was
334 specified.
335 2 At least one warning occurred, but no error, and -W warning or a
336 lower level was requested.
337 3 At least one parsing error occurred, but no unsupported feature
338 was encountered, and -W error or a lower level was requested.
339 4 At least one unsupported feature was encountered, and -W unsupp
340 or a lower level was requested.
341 5 Invalid command line arguments were specified. No input files
342 have been read.
343 6 An operating system error occurred, for example exhaustion of
344 memory, file descriptors, or process table entries. Such errors
345 may cause mandoc to exit at once, possibly in the middle of pars‐
346 ing or formatting a file.
347 Note that selecting -T lint output mode implies -W all.
349
351 To page manuals to the terminal:
352 $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
354 To produce HTML manuals with /usr/share/misc/mandoc.css as the style-
356 sheet:
357 $ mandoc -T html -O style=/usr/share/misc/mandoc.css mdoc.7 >
359 mdoc.7.html
360 To check over a large set of manuals:
362 $ mandoc -T lint `find /usr/src -name \*\.[1-9]`
364 To produce a series of PostScript manuals for A4 paper:
366 $ mandoc -T ps -O paper=a4 mdoc.7 man.7 > manuals.ps
368 Convert a modern mdoc(7) manual to the older man(7) format, for use on
370 systems lacking an mdoc(7) parser:
371 $ mandoc -T man foo.mdoc > foo.man
373
375 Messages displayed by mandoc follow this format:
376 mandoc: file:line:column: level: message: macro arguments (os)
378 The first three fields identify the file name, line number, and column
380 number of the input file where the message was triggered. The line and
381 column numbers start at 1. Both are omitted for messages referring to an
382 input file as a whole. All level and message strings are explained be‐
383 low. The name of the macro triggering the message and its arguments are
384 omitted where meaningless. The os operating system specifier is omitted
385 for messages that are relevant for all operating systems. Fatal messages
386 about invalid command line arguments or operating system errors, for ex‐
387 ample when memory is exhausted, may also omit the file and level fields.
388 Message levels have the following meanings:
390 syserr An operating system error occurred. There isn't necessarily
392 anything wrong with the input files. Output may all the same be
393 missing or incomplete.
394 badarg Invalid command line arguments were specified. No input files
396 have been read and no output is produced.
397 unsupp An input file uses unsupported low-level roff(7) features. The
399 output may be incomplete and/or misformatted, so using GNU troff
400 instead of mandoc to process the file may be preferable.
401 error Indicates a risk of information loss or severe misformatting, in
403 most cases caused by serious syntax errors.
404 warning Indicates a risk that the information shown or its formatting
406 may mismatch the author's intent in minor ways. Additionally,
407 syntax errors are classified at least as warnings, even if they
408 do not usually cause misformatting.
409 style An input file uses dubious or discouraged style. This is not a
411 complaint about the syntax, and probably neither formatting nor
412 portability are in danger. While great care is taken to avoid
413 false positives on the higher message levels, the style level
414 tries to reduce the probability that issues go unnoticed, so it
415 may occasionally issue bogus suggestions. Please use your good
416 judgement to decide whether any particular style suggestion re‐
417 ally justifies a change to the input file.
418 base A convention used in the base system of a specific operating
420 system is not adhered to. These are not markup mistakes, and
421 neither the quality of formatting nor portability are in danger.
422 Messages of the base level are printed with the more intuitive
423 style level tag.
424 Messages of the base, style, warning, error, and unsupp levels are hidden
426 unless their level, or a lower level, is requested using a -W option or
427 -T lint output mode.
428 As indicated below, all base and some style checks are only performed if
430 a specific operating system name occurs in the arguments of the -W com‐
431 mand line option, of the Os macro, of the -Ios command line option, or,
432 if neither are present, in the return value of the uname(3) function.
433 Conventions for base system manuals
435 Mdocdate found
436 (mdoc, NetBSD) The Dd macro uses CVS Mdocdate keyword substitution, which
437 is not supported by the NetBSD base system. Consider using the conven‐
438 tional “Month dd, yyyy” format instead.
439 Mdocdate missing
441 (mdoc, OpenBSD) The Dd macro does not use CVS Mdocdate keyword substitu‐
442 tion, but using it is conventionally expected in the OpenBSD base system.
443 unknown architecture
445 (mdoc, OpenBSD, NetBSD) The third argument of the Dt macro does not match
446 any of the architectures this operating system is running on.
447 operating system explicitly specified
449 (mdoc, OpenBSD, NetBSD) The Os macro has an argument. In the base sys‐
450 tem, it is conventionally left blank.
451 RCS id missing
453 (OpenBSD, NetBSD) The manual page lacks the comment line with the RCS
454 identifier generated by CVS OpenBSD or NetBSD keyword substitution as
455 conventionally used in these operating systems.
456 Style suggestions
458 legacy man(7) date format
459 (mdoc) The Dd macro uses the legacy man(7) date format “yyyy-dd-mm”.
460 Consider using the conventional mdoc(7) date format “Month dd, yyyy” in‐
461 stead.
462 normalizing date format to: ...
464 (mdoc, man) The Dd or TH macro provides an abbreviated month name or a
465 day number with a leading zero. In the formatted output, the month name
466 is written out in full and the leading zero is omitted.
467 lower case character in document title
469 (mdoc, man) The title is still used as given in the Dt or TH macro.
470 duplicate RCS id
472 A single manual page contains two copies of the RCS identifier for the
473 same operating system. Consider deleting the later instance and moving
474 the first one up to the top of the page.
475 possible typo in section name
477 (mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
478 similar, but not identical to a standard section name.
479 unterminated quoted argument
481 (roff) Macro arguments can be enclosed in double quote characters such
482 that space characters and macro names contained in the quoted argument
483 need not be escaped. The closing quote of the last argument of a macro
484 can be omitted. However, omitting it is not recommended because it makes
485 the code harder to read.
486 useless macro
488 (mdoc) A Bt, Tn, or Ud macro was found. Simply delete it: it serves no
489 useful purpose.
490 consider using OS macro
492 (mdoc) A string was found in plain text or in a Bx macro that could be
493 represented using Ox, Nx, Fx, or Dx.
494 errnos out of order
496 (mdoc, NetBSD) The Er items in a Bl list are not in alphabetical order.
497 duplicate errno
499 (mdoc, NetBSD) A Bl list contains two consecutive It entries describing
500 the same Er number.
501 referenced manual not found
503 (mdoc) An Xr macro references a manual page that was not found. When
504 running with -W base, the search is restricted to the base system, by de‐
505 fault to /usr/share/man:/usr/X11R6/man. This path can be configured at
506 compile time using the MANPATH_BASE preprocessor macro. When running
507 with -W style, the search is done along the full search path as described
508 in the man(1) manual page, respecting the -m and -M command line options,
509 the MANPATH environment variable, the man.conf(5) file and falling back
510 to the default of /usr/share/man:/usr/X11R6/man:/usr/local/man, also con‐
511 figurable at compile time using the MANPATH_DEFAULT preprocessor macro.
512 trailing delimiter
514 (mdoc) The last argument of an Ex, Fo, Nd, Nm, Os, Sh, Ss, St, or Sx
515 macro ends with a trailing delimiter. This is usually bad style and of‐
516 ten indicates typos. Most likely, the delimiter can be removed.
517 no blank before trailing delimiter
519 (mdoc) The last argument of a macro that supports trailing delimiter ar‐
520 guments is longer than one byte and ends with a trailing delimiter. Con‐
521 sider inserting a blank such that the delimiter becomes a separate argu‐
522 ment, thus moving it out of the scope of the macro.
523 fill mode already enabled, skipping
525 (man) A fi request occurs even though the document is still in fill mode,
526 or already switched back to fill mode. It has no effect.
527 fill mode already disabled, skipping
529 (man) An nf request occurs even though the document already switched to
530 no-fill mode and did not switch back to fill mode yet. It has no effect.
531 input text line longer than 80 bytes
533 Consider breaking the input text line at one of the blank characters be‐
534 fore column 80.
535 verbatim "--", maybe consider using \(em
537 (mdoc) Even though the ASCII output device renders an em-dash as "--",
538 that is not a good way to write it in an input file because it renders
539 poorly on all other output devices.
540 function name without markup
542 (mdoc) A word followed by an empty pair of parentheses occurs on a text
543 line. Consider using an Fn or Xr macro.
544 whitespace at end of input line
546 (mdoc, man, roff) Whitespace at the end of input lines is almost never
547 semantically significant — but in the odd case where it might be, it is
548 extremely confusing when reviewing and maintaining documents.
549 bad comment style
551 (roff) Comment lines start with a dot, a backslash, and a double-quote
552 character. The mandoc utility treats the line as a comment line even
553 without the backslash, but leaving out the backslash might not be porta‐
554 ble.
555 Warnings related to the document prologue
557 missing manual title, using UNTITLED
558 (mdoc) A Dt macro has no arguments, or there is no Dt macro before the
559 first non-prologue macro.
560 missing manual title, using ""
562 (man) There is no TH macro, or it has no arguments.
563 missing manual section, using ""
565 (mdoc, man) A Dt or TH macro lacks the mandatory section argument.
566 unknown manual section
568 (mdoc) The section number in a Dt line is invalid, but still used.
569 filename/section mismatch
571 (mdoc, man) The name of the input file being processed is known and its
572 file name extension starts with a non-zero digit, but the Dt or TH macro
573 contains a section argument that starts with a different non-zero digit.
574 The section argument is used as provided anyway. Consider checking
575 whether the file name or the argument need a correction.
576 missing date, using ""
578 (mdoc, man) The document was parsed as mdoc(7) and it has no Dd macro, or
579 the Dd macro has no arguments or only empty arguments; or the document
580 was parsed as man(7) and it has no TH macro, or the TH macro has less
581 than three arguments or its third argument is empty.
582 cannot parse date, using it verbatim
584 (mdoc, man) The date given in a Dd or TH macro does not follow the con‐
585 ventional format.
586 date in the future, using it anyway
588 (mdoc, man) The date given in a Dd or TH macro is more than a day ahead
589 of the current system time(3).
590 missing Os macro, using ""
592 (mdoc) The default or current system is not shown in this case.
593 late prologue macro
595 (mdoc) A Dd or Os macro occurs after some non-prologue macro, but still
596 takes effect.
597 prologue macros out of order
599 (mdoc) The prologue macros are not given in the conventional order Dd,
600 Dt, Os. All three macros are used even when given in another order.
601 Warnings regarding document structure
603 .so is fragile, better use ln(1)
604 (roff) Including files only works when the parser program runs with the
605 correct current working directory.
606 no document body
608 (mdoc, man) The document body contains neither text nor macros. An empty
609 document is shown, consisting only of a header and a footer line.
610 content before first section header
612 (mdoc, man) Some macros or text precede the first Sh or SH section
613 header. The offending macros and text are parsed and added to the top
614 level of the syntax tree, outside any section block.
615 first section is not NAME
617 (mdoc) The argument of the first Sh macro is not ‘NAME’. This may con‐
618 fuse makewhatis(8) and apropos(1).
619 NAME section without Nm before Nd
621 (mdoc) The NAME section does not contain any Nm child macro before the
622 first Nd macro.
623 NAME section without description
625 (mdoc) The NAME section lacks the mandatory Nd child macro.
626 description not at the end of NAME
628 (mdoc) The NAME section does contain an Nd child macro, but other content
629 follows it.
630 bad NAME section content
632 (mdoc) The NAME section contains plain text or macros other than Nm and
633 Nd.
634 missing comma before name
636 (mdoc) The NAME section contains an Nm macro that is neither the first
637 one nor preceded by a comma.
638 missing description line, using ""
640 (mdoc) The Nd macro lacks the required argument. The title line of the
641 manual will end after the dash.
642 description line outside NAME section
644 (mdoc) An Nd macro appears outside the NAME section. The arguments are
645 printed anyway and the following text is used for apropos(1), but none of
646 that behaviour is portable.
647 sections out of conventional order
649 (mdoc) A standard section occurs after another section it usually pre‐
650 cedes. All section titles are used as given, and the order of sections
651 is not changed.
652 duplicate section title
654 (mdoc) The same standard section title occurs more than once.
655 unexpected section
657 (mdoc) A standard section header occurs in a section of the manual where
658 it normally isn't useful.
659 cross reference to self
661 (mdoc) An Xr macro refers to a name and section matching the section of
662 the present manual page and a name mentioned in an Nm macro in the NAME
663 or SYNOPSIS section, or in an Fn or Fo macro in the SYNOPSIS. Consider
664 using Nm or Fn instead of Xr.
665 unusual Xr order
667 (mdoc) In the SEE ALSO section, an Xr macro with a lower section number
668 follows one with a higher number, or two Xr macros referring to the same
669 section are out of alphabetical order.
670 unusual Xr punctuation
672 (mdoc) In the SEE ALSO section, punctuation between two Xr macros differs
673 from a single comma, or there is trailing punctuation after the last Xr
674 macro.
675 AUTHORS section without An macro
677 (mdoc) An AUTHORS sections contains no An macros, or only empty ones.
678 Probably, there are author names lacking markup.
679 Warnings related to macros and nesting
681 obsolete macro
682 (mdoc) See the mdoc(7) manual for replacements.
683 macro neither callable nor escaped
685 (mdoc) The name of a macro that is not callable appears on a macro line.
686 It is printed verbatim. If the intention is to call it, move it to its
687 own input line; otherwise, escape it by prepending ‘\&’.
688 skipping paragraph macro
690 In mdoc(7) documents, this happens
691 - at the beginning and end of sections and subsections
692 - right before non-compact lists and displays
693 - at the end of items in non-column, non-compact lists
694 - and for multiple consecutive paragraph macros.
695 In man(7) documents, it happens
696 - for empty P, PP, and LP macros
697 - for IP macros having neither head nor body arguments
698 - for br or sp right after SH or SS
699 moving paragraph macro out of list
701 (mdoc) A list item in a Bl list contains a trailing paragraph macro. The
702 paragraph macro is moved after the end of the list.
703 skipping no-space macro
705 (mdoc) An input line begins with an Ns macro, or the next argument after
706 an Ns macro is an isolated closing delimiter. The macro is ignored.
707 blocks badly nested
709 (mdoc) If two blocks intersect, one should completely contain the other.
710 Otherwise, rendered output is likely to look strange in any output for‐
711 mat, and rendering in SGML-based output formats is likely to be outright
712 wrong because such languages do not support badly nested blocks at all.
713 Typical examples of badly nested blocks are "Ao Bo Ac Bc" and "Ao Bq Ac".
714 In these examples, Ac breaks Bo and Bq, respectively.
715 nested displays are not portable
717 (mdoc) A Bd, D1, or Dl display occurs nested inside another Bd display.
718 This works with mandoc, but fails with most other implementations.
719 moving content out of list
721 (mdoc) A Bl list block contains text or macros before the first It macro.
722 The offending children are moved before the beginning of the list.
723 first macro on line
725 Inside a Bl -column list, a Ta macro occurs as the first macro on a line,
726 which is not portable.
727 line scope broken
729 (man) While parsing the next-line scope of the previous macro, another
730 macro is found that prematurely terminates the previous one. The previ‐
731 ous, interrupted macro is deleted from the parse tree.
732 Warnings related to missing arguments
734 skipping empty request
735 (roff, eqn) The macro name is missing from a macro definition request, or
736 an eqn(7) control statement or operation keyword lacks its required argu‐
737 ment.
738 conditional request controls empty scope
740 (roff) A conditional request is only useful if any of the following fol‐
741 lows it on the same logical input line:
742 - The ‘\{’ keyword to open a multi-line scope.
743 - A request or macro or some text, resulting in a single-line scope.
744 - The immediate end of the logical line without any intervening white‐
745 space, resulting in next-line scope.
746 Here, a conditional request is followed by trailing whitespace only, and
747 there is no other content on its logical input line. Note that it
748 doesn't matter whether the logical input line is split across multiple
749 physical input lines using ‘\’ line continuation characters. This is one
750 of the rare cases where trailing whitespace is syntactically significant.
751 The conditional request controls a scope containing whitespace only, so
752 it is unlikely to have a significant effect, except that it may control a
753 following el clause.
754 skipping empty macro
756 (mdoc) The indicated macro has no arguments and hence no effect.
757 empty block
759 (mdoc, man) A Bd, Bk, Bl, D1, Dl, MT, RS, or UR block contains nothing in
760 its body and will produce no output.
761 empty argument, using 0n
763 (mdoc) The required width is missing after Bd or Bl -offset or -width.
764 missing display type, using -ragged
766 (mdoc) The Bd macro is invoked without the required display type.
767 list type is not the first argument
769 (mdoc) In a Bl macro, at least one other argument precedes the type argu‐
770 ment. The mandoc utility copes with any argument order, but some other
771 mdoc(7) implementations do not.
772 missing -width in -tag list, using 8n
774 (mdoc) Every Bl macro having the -tag argument requires -width, too.
775 missing utility name, using ""
777 (mdoc) The Ex -std macro is called without an argument before Nm has
778 first been called with an argument.
779 missing function name, using ""
781 (mdoc) The Fo macro is called without an argument. No function name is
782 printed.
783 empty head in list item
785 (mdoc) In a Bl -diag, -hang, -inset, -ohang, or -tag list, an It macro
786 lacks the required argument. The item head is left empty.
787 empty list item
789 (mdoc) In a Bl -bullet, -dash, -enum, or -hyphen list, an It block is
790 empty. An empty list item is shown.
791 missing argument, using next line
793 (mdoc) An It macro in a Bd -column list has no arguments. While mandoc
794 uses the text or macros of the following line, if any, for the cell,
795 other formatters may misformat the list.
796 missing font type, using \fR
798 (mdoc) A Bf macro has no argument. It switches to the default font.
799 unknown font type, using \fR
801 (mdoc) The Bf argument is invalid. The default font is used instead.
802 nothing follows prefix
804 (mdoc) A Pf macro has no argument, or only one argument and no macro fol‐
805 lows on the same input line. This defeats its purpose; in particular,
806 spacing is not suppressed before the text or macros following on the next
807 input line.
808 empty reference block
810 (mdoc) An Rs macro is immediately followed by an Re macro on the next in‐
811 put line. Such an empty block does not produce any output.
812 missing section argument
814 (mdoc) An Xr macro lacks its second, section number argument. The first
815 argument, i.e. the name, is printed, but without subsequent parentheses.
816 missing -std argument, adding it
818 (mdoc) An Ex or Rv macro lacks the required -std argument. The mandoc
819 utility assumes -std even when it is not specified, but other implementa‐
820 tions may not.
821 missing option string, using ""
823 (man) The OP macro is invoked without any argument. An empty pair of
824 square brackets is shown.
825 missing resource identifier, using ""
827 (man) The MT or UR macro is invoked without any argument. An empty pair
828 of angle brackets is shown.
829 missing eqn box, using ""
831 (eqn) A diacritic mark or a binary operator is found, but there is noth‐
832 ing to the left of it. An empty box is inserted.
833 Warnings related to bad macro arguments
835 duplicate argument
836 (mdoc) A Bd or Bl macro has more than one -compact, more than one
837 -offset, or more than one -width argument. All but the last instances of
838 these arguments are ignored.
839 skipping duplicate argument
841 (mdoc) An An macro has more than one -split or -nosplit argument. All
842 but the first of these arguments are ignored.
843 skipping duplicate display type
845 (mdoc) A Bd macro has more than one type argument; the first one is used.
846 skipping duplicate list type
848 (mdoc) A Bl macro has more than one type argument; the first one is used.
849 skipping -width argument
851 (mdoc) A Bl -column, -diag, -ohang, -inset, or -item list has a -width
852 argument. That has no effect.
853 wrong number of cells
855 In a line of a Bl -column list, the number of tabs or Ta macros is less
856 than the number expected from the list header line or exceeds the ex‐
857 pected number by more than one. Missing cells remain empty, and all
858 cells exceeding the number of columns are joined into one single cell.
859 unknown AT&T UNIX version
861 (mdoc) An At macro has an invalid argument. It is used verbatim, with
862 "AT&T UNIX " prefixed to it.
863 comma in function argument
865 (mdoc) An argument of an Fa or Fn macro contains a comma; it should prob‐
866 ably be split into two arguments.
867 parenthesis in function name
869 (mdoc) The first argument of an Fc or Fn macro contains an opening or
870 closing parenthesis; that's probably wrong, parentheses are added auto‐
871 matically.
872 unknown library name
874 (mdoc, not on OpenBSD) An Lb macro has an unknown name argument and will
875 be rendered as "library “name”".
876 invalid content in Rs block
878 (mdoc) An Rs block contains plain text or non-% macros. The bogus con‐
879 tent is left in the syntax tree. Formatting may be poor.
880 invalid Boolean argument
882 (mdoc) An Sm macro has an argument other than on or off. The invalid ar‐
883 gument is moved out of the macro, which leaves the macro empty, causing
884 it to toggle the spacing mode.
885 argument contains two font escapes
887 (roff) The second argument of a char request contains more than one font
888 escape sequence. A wrong font may remain active after using the charac‐
889 ter.
890 unknown font, skipping request
892 (man, tbl) A roff(7) ft request or a tbl(7) f layout modifier has an un‐
893 known font argument.
894 odd number of characters in request
896 (roff) A tr request contains an odd number of characters. The last char‐
897 acter is mapped to the blank character.
898 Warnings related to plain text
900 blank line in fill mode, using .sp
901 (mdoc) The meaning of blank input lines is only well-defined in non-fill
902 mode: In fill mode, line breaks of text input lines are not supposed to
903 be significant. However, for compatibility with groff, blank lines in
904 fill mode are formatted like sp requests. To request a paragraph break,
905 use Pp instead of a blank line.
906 tab in filled text
908 (mdoc, man) The meaning of tab characters is only well-defined in non-
909 fill mode: In fill mode, whitespace is not supposed to be significant on
910 text input lines. As an implementation dependent choice, tab characters
911 on text lines are passed through to the formatters in any case. Given
912 that the text before the tab character will be filled, it is hard to pre‐
913 dict which tab stop position the tab will advance to.
914 new sentence, new line
916 (mdoc) A new sentence starts in the middle of a text line. Start it on a
917 new input line to help formatters produce correct spacing.
918 invalid escape sequence
920 (roff) An escape sequence has an invalid opening argument delimiter,
921 lacks the closing argument delimiter, the argument is of an invalid form,
922 or it is a character escape sequence with an invalid name. If the argu‐
923 ment is incomplete, \* and \n expand to an empty string, \B to the digit
924 ‘0’, and \w to the length of the incomplete argument. All other invalid
925 escape sequences are ignored.
926 undefined escape, printing literally
928 (roff) In an escape sequence, the first character right after the leading
929 backslash is invalid. That character is printed literally, which is
930 equivalent to ignoring the backslash.
931 undefined string, using ""
933 (roff) If a string is used without being defined before, its value is im‐
934 plicitly set to the empty string. However, defining strings explicitly
935 before use keeps the code more readable.
936 Warnings related to tables
938 tbl line starts with span
939 (tbl) The first cell in a table layout line is a horizontal span (‘s’).
940 Data provided for this cell is ignored, and nothing is printed in the
941 cell.
942 tbl column starts with span
944 (tbl) The first line of a table layout specification requests a vertical
945 span (‘^’). Data provided for this cell is ignored, and nothing is
946 printed in the cell.
947 skipping vertical bar in tbl layout
949 (tbl) A table layout specification contains more than two consecutive
950 vertical bars. A double bar is printed, all additional bars are dis‐
951 carded.
952 Errors related to tables
954 non-alphabetic character in tbl options
955 (tbl) The table options line contains a character other than a letter,
956 blank, or comma where the beginning of an option name is expected. The
957 character is ignored.
958 skipping unknown tbl option
960 (tbl) The table options line contains a string of letters that does not
961 match any known option name. The word is ignored.
962 missing tbl option argument
964 (tbl) A table option that requires an argument is not followed by an
965 opening parenthesis, or the opening parenthesis is immediately followed
966 by a closing parenthesis. The option is ignored.
967 wrong tbl option argument size
969 (tbl) A table option argument contains an invalid number of characters.
970 Both the option and the argument are ignored.
971 empty tbl layout
973 (tbl) A table layout specification is completely empty, specifying zero
974 lines and zero columns. As a fallback, a single left-justified column is
975 used.
976 invalid character in tbl layout
978 (tbl) A table layout specification contains a character that can neither
979 be interpreted as a layout key character nor as a layout modifier, or a
980 modifier precedes the first key. The invalid character is discarded.
981 unmatched parenthesis in tbl layout
983 (tbl) A table layout specification contains an opening parenthesis, but
984 no matching closing parenthesis. The rest of the input line, starting
985 from the parenthesis, has no effect.
986 ignoring excessive spacing in tbl layout
988 (tbl) A spacing modifier in a table layout is unreasonably large. The
989 default spacing of 3n is used instead.
990 tbl without any data cells
992 (tbl) A table does not contain any data cells. It will probably produce
993 no output.
994 ignoring data in spanned tbl cell
996 (tbl) A table cell is marked as a horizontal span (‘s’) or vertical span
997 (‘^’) in the table layout, but it contains data. The data is ignored.
998 ignoring extra tbl data cells
1000 (tbl) A data line contains more cells than the corresponding layout line.
1001 The data in the extra cells is ignored.
1002 data block open at end of tbl
1004 (tbl) A data block is opened with T{, but never closed with a matching
1005 T}. The remaining data lines of the table are all put into one cell, and
1006 any remaining cells stay empty.
1007 Errors related to roff, mdoc, and man code
1009 duplicate prologue macro
1010 (mdoc) One of the prologue macros occurs more than once. The last in‐
1011 stance overrides all previous ones.
1012 skipping late title macro
1014 (mdoc) The Dt macro appears after the first non-prologue macro. Tradi‐
1015 tional formatters cannot handle this because they write the page header
1016 before parsing the document body. Even though this technical restriction
1017 does not apply to mandoc, traditional semantics is preserved. The late
1018 macro is discarded including its arguments.
1019 input stack limit exceeded, infinite loop?
1021 (roff) Explicit recursion limits are implemented for the following fea‐
1022 tures, in order to prevent infinite loops:
1023 - expansion of nested escape sequences including expansion of strings
1024 and number registers,
1025 - expansion of nested user-defined macros,
1026 - and so file inclusion.
1027 When a limit is hit, the output is incorrect, typically losing some con‐
1028 tent, but the parser can continue.
1029 skipping bad character
1031 (mdoc, man, roff) The input file contains a byte that is not a printable
1032 ascii(7) character. The message mentions the character number. The of‐
1033 fending byte is replaced with a question mark (‘?’). Consider editing
1034 the input file to replace the byte with an ASCII transliteration of the
1035 intended character.
1036 skipping unknown macro
1038 (mdoc, man, roff) The first identifier on a request or macro line is nei‐
1039 ther recognized as a roff(7) request, nor as a user-defined macro, nor,
1040 respectively, as an mdoc(7) or man(7) macro. It may be mistyped or un‐
1041 supported. The request or macro is discarded including its arguments.
1042 skipping request outside macro
1044 (roff) A shift or return request occurs outside any macro definition and
1045 has no effect.
1046 skipping insecure request
1048 (roff) An input file attempted to run a shell command or to read or write
1049 an external file. Such attempts are denied for security reasons.
1050 skipping item outside list
1052 (mdoc, eqn) An It macro occurs outside any Bl list, or an eqn(7) above
1053 delimiter occurs outside any pile. It is discarded including its argu‐
1054 ments.
1055 skipping column outside column list
1057 (mdoc) A Ta macro occurs outside any Bl -column block. It is discarded
1058 including its arguments.
1059 skipping end of block that is not open
1061 (mdoc, man, eqn, tbl, roff) Various syntax elements can only be used to
1062 explicitly close blocks that have previously been opened. An mdoc(7)
1063 block closing macro, a man(7) ME, RE or UE macro, an eqn(7) right delim‐
1064 iter or closing brace, or the end of an equation, table, or roff(7) con‐
1065 ditional request is encountered but no matching block is open. The of‐
1066 fending request or macro is discarded.
1067 fewer RS blocks open, skipping
1069 (man) The RE macro is invoked with an argument, but less than the speci‐
1070 fied number of RS blocks is open. The RE macro is discarded.
1071 inserting missing end of block
1073 (mdoc, tbl) Various mdoc(7) macros as well as tables require explicit
1074 closing by dedicated macros. A block that doesn't support bad nesting
1075 ends before all of its children are properly closed. The open child
1076 nodes are closed implicitly.
1077 appending missing end of block
1079 (mdoc, man, eqn, tbl, roff) At the end of the document, an explicit
1080 mdoc(7) block, a man(7) next-line scope or MT, RS or UR block, an equa‐
1081 tion, table, or roff(7) conditional or ignore block is still open. The
1082 open block is closed implicitly.
1083 escaped character not allowed in a name
1085 (roff) Macro, string and register identifiers consist of printable, non-
1086 whitespace ASCII characters. Escape sequences and characters and strings
1087 expressed in terms of them cannot form part of a name. The first argu‐
1088 ment of an am, as, de, ds, nr, or rr request, or any argument of an rm
1089 request, or the name of a request or user defined macro being called, is
1090 terminated by an escape sequence. In the cases of as, ds, and nr, the
1091 request has no effect at all. In the cases of am, de, rr, and rm, what
1092 was parsed up to this point is used as the arguments to the request, and
1093 the rest of the input line is discarded including the escape sequence.
1094 When parsing for a request or a user-defined macro name to be called,
1095 only the escape sequence is discarded. The characters preceding it are
1096 used as the request or macro name, the characters following it are used
1097 as the arguments to the request or macro.
1098 using macro argument outside macro
1100 (roff) The escape sequence \$ occurs outside any macro definition and ex‐
1101 pands to the empty string.
1102 argument number is not numeric
1104 (roff) The argument of the escape sequence \$ is not a digit; the escape
1105 sequence expands to the empty string.
1106 NOT IMPLEMENTED: Bd -file
1108 (mdoc) For security reasons, the Bd macro does not support the -file ar‐
1109 gument. By requesting the inclusion of a sensitive file, a malicious
1110 document might otherwise trick a privileged user into inadvertently dis‐
1111 playing the file on the screen, revealing the file content to bystanders.
1112 The argument is ignored including the file name following it.
1113 skipping display without arguments
1115 (mdoc) A Bd block macro does not have any arguments. The block is dis‐
1116 carded, and the block content is displayed in whatever mode was active
1117 before the block.
1118 missing list type, using -item
1120 (mdoc) A Bl macro fails to specify the list type.
1121 argument is not numeric, using 1
1123 (roff) The argument of a ce request is not a number.
1124 argument is not a character
1126 (roff) The first argument of a char request is neither a single ASCII
1127 character nor a single character escape sequence. The request is ignored
1128 including all its arguments.
1129 missing manual name, using ""
1131 (mdoc) The first call to Nm, or any call in the NAME section, lacks the
1132 required argument.
1133 uname(3) system call failed, using UNKNOWN
1135 (mdoc) The Os macro is called without arguments, and the uname(3) system
1136 call failed. As a workaround, mandoc can be compiled with
1137 -DOSNAME="\"string\"".
1138 unknown standard specifier
1140 (mdoc) An St macro has an unknown argument and is discarded.
1141 skipping request without numeric argument
1143 (roff, eqn) An it request or an eqn(7) size or gsize statement has a non-
1144 numeric or negative argument or no argument at all. The invalid request
1145 or statement is ignored.
1146 excessive shift
1148 (roff) The argument of a shift request is larger than the number of argu‐
1149 ments of the macro that is currently being executed. All macro arguments
1150 are deleted and \n(.$ is set to zero.
1151 NOT IMPLEMENTED: .so with absolute path or ".."
1153 (roff) For security reasons, mandoc allows so file inclusion requests
1154 only with relative paths and only without ascending to any parent direc‐
1155 tory. By requesting the inclusion of a sensitive file, a malicious docu‐
1156 ment might otherwise trick a privileged user into inadvertently display‐
1157 ing the file on the screen, revealing the file content to bystanders.
1158 mandoc only shows the path as it appears behind so.
1159 .so request failed
1161 (roff) Servicing a so request requires reading an external file, but the
1162 file could not be opened. mandoc only shows the path as it appears be‐
1163 hind so.
1164 skipping all arguments
1166 (mdoc, man, eqn, roff) An mdoc(7) Bt, Ed, Ef, Ek, El, Lp, Pp, Re, Rs, or
1167 Ud macro, an It macro in a list that don't support item heads, a man(7)
1168 LP, P, or PP macro, an eqn(7) EQ or EN macro, or a roff(7) br, fi, or nf
1169 request or ‘..’ block closing request is invoked with at least one argu‐
1170 ment. All arguments are ignored.
1171 skipping excess arguments
1173 (mdoc, man, roff) A macro or request is invoked with too many arguments:
1174 - Fo, MT, PD, RS, UR, ft, or sp with more than one argument
1175 - An with another argument after -split or -nosplit
1176 - RE with more than one argument or with a non-integer argument
1177 - OP or a request of the de family with more than two arguments
1178 - Dt with more than three arguments
1179 - TH with more than five arguments
1180 - Bd, Bk, or Bl with invalid arguments
1181 The excess arguments are ignored.
1182 Unsupported features
1184 input too large
1185 (mdoc, man) Currently, mandoc cannot handle input files larger than its
1186 arbitrary size limit of 2^31 bytes (2 Gigabytes). Since useful manuals
1187 are always small, this is not a problem in practice. Parsing is aborted
1188 as soon as the condition is detected.
1189 unsupported control character
1191 (roff) An ASCII control character supported by other roff(7) implementa‐
1192 tions but not by mandoc was found in an input file. It is replaced by a
1193 question mark.
1194 unsupported escape sequence
1196 (roff) An input file contains an escape sequence supported by GNU troff
1197 or Heirloom troff but not by mandoc, and it is likely that this will
1198 cause information loss or considerable misformatting.
1199 unsupported roff request
1201 (roff) An input file contains a roff(7) request supported by GNU troff or
1202 Heirloom troff but not by mandoc, and it is likely that this will cause
1203 information loss or considerable misformatting.
1204 eqn delim option in tbl
1206 (eqn, tbl) The options line of a table defines equation delimiters. Any
1207 equation source code contained in the table will be printed unformatted.
1208 unsupported table layout modifier
1210 (tbl) A table layout specification contains an ‘m’ modifier. The modi‐
1211 fier is discarded.
1212 ignoring macro in table
1214 (tbl, mdoc, man) A table contains an invocation of an mdoc(7) or man(7)
1215 macro or of an undefined macro. The macro is ignored, and its arguments
1216 are handled as if they were a text line.
1217 skipping tbl in -Tman mode
1219 (mdoc, tbl) An input file contains the TS macro. This message is only
1220 generated in -T man output mode, where tbl(7) input is not supported.
1221 skipping eqn in -Tman mode
1223 (mdoc, eqn) An input file contains the EQ macro. This message is only
1224 generated in -T man output mode, where eqn(7) input is not supported.
1225 Bad command line arguments
1227 bad command line argument
1228 The argument following one of the -IKMmOTW command line options is in‐
1229 valid, or a file given as a command line argument cannot be opened.
1230 duplicate command line argument
1232 The -I command line option was specified twice.
1233 option has a superfluous value
1235 An argument to the -O option has a value but does not accept one.
1236 missing option value
1238 An argument to the -O option has no argument but requires one.
1239 bad option value
1241 An argument to the -O indent or width option has an invalid value.
1242 duplicate option value
1244 The same -O option is specified more than once.
1245 no such tag
1247 The -O tag option was specified but the tag was not found in any of the
1248 displayed manual pages.
1249 -Tmarkdown unsupported for man(7) input
1251 (man) The -T markdown option was specified but an input file uses the
1252 man(7) language. No output is produced for that input file.
1253
1255 apropos(1), man(1), eqn(7), man(7), mandoc_char(7), mdoc(7), roff(7),
1256 tbl(7)
1257
1259 The mandoc utility first appeared in OpenBSD 4.8. The option -I appeared
1260 in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
1261
1263 The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1264 is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1265BSD August 14, 2021 BSD