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