1MANDOC(1)                 BSD General Commands Manual                MANDOC(1)
2

NAME

4     mandoc — format manual pages
5

SYNOPSIS

7     mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
8            [-T output] [-W level] [file ...]
9

DESCRIPTION

11     The mandoc utility formats manual pages for display.
12
13     By default, mandoc reads mdoc(7) or man(7) text from stdin and produces
14     -T locale output.
15
16     The options are as follows:
17
18     -a      If the standard output is a terminal device and -c is not speci‐
19             fied, use more(1) to paginate the output, just like man(1) would.
20
21     -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
25     -I os=name
26             Override the default operating system name for the mdoc(7) Os and
27             for the man(7) TH macro.
28
29     -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
34             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
38             2.   If the first or second line of the input file matches the
39                  emacs mode line format
40
41                        .\" -*- [...;] coding: encoding; -*-
42
43                  then input is interpreted according to encoding.
44
45             3.   If the first non-ASCII byte in the file introduces a valid
46                  UTF-8 sequence, input is interpreted as utf-8.
47
48             4.   Otherwise, input is interpreted as iso-8859-1.
49
50     -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
58     -O options
59             Comma-separated output options.  See the descriptions of the
60             individual output formats for supported options.
61
62     -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
67             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
71     -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
83             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
89     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
93     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
98   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
103     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
110     The special characters documented in mandoc_char(7) are rendered best-
111     effort in an ASCII equivalent.  In particular, opening and closing
112     ‘single quotes’ are represented as characters number 0x60 and 0x27,
113     respectively, which agrees with all ASCII standards from 1965 to the lat‐
114     est revision (2012) and which matches the traditional way in which
115     roff(7) formatters represent single quotes in ASCII output.  This correct
116     ASCII rendering may look strange with modern Unicode-compatible fonts
117     because contrary to ASCII, Unicode uses the code point U+0060 for the
118     grave accent only, never for an opening quote.
119
120     The following -O arguments are accepted:
121
122     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
130     mdoc    Format man(7) input files in mdoc(7) output style.  Specifically,
131             this suppresses the two additional blank lines near the top and
132             the bottom of each page, 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
136     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
146     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
153   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
158     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
163     Non-ASCII characters are rendered as hexadecimal Unicode character refer‐
164     ences.
165
166     The following -O arguments are accepted:
167
168     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
174     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).
177             Instances of ‘%I’ are replaced with the include filename.  The
178             default is not to present a hyperlink.
179
180     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).
183             Instances 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
190     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
194     toc     If an input file contains at least two non-standard sections,
195             print a table of contents near the beginning of the output.
196
197   Locale Output
198     By default, mandoc automatically selects UTF-8 or ASCII output according
199     to the current locale(1).  If any of the environment variables LC_ALL,
200     LC_CTYPE, or LANG are set and the first one that is set selects the UTF-8
201     character encoding, it produces UTF-8 Output; otherwise, it falls back to
202     ASCII Output.  This output mode can also be selected explicitly with -T
203     locale.
204
205   Man Output
206     Use -T man to translate mdoc(7) input into man(7) output format.  This is
207     useful for distributing manual sources to legacy systems lacking mdoc(7)
208     formatters.
209
210     If the input format of a file is man(7), the input is copied to the out‐
211     put, expanding any roff(7) so requests.  The parser is also run, and as
212     usual, the -W level controls which DIAGNOSTICS are displayed before copy‐
213     ing the input to the output.
214
215   Markdown Output
216     Use -T markdown to translate mdoc(7) input to the markdown format con‐
217     forming to John Gruber's 2004 specification:
218           http://daringfireball.net/projects/markdown/syntax.text.
219     The output also almost conforms to the CommonMark: http://commonmark.org/
220     specification.
221
222     The character set used for the markdown output is ASCII.  Non-ASCII char‐
223     acters are encoded as HTML entities.  Since that is not possible in lit‐
224     eral font contexts, because these are rendered as code spans and code
225     blocks in the markdown output, non-ASCII characters are transliterated to
226     ASCII approximations in these contexts.
227
228     Markdown is a very weak markup language, so all semantic markup is lost,
229     and even part of the presentational markup may be lost.  Do not use this
230     as an intermediate step in converting to HTML; instead, use -T html
231     directly.
232
233     The man(7), tbl(7), and eqn(7) input languages are not supported by -T
234     markdown output mode.
235
236   PDF Output
237     PDF-1.1 output may be generated by -T pdf.  See PostScript Output for -O
238     arguments and defaults.
239
240   PostScript Output
241     PostScript "Adobe-3.0" Level-2 pages may be generated by -T ps.  Output
242     pages default to letter sized and are rendered in the Times font family,
243     11-point.  Margins are calculated as 1/9 the page length and width.
244     Line-height is 1.4m.
245
246     Special characters are rendered as in ASCII Output.
247
248     The following -O arguments are accepted:
249
250     paper=name
251             The paper size name may be one of a3, a4, a5, legal, or letter.
252             You may also manually specify dimensions as NNxNN, width by
253             height in millimetres.  If an unknown value is encountered,
254             letter is used.
255
256   UTF-8 Output
257     Use -T utf8 to force text output in UTF-8 multi-byte character encoding,
258     ignoring the locale(1) settings in the environment.  See ASCII Output
259     regarding font styles and -O arguments.
260
261     On operating systems lacking locale or wide character support, and on
262     those where the internal character representation is not UCS-4, mandoc
263     always falls back to ASCII Output.
264
265   Syntax tree output
266     Use -T tree to show a human readable representation of the syntax tree.
267     It is useful for debugging the source code of manual pages.  The exact
268     format is subject to change, so don't write parsers for it.
269
270     The first paragraph shows meta data found in the mdoc(7) prologue, on the
271     man(7) TH line, or the fallbacks used.
272
273     In the tree dump, each output line shows one syntax tree node.  Child
274     nodes are indented with respect to their parent node.  The columns are:
275
276     1.   For macro nodes, the macro name; for text and tbl(7) nodes, the con‐
277          tent.  There is a special format for eqn(7) nodes.
278     2.   Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
279     3.   Flags:
280          -   An opening parenthesis if the node is an opening delimiter.
281          -   An asterisk if the node starts a new input line.
282          -   The input line number (starting at one).
283          -   A colon.
284          -   The input column number (starting at one).
285          -   A closing parenthesis if the node is a closing delimiter.
286          -   A full stop if the node ends a sentence.
287          -   BROKEN if the node is a block broken by another block.
288          -   NOSRC if the node is not in the input file, but automatically
289              generated from macros.
290          -   NOPRT if the node is not supposed to generate output for any
291              output format.
292
293     The following -O argument is accepted:
294
295     noval   Skip validation and show the unvalidated syntax tree.  This can
296             help to find out whether a given behaviour is caused by the
297             parser or by the validator.  Meta data is not available in this
298             case.
299

ENVIRONMENT

301     LC_CTYPE  The character encoding locale(1).  When Locale Output is
302               selected, it decides whether to use ASCII or UTF-8 output for‐
303               mat.  It never affects the interpretation of input files.
304
305     MANPAGER  Any non-empty value of the environment variable MANPAGER is
306               used instead of the standard pagination program, more(1); see
307               man(1) for details.  Only used if -a or -l is specified.
308
309     PAGER     Specifies the pagination program to use when MANPAGER is not
310               defined.  If neither PAGER nor MANPAGER is defined, more(1) -s
311               is used.  Only used if -a or -l is specified.
312

EXIT STATUS

314     The mandoc utility exits with one of the following values, controlled by
315     the message level associated with the -W option:
316
317     0       No base system convention violations, style suggestions, warn‐
318             ings, or errors occurred, or those that did were ignored because
319             they were lower than the requested level.
320     1       At least one base system convention violation or style suggestion
321             occurred, but no warning or error, and -W base or -W style was
322             specified.
323     2       At least one warning occurred, but no error, and -W warning or a
324             lower level was requested.
325     3       At least one parsing error occurred, but no unsupported feature
326             was encountered, and -W error or a lower level was requested.
327     4       At least one unsupported feature was encountered, and -W unsupp
328             or a lower level was requested.
329     5       Invalid command line arguments were specified.  No input files
330             have been read.
331     6       An operating system error occurred, for example exhaustion of
332             memory, file descriptors, or process table entries.  Such errors
333             cause mandoc to exit at once, possibly in the middle of parsing
334             or formatting a file.
335
336     Note that selecting -T lint output mode implies -W all.
337

EXAMPLES

339     To page manuals to the terminal:
340
341           $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
342
343     To produce HTML manuals with /usr/share/misc/mandoc.css as the style-
344     sheet:
345
346           $ mandoc -T html -O style=/usr/share/misc/mandoc.css mdoc.7 >
347           mdoc.7.html
348
349     To check over a large set of manuals:
350
351           $ mandoc -T lint `find /usr/src -name \*\.[1-9]`
352
353     To produce a series of PostScript manuals for A4 paper:
354
355           $ mandoc -T ps -O paper=a4 mdoc.7 man.7 > manuals.ps
356
357     Convert a modern mdoc(7) manual to the older man(7) format, for use on
358     systems lacking an mdoc(7) parser:
359
360           $ mandoc -T man foo.mdoc > foo.man
361

DIAGNOSTICS

363     Messages displayed by mandoc follow this format:
364
365           mandoc: file:line:column: level: message: macro arguments (os)
366
367     The first three fields identify the file name, line number, and column
368     number of the input file where the message was triggered.  The line and
369     column numbers start at 1.  Both are omitted for messages referring to an
370     input file as a whole.  All level and message strings are explained
371     below.  The name of the macro triggering the message and its arguments
372     are omitted where meaningless.  The os operating system specifier is
373     omitted for messages that are relevant for all operating systems.  Fatal
374     messages about invalid command line arguments or operating system errors,
375     for example when memory is exhausted, may also omit the file and level
376     fields.
377
378     Message levels have the following meanings:
379
380     unsupp   An input file uses unsupported low-level roff(7) features.  The
381              output may be incomplete and/or misformatted, so using GNU troff
382              instead of mandoc to process the file may be preferable.
383
384     error    Indicates a risk of information loss or severe misformatting, in
385              most cases caused by serious syntax errors.
386
387     warning  Indicates a risk that the information shown or its formatting
388              may mismatch the author's intent in minor ways.  Additionally,
389              syntax errors are classified at least as warnings, even if they
390              do not usually cause misformatting.
391
392     style    An input file uses dubious or discouraged style.  This is not a
393              complaint about the syntax, and probably neither formatting nor
394              portability are in danger.  While great care is taken to avoid
395              false positives on the higher message levels, the style level
396              tries to reduce the probability that issues go unnoticed, so it
397              may occasionally issue bogus suggestions.  Please use your good
398              judgement to decide whether any particular style suggestion
399              really justifies a change to the input file.
400
401     base     A convention used in the base system of a specific operating
402              system is not adhered to.  These are not markup mistakes, and
403              neither the quality of formatting nor portability are in danger.
404              Messages of the base level are printed with the more intuitive
405              style level tag.
406
407     Messages of the base, style, warning, error, and unsupp levels except
408     those about non-existent or unreadable input files are hidden unless
409     their level, or a lower level, is requested using a -W option or -T lint
410     output mode.
411
412     As indicated below, all base and some style checks are only performed if
413     a specific operating system name occurs in the arguments of the -W com‐
414     mand line option, of the Os macro, of the -Ios command line option, or,
415     if neither are present, in the return value of the uname(3) function.
416
417   Conventions for base system manuals
418     Mdocdate found
419     (mdoc, NetBSD) The Dd macro uses CVS Mdocdate keyword substitution, which
420     is not supported by the NetBSD base system.  Consider using the conven‐
421     tional “Month dd, yyyy” format instead.
422
423     Mdocdate missing
424     (mdoc, OpenBSD) The Dd macro does not use CVS Mdocdate keyword substitu‐
425     tion, but using it is conventionally expected in the OpenBSD base system.
426
427     unknown architecture
428     (mdoc, OpenBSD, NetBSD) The third argument of the Dt macro does not match
429     any of the architectures this operating system is running on.
430
431     operating system explicitly specified
432     (mdoc, OpenBSD, NetBSD) The Os macro has an argument.  In the base sys‐
433     tem, it is conventionally left blank.
434
435     RCS id missing
436     (OpenBSD, NetBSD) The manual page lacks the comment line with the RCS
437     identifier generated by CVS OpenBSD or NetBSD keyword substitution as
438     conventionally used in these operating systems.
439
440     referenced manual not found
441     (mdoc) An Xr macro references a manual page that is not found in the base
442     system.  The path to look for base system manuals is configurable at com‐
443     pile time and defaults to /usr/share/man: /usr/X11R6/man.
444
445   Style suggestions
446     legacy man(7) date format
447     (mdoc) The Dd macro uses the legacy man(7) date format “yyyy-dd-mm”.
448     Consider using the conventional mdoc(7) date format “Month dd, yyyy”
449     instead.
450
451     normalizing date format to: ...
452     (mdoc, man) The Dd or TH macro provides an abbreviated month name or a
453     day number with a leading zero.  In the formatted output, the month name
454     is written out in full and the leading zero is omitted.
455
456     lower case character in document title
457     (mdoc, man) The title is still used as given in the Dt or TH macro.
458
459     duplicate RCS id
460     A single manual page contains two copies of the RCS identifier for the
461     same operating system.  Consider deleting the later instance and moving
462     the first one up to the top of the page.
463
464     possible typo in section name
465     (mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
466     similar, but not identical to a standard section name.
467
468     unterminated quoted argument
469     (roff) Macro arguments can be enclosed in double quote characters such
470     that space characters and macro names contained in the quoted argument
471     need not be escaped.  The closing quote of the last argument of a macro
472     can be omitted.  However, omitting it is not recommended because it makes
473     the code harder to read.
474
475     useless macro
476     (mdoc) A Bt, Tn, or Ud macro was found.  Simply delete it: it serves no
477     useful purpose.
478
479     consider using OS macro
480     (mdoc) A string was found in plain text or in a Bx macro that could be
481     represented using Ox, Nx, Fx, or Dx.
482
483     errnos out of order
484     (mdoc, NetBSD) The Er items in a Bl list are not in alphabetical order.
485
486     duplicate errno
487     (mdoc, NetBSD) A Bl list contains two consecutive It entries describing
488     the same Er number.
489
490     trailing delimiter
491     (mdoc) The last argument of an Ex, Fo, Nd, Nm, Os, Sh, Ss, St, or Sx
492     macro ends with a trailing delimiter.  This is usually bad style and
493     often indicates typos.  Most likely, the delimiter can be removed.
494
495     no blank before trailing delimiter
496     (mdoc) The last argument of a macro that supports trailing delimiter
497     arguments is longer than one byte and ends with a trailing delimiter.
498     Consider inserting a blank such that the delimiter becomes a separate
499     argument, thus moving it out of the scope of the macro.
500
501     fill mode already enabled, skipping
502     (man) A fi request occurs even though the document is still in fill mode,
503     or already switched back to fill mode.  It has no effect.
504
505     fill mode already disabled, skipping
506     (man) An nf request occurs even though the document already switched to
507     no-fill mode and did not switch back to fill mode yet.  It has no effect.
508
509     verbatim "--", maybe consider using \(em
510     (mdoc) Even though the ASCII output device renders an em-dash as "--",
511     that is not a good way to write it in an input file because it renders
512     poorly on all other output devices.
513
514     function name without markup
515     (mdoc) A word followed by an empty pair of parentheses occurs on a text
516     line.  Consider using an Fn or Xr macro.
517
518     whitespace at end of input line
519     (mdoc, man, roff) Whitespace at the end of input lines is almost never
520     semantically significant — but in the odd case where it might be, it is
521     extremely confusing when reviewing and maintaining documents.
522
523     bad comment style
524     (roff) Comment lines start with a dot, a backslash, and a double-quote
525     character.  The mandoc utility treats the line as a comment line even
526     without the backslash, but leaving out the backslash might not be porta‐
527     ble.
528
529   Warnings related to the document prologue
530     missing manual title, using UNTITLED
531     (mdoc) A Dt macro has no arguments, or there is no Dt macro before the
532     first non-prologue macro.
533
534     missing manual title, using ""
535     (man) There is no TH macro, or it has no arguments.
536
537     missing manual section, using ""
538     (mdoc, man) A Dt or TH macro lacks the mandatory section argument.
539
540     unknown manual section
541     (mdoc) The section number in a Dt line is invalid, but still used.
542
543     missing date, using today's date
544     (mdoc, man) The document was parsed as mdoc(7) and it has no Dd macro, or
545     the Dd macro has no arguments or only empty arguments; or the document
546     was parsed as man(7) and it has no TH macro, or the TH macro has less
547     than three arguments or its third argument is empty.
548
549     cannot parse date, using it verbatim
550     (mdoc, man) The date given in a Dd or TH macro does not follow the con‐
551     ventional format.
552
553     date in the future, using it anyway
554     (mdoc, man) The date given in a Dd or TH macro is more than a day ahead
555     of the current system time(3).
556
557     missing Os macro, using ""
558     (mdoc) The default or current system is not shown in this case.
559
560     late prologue macro
561     (mdoc) A Dd or Os macro occurs after some non-prologue macro, but still
562     takes effect.
563
564     prologue macros out of order
565     (mdoc) The prologue macros are not given in the conventional order Dd,
566     Dt, Os.  All three macros are used even when given in another order.
567
568   Warnings regarding document structure
569     .so is fragile, better use ln(1)
570     (roff) Including files only works when the parser program runs with the
571     correct current working directory.
572
573     no document body
574     (mdoc, man) The document body contains neither text nor macros.  An empty
575     document is shown, consisting only of a header and a footer line.
576
577     content before first section header
578     (mdoc, man) Some macros or text precede the first Sh or SH section
579     header.  The offending macros and text are parsed and added to the top
580     level of the syntax tree, outside any section block.
581
582     first section is not NAME
583     (mdoc) The argument of the first Sh macro is not ‘NAME’.  This may con‐
584     fuse makewhatis(8) and apropos(1).
585
586     NAME section without Nm before Nd
587     (mdoc) The NAME section does not contain any Nm child macro before the
588     first Nd macro.
589
590     NAME section without description
591     (mdoc) The NAME section lacks the mandatory Nd child macro.
592
593     description not at the end of NAME
594     (mdoc) The NAME section does contain an Nd child macro, but other content
595     follows it.
596
597     bad NAME section content
598     (mdoc) The NAME section contains plain text or macros other than Nm and
599     Nd.
600
601     missing comma before name
602     (mdoc) The NAME section contains an Nm macro that is neither the first
603     one nor preceded by a comma.
604
605     missing description line, using ""
606     (mdoc) The Nd macro lacks the required argument.  The title line of the
607     manual will end after the dash.
608
609     description line outside NAME section
610     (mdoc) An Nd macro appears outside the NAME section.  The arguments are
611     printed anyway and the following text is used for apropos(1), but none of
612     that behaviour is portable.
613
614     sections out of conventional order
615     (mdoc) A standard section occurs after another section it usually pre‐
616     cedes.  All section titles are used as given, and the order of sections
617     is not changed.
618
619     duplicate section title
620     (mdoc) The same standard section title occurs more than once.
621
622     unexpected section
623     (mdoc) A standard section header occurs in a section of the manual where
624     it normally isn't useful.
625
626     cross reference to self
627     (mdoc) An Xr macro refers to a name and section matching the section of
628     the present manual page and a name mentioned in an Nm macro in the NAME
629     or SYNOPSIS section, or in an Fn or Fo macro in the SYNOPSIS.  Consider
630     using Nm or Fn instead of Xr.
631
632     unusual Xr order
633     (mdoc) In the SEE ALSO section, an Xr macro with a lower section number
634     follows one with a higher number, or two Xr macros referring to the same
635     section are out of alphabetical order.
636
637     unusual Xr punctuation
638     (mdoc) In the SEE ALSO section, punctuation between two Xr macros differs
639     from a single comma, or there is trailing punctuation after the last Xr
640     macro.
641
642     AUTHORS section without An macro
643     (mdoc) An AUTHORS sections contains no An macros, or only empty ones.
644     Probably, there are author names lacking markup.
645
646   Warnings related to macros and nesting
647     obsolete macro
648     (mdoc) See the mdoc(7) manual for replacements.
649
650     macro neither callable nor escaped
651     (mdoc) The name of a macro that is not callable appears on a macro line.
652     It is printed verbatim.  If the intention is to call it, move it to its
653     own input line; otherwise, escape it by prepending ‘\&’.
654
655     skipping paragraph macro
656     In mdoc(7) documents, this happens
657     -   at the beginning and end of sections and subsections
658     -   right before non-compact lists and displays
659     -   at the end of items in non-column, non-compact lists
660     -   and for multiple consecutive paragraph macros.
661     In man(7) documents, it happens
662     -   for empty P, PP, and LP macros
663     -   for IP macros having neither head nor body arguments
664     -   for br or sp right after SH or SS
665
666     moving paragraph macro out of list
667     (mdoc) A list item in a Bl list contains a trailing paragraph macro.  The
668     paragraph macro is moved after the end of the list.
669
670     skipping no-space macro
671     (mdoc) An input line begins with an Ns macro, or the next argument after
672     an Ns macro is an isolated closing delimiter.  The macro is ignored.
673
674     blocks badly nested
675     (mdoc) If two blocks intersect, one should completely contain the other.
676     Otherwise, rendered output is likely to look strange in any output for‐
677     mat, and rendering in SGML-based output formats is likely to be outright
678     wrong because such languages do not support badly nested blocks at all.
679     Typical examples of badly nested blocks are "Ao Bo Ac Bc" and "Ao Bq Ac".
680     In these examples, Ac breaks Bo and Bq, respectively.
681
682     nested displays are not portable
683     (mdoc) A Bd, D1, or Dl display occurs nested inside another Bd display.
684     This works with mandoc, but fails with most other implementations.
685
686     moving content out of list
687     (mdoc) A Bl list block contains text or macros before the first It macro.
688     The offending children are moved before the beginning of the list.
689
690     first macro on line
691     Inside a Bl -column list, a Ta macro occurs as the first macro on a line,
692     which is not portable.
693
694     line scope broken
695     (man) While parsing the next-line scope of the previous macro, another
696     macro is found that prematurely terminates the previous one.  The previ‐
697     ous, interrupted macro is deleted from the parse tree.
698
699   Warnings related to missing arguments
700     skipping empty request
701     (roff, eqn) The macro name is missing from a macro definition request, or
702     an eqn(7) control statement or operation keyword lacks its required argu‐
703     ment.
704
705     conditional request controls empty scope
706     (roff) A conditional request is only useful if any of the following fol‐
707     lows it on the same logical input line:
708     -   The ‘\{’ keyword to open a multi-line scope.
709     -   A request or macro or some text, resulting in a single-line scope.
710     -   The immediate end of the logical line without any intervening white‐
711         space, resulting in next-line scope.
712     Here, a conditional request is followed by trailing whitespace only, and
713     there is no other content on its logical input line.  Note that it
714     doesn't matter whether the logical input line is split across multiple
715     physical input lines using ‘\’ line continuation characters.  This is one
716     of the rare cases where trailing whitespace is syntactically significant.
717     The conditional request controls a scope containing whitespace only, so
718     it is unlikely to have a significant effect, except that it may control a
719     following el clause.
720
721     skipping empty macro
722     (mdoc) The indicated macro has no arguments and hence no effect.
723
724     empty block
725     (mdoc, man) A Bd, Bk, Bl, D1, Dl, MT, RS, or UR block contains nothing in
726     its body and will produce no output.
727
728     empty argument, using 0n
729     (mdoc) The required width is missing after Bd or Bl -offset or -width.
730
731     missing display type, using -ragged
732     (mdoc) The Bd macro is invoked without the required display type.
733
734     list type is not the first argument
735     (mdoc) In a Bl macro, at least one other argument precedes the type argu‐
736     ment.  The mandoc utility copes with any argument order, but some other
737     mdoc(7) implementations do not.
738
739     missing -width in -tag list, using 8n
740     (mdoc) Every Bl macro having the -tag argument requires -width, too.
741
742     missing utility name, using ""
743     (mdoc) The Ex -std macro is called without an argument before Nm has
744     first been called with an argument.
745
746     missing function name, using ""
747     (mdoc) The Fo macro is called without an argument.  No function name is
748     printed.
749
750     empty head in list item
751     (mdoc) In a Bl -diag, -hang, -inset, -ohang, or -tag list, an It macro
752     lacks the required argument.  The item head is left empty.
753
754     empty list item
755     (mdoc) In a Bl -bullet, -dash, -enum, or -hyphen list, an It block is
756     empty.  An empty list item is shown.
757
758     missing argument, using next line
759     (mdoc) An It macro in a Bd -column list has no arguments.  While mandoc
760     uses the text or macros of the following line, if any, for the cell,
761     other formatters may misformat the list.
762
763     missing font type, using \fR
764     (mdoc) A Bf macro has no argument.  It switches to the default font.
765
766     unknown font type, using \fR
767     (mdoc) The Bf argument is invalid.  The default font is used instead.
768
769     nothing follows prefix
770     (mdoc) A Pf macro has no argument, or only one argument and no macro fol‐
771     lows on the same input line.  This defeats its purpose; in particular,
772     spacing is not suppressed before the text or macros following on the next
773     input line.
774
775     empty reference block
776     (mdoc) An Rs macro is immediately followed by an Re macro on the next
777     input line.  Such an empty block does not produce any output.
778
779     missing section argument
780     (mdoc) An Xr macro lacks its second, section number argument.  The first
781     argument, i.e. the name, is printed, but without subsequent parentheses.
782
783     missing -std argument, adding it
784     (mdoc) An Ex or Rv macro lacks the required -std argument.  The mandoc
785     utility assumes -std even when it is not specified, but other implementa‐
786     tions may not.
787
788     missing option string, using ""
789     (man) The OP macro is invoked without any argument.  An empty pair of
790     square brackets is shown.
791
792     missing resource identifier, using ""
793     (man) The MT or UR macro is invoked without any argument.  An empty pair
794     of angle brackets is shown.
795
796     missing eqn box, using ""
797     (eqn) A diacritic mark or a binary operator is found, but there is noth‐
798     ing to the left of it.  An empty box is inserted.
799
800   Warnings related to bad macro arguments
801     duplicate argument
802     (mdoc) A Bd or Bl macro has more than one -compact, more than one
803     -offset, or more than one -width argument.  All but the last instances of
804     these arguments are ignored.
805
806     skipping duplicate argument
807     (mdoc) An An macro has more than one -split or -nosplit argument.  All
808     but the first of these arguments are ignored.
809
810     skipping duplicate display type
811     (mdoc) A Bd macro has more than one type argument; the first one is used.
812
813     skipping duplicate list type
814     (mdoc) A Bl macro has more than one type argument; the first one is used.
815
816     skipping -width argument
817     (mdoc) A Bl -column, -diag, -ohang, -inset, or -item list has a -width
818     argument.  That has no effect.
819
820     wrong number of cells
821     In a line of a Bl -column list, the number of tabs or Ta macros is less
822     than the number expected from the list header line or exceeds the
823     expected number by more than one.  Missing cells remain empty, and all
824     cells exceeding the number of columns are joined into one single cell.
825
826     unknown AT&T UNIX version
827     (mdoc) An At macro has an invalid argument.  It is used verbatim, with
828     "AT&T UNIX " prefixed to it.
829
830     comma in function argument
831     (mdoc) An argument of an Fa or Fn macro contains a comma; it should prob‐
832     ably be split into two arguments.
833
834     parenthesis in function name
835     (mdoc) The first argument of an Fc or Fn macro contains an opening or
836     closing parenthesis; that's probably wrong, parentheses are added auto‐
837     matically.
838
839     unknown library name
840     (mdoc, not on OpenBSD) An Lb macro has an unknown name argument and will
841     be rendered as "library “name”".
842
843     invalid content in Rs block
844     (mdoc) An Rs block contains plain text or non-% macros.  The bogus con‐
845     tent is left in the syntax tree.  Formatting may be poor.
846
847     invalid Boolean argument
848     (mdoc) An Sm macro has an argument other than on or off.  The invalid
849     argument is moved out of the macro, which leaves the macro empty, causing
850     it to toggle the spacing mode.
851
852     argument contains two font escapes
853     (roff) The second argument of a char request contains more than one font
854     escape sequence.  A wrong font may remain active after using the charac‐
855     ter.
856
857     unknown font, skipping request
858     (man, tbl) A roff(7) ft request or a tbl(7) f layout modifier has an
859     unknown font argument.
860
861     odd number of characters in request
862     (roff) A tr request contains an odd number of characters.  The last char‐
863     acter is mapped to the blank character.
864
865   Warnings related to plain text
866     blank line in fill mode, using .sp
867     (mdoc) The meaning of blank input lines is only well-defined in non-fill
868     mode: In fill mode, line breaks of text input lines are not supposed to
869     be significant.  However, for compatibility with groff, blank lines in
870     fill mode are replaced with sp requests.
871
872     tab in filled text
873     (mdoc, man) The meaning of tab characters is only well-defined in non-
874     fill mode: In fill mode, whitespace is not supposed to be significant on
875     text input lines.  As an implementation dependent choice, tab characters
876     on text lines are passed through to the formatters in any case.  Given
877     that the text before the tab character will be filled, it is hard to pre‐
878     dict which tab stop position the tab will advance to.
879
880     new sentence, new line
881     (mdoc) A new sentence starts in the middle of a text line.  Start it on a
882     new input line to help formatters produce correct spacing.
883
884     invalid escape sequence
885     (roff) An escape sequence has an invalid opening argument delimiter,
886     lacks the closing argument delimiter, the argument is of an invalid form,
887     or it is a character escape sequence with an invalid name.  If the argu‐
888     ment is incomplete, \* and \n expand to an empty string, \B to the digit
889     ‘0’, and \w to the length of the incomplete argument.  All other invalid
890     escape sequences are ignored.
891
892     undefined escape, printing literally
893     (roff) In an escape sequence, the first character right after the leading
894     backslash is invalid.  That character is printed literally, which is
895     equivalent to ignoring the backslash.
896
897     undefined string, using ""
898     (roff) If a string is used without being defined before, its value is
899     implicitly set to the empty string.  However, defining strings explicitly
900     before use keeps the code more readable.
901
902   Warnings related to tables
903     tbl line starts with span
904     (tbl) The first cell in a table layout line is a horizontal span (‘s’).
905     Data provided for this cell is ignored, and nothing is printed in the
906     cell.
907
908     tbl column starts with span
909     (tbl) The first line of a table layout specification requests a vertical
910     span (‘^’).  Data provided for this cell is ignored, and nothing is
911     printed in the cell.
912
913     skipping vertical bar in tbl layout
914     (tbl) A table layout specification contains more than two consecutive
915     vertical bars.  A double bar is printed, all additional bars are dis‐
916     carded.
917
918   Errors related to tables
919     non-alphabetic character in tbl options
920     (tbl) The table options line contains a character other than a letter,
921     blank, or comma where the beginning of an option name is expected.  The
922     character is ignored.
923
924     skipping unknown tbl option
925     (tbl) The table options line contains a string of letters that does not
926     match any known option name.  The word is ignored.
927
928     missing tbl option argument
929     (tbl) A table option that requires an argument is not followed by an
930     opening parenthesis, or the opening parenthesis is immediately followed
931     by a closing parenthesis.  The option is ignored.
932
933     wrong tbl option argument size
934     (tbl) A table option argument contains an invalid number of characters.
935     Both the option and the argument are ignored.
936
937     empty tbl layout
938     (tbl) A table layout specification is completely empty, specifying zero
939     lines and zero columns.  As a fallback, a single left-justified column is
940     used.
941
942     invalid character in tbl layout
943     (tbl) A table layout specification contains a character that can neither
944     be interpreted as a layout key character nor as a layout modifier, or a
945     modifier precedes the first key.  The invalid character is discarded.
946
947     unmatched parenthesis in tbl layout
948     (tbl) A table layout specification contains an opening parenthesis, but
949     no matching closing parenthesis.  The rest of the input line, starting
950     from the parenthesis, has no effect.
951
952     tbl without any data cells
953     (tbl) A table does not contain any data cells.  It will probably produce
954     no output.
955
956     ignoring data in spanned tbl cell
957     (tbl) A table cell is marked as a horizontal span (‘s’) or vertical span
958     (‘^’) in the table layout, but it contains data.  The data is ignored.
959
960     ignoring extra tbl data cells
961     (tbl) A data line contains more cells than the corresponding layout line.
962     The data in the extra cells is ignored.
963
964     data block open at end of tbl
965     (tbl) A data block is opened with T{, but never closed with a matching
966     T}.  The remaining data lines of the table are all put into one cell, and
967     any remaining cells stay empty.
968
969   Errors related to roff, mdoc, and man code
970     duplicate prologue macro
971     (mdoc) One of the prologue macros occurs more than once.  The last
972     instance overrides all previous ones.
973
974     skipping late title macro
975     (mdoc) The Dt macro appears after the first non-prologue macro.  Tradi‐
976     tional formatters cannot handle this because they write the page header
977     before parsing the document body.  Even though this technical restriction
978     does not apply to mandoc, traditional semantics is preserved.  The late
979     macro is discarded including its arguments.
980
981     input stack limit exceeded, infinite loop?
982     (roff) Explicit recursion limits are implemented for the following fea‐
983     tures, in order to prevent infinite loops:
984     -   expansion of nested escape sequences including expansion of strings
985         and number registers,
986     -   expansion of nested user-defined macros,
987     -   and so file inclusion.
988     When a limit is hit, the output is incorrect, typically losing some con‐
989     tent, but the parser can continue.
990
991     skipping bad character
992     (mdoc, man, roff) The input file contains a byte that is not a printable
993     ascii(7) character.  The message mentions the character number.  The
994     offending byte is replaced with a question mark (‘?’).  Consider editing
995     the input file to replace the byte with an ASCII transliteration of the
996     intended character.
997
998     skipping unknown macro
999     (mdoc, man, roff) The first identifier on a request or macro line is nei‐
1000     ther recognized as a roff(7) request, nor as a user-defined macro, nor,
1001     respectively, as an mdoc(7) or man(7) macro.  It may be mistyped or
1002     unsupported.  The request or macro is discarded including its arguments.
1003
1004     skipping request outside macro
1005     (roff) A shift or return request occurs outside any macro definition and
1006     has no effect.
1007
1008     skipping insecure request
1009     (roff) An input file attempted to run a shell command or to read or write
1010     an external file.  Such attempts are denied for security reasons.
1011
1012     skipping item outside list
1013     (mdoc, eqn) An It macro occurs outside any Bl list, or an eqn(7) above
1014     delimiter occurs outside any pile.  It is discarded including its argu‐
1015     ments.
1016
1017     skipping column outside column list
1018     (mdoc) A Ta macro occurs outside any Bl -column block.  It is discarded
1019     including its arguments.
1020
1021     skipping end of block that is not open
1022     (mdoc, man, eqn, tbl, roff) Various syntax elements can only be used to
1023     explicitly close blocks that have previously been opened.  An mdoc(7)
1024     block closing macro, a man(7) ME, RE or UE macro, an eqn(7) right delim‐
1025     iter or closing brace, or the end of an equation, table, or roff(7) con‐
1026     ditional request is encountered but no matching block is open.  The
1027     offending request or macro is discarded.
1028
1029     fewer RS blocks open, skipping
1030     (man) The RE macro is invoked with an argument, but less than the speci‐
1031     fied number of RS blocks is open.  The RE macro is discarded.
1032
1033     inserting missing end of block
1034     (mdoc, tbl) Various mdoc(7) macros as well as tables require explicit
1035     closing by dedicated macros.  A block that doesn't support bad nesting
1036     ends before all of its children are properly closed.  The open child
1037     nodes are closed implicitly.
1038
1039     appending missing end of block
1040     (mdoc, man, eqn, tbl, roff) At the end of the document, an explicit
1041     mdoc(7) block, a man(7) next-line scope or MT, RS or UR block, an equa‐
1042     tion, table, or roff(7) conditional or ignore block is still open.  The
1043     open block is closed implicitly.
1044
1045     escaped character not allowed in a name
1046     (roff) Macro, string and register identifiers consist of printable, non-
1047     whitespace ASCII characters.  Escape sequences and characters and strings
1048     expressed in terms of them cannot form part of a name.  The first argu‐
1049     ment of an am, as, de, ds, nr, or rr request, or any argument of an rm
1050     request, or the name of a request or user defined macro being called, is
1051     terminated by an escape sequence.  In the cases of as, ds, and nr, the
1052     request has no effect at all.  In the cases of am, de, rr, and rm, what
1053     was parsed up to this point is used as the arguments to the request, and
1054     the rest of the input line is discarded including the escape sequence.
1055     When parsing for a request or a user-defined macro name to be called,
1056     only the escape sequence is discarded.  The characters preceding it are
1057     used as the request or macro name, the characters following it are used
1058     as the arguments to the request or macro.
1059
1060     using macro argument outside macro
1061     (roff) The escape sequence \$ occurs outside any macro definition and
1062     expands to the empty string.
1063
1064     argument number is not numeric
1065     (roff) The argument of the escape sequence \$ is not a digit; the escape
1066     sequence expands to the empty string.
1067
1068     NOT IMPLEMENTED: Bd -file
1069     (mdoc) For security reasons, the Bd macro does not support the -file
1070     argument.  By requesting the inclusion of a sensitive file, a malicious
1071     document might otherwise trick a privileged user into inadvertently dis‐
1072     playing the file on the screen, revealing the file content to bystanders.
1073     The argument is ignored including the file name following it.
1074
1075     skipping display without arguments
1076     (mdoc) A Bd block macro does not have any arguments.  The block is dis‐
1077     carded, and the block content is displayed in whatever mode was active
1078     before the block.
1079
1080     missing list type, using -item
1081     (mdoc) A Bl macro fails to specify the list type.
1082
1083     argument is not numeric, using 1
1084     (roff) The argument of a ce request is not a number.
1085
1086     argument is not a character
1087     (roff) The first argument of a char request is neither a single ASCII
1088     character nor a single character escape sequence.  The request is ignored
1089     including all its arguments.
1090
1091     missing manual name, using ""
1092     (mdoc) The first call to Nm, or any call in the NAME section, lacks the
1093     required argument.
1094
1095     uname(3) system call failed, using UNKNOWN
1096     (mdoc) The Os macro is called without arguments, and the uname(3) system
1097     call failed.  As a workaround, mandoc can be compiled with
1098     -DOSNAME="\"string\"".
1099
1100     unknown standard specifier
1101     (mdoc) An St macro has an unknown argument and is discarded.
1102
1103     skipping request without numeric argument
1104     (roff, eqn) An it request or an eqn(7) size or gsize statement has a non-
1105     numeric or negative argument or no argument at all.  The invalid request
1106     or statement is ignored.
1107
1108     excessive shift
1109     (roff) The argument of a shift request is larger than the number of argu‐
1110     ments of the macro that is currently being executed.  All macro arguments
1111     are deleted and \n(.$ is set to zero.
1112
1113     NOT IMPLEMENTED: .so with absolute path or ".."
1114     (roff) For security reasons, mandoc allows so file inclusion requests
1115     only with relative paths and only without ascending to any parent direc‐
1116     tory.  By requesting the inclusion of a sensitive file, a malicious docu‐
1117     ment might otherwise trick a privileged user into inadvertently display‐
1118     ing the file on the screen, revealing the file content to bystanders.
1119     mandoc only shows the path as it appears behind so.
1120
1121     .so request failed
1122     (roff) Servicing a so request requires reading an external file, but the
1123     file could not be opened.  mandoc only shows the path as it appears
1124     behind so.
1125
1126     skipping all arguments
1127     (mdoc, man, eqn, roff) An mdoc(7) Bt, Ed, Ef, Ek, El, Lp, Pp, Re, Rs, or
1128     Ud macro, an It macro in a list that don't support item heads, a man(7)
1129     LP, P, or PP macro, an eqn(7) EQ or EN macro, or a roff(7) br, fi, or nf
1130     request or ‘..’ block closing request is invoked with at least one argu‐
1131     ment.  All arguments are ignored.
1132
1133     skipping excess arguments
1134     (mdoc, man, roff) A macro or request is invoked with too many arguments:
1135       -   Fo, MT, PD, RS, UR, ft, or sp with more than one argument
1136       -   An with another argument after -split or -nosplit
1137       -   RE with more than one argument or with a non-integer argument
1138       -   OP or a request of the de family with more than two arguments
1139       -   Dt with more than three arguments
1140       -   TH with more than five arguments
1141       -   Bd, Bk, or Bl with invalid arguments
1142     The excess arguments are ignored.
1143
1144   Unsupported features
1145     input too large
1146     (mdoc, man) Currently, mandoc cannot handle input files larger than its
1147     arbitrary size limit of 2^31 bytes (2 Gigabytes).  Since useful manuals
1148     are always small, this is not a problem in practice.  Parsing is aborted
1149     as soon as the condition is detected.
1150
1151     unsupported control character
1152     (roff) An ASCII control character supported by other roff(7) implementa‐
1153     tions but not by mandoc was found in an input file.  It is replaced by a
1154     question mark.
1155
1156     unsupported escape sequence
1157     (roff) An input file contains an escape sequence supported by GNU troff
1158     or Heirloom troff but not by mandoc, and it is likely that this will
1159     cause information loss or considerable misformatting.
1160
1161     unsupported roff request
1162     (roff) An input file contains a roff(7) request supported by GNU troff or
1163     Heirloom troff but not by mandoc, and it is likely that this will cause
1164     information loss or considerable misformatting.
1165
1166     eqn delim option in tbl
1167     (eqn, tbl) The options line of a table defines equation delimiters.  Any
1168     equation source code contained in the table will be printed unformatted.
1169
1170     unsupported table layout modifier
1171     (tbl) A table layout specification contains an ‘m’ modifier.  The modi‐
1172     fier is discarded.
1173
1174     ignoring macro in table
1175     (tbl, mdoc, man) A table contains an invocation of an mdoc(7) or man(7)
1176     macro or of an undefined macro.  The macro is ignored, and its arguments
1177     are handled as if they were a text line.
1178

SEE ALSO

1180     apropos(1), man(1), eqn(7), man(7), mandoc_char(7), mdoc(7), roff(7),
1181     tbl(7)
1182

HISTORY

1184     The mandoc utility first appeared in OpenBSD 4.8.  The option -I appeared
1185     in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
1186

AUTHORS

1188     The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1189     is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1190
1191BSD                              May 10, 2020                              BSD
Impressum