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’.
107
108     The special characters documented in mandoc_char(7) are rendered best-
109     effort in an ASCII equivalent.
110
111     The following -O arguments are accepted:
112
113     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
121     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
127     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
134   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
139     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
144     Non-ASCII characters are rendered as hexadecimal Unicode character refer‐
145     ences.
146
147     The following -O arguments are accepted:
148
149     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
155     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
161     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
168     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
172   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
180   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
185     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
190   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
197     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
203     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
208     The man(7), tbl(7), and eqn(7) input languages are not supported by -T
209     markdown output mode.
210
211   PDF Output
212     PDF-1.1 output may be generated by -T pdf.  See PostScript Output for -O
213     arguments and defaults.
214
215   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
221     Special characters are rendered as in ASCII Output.
222
223     The following -O arguments are accepted:
224
225     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
231   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
236     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
240   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
245     The first paragraph shows meta data found in the mdoc(7) prologue, on the
246     man(7) TH line, or the fallbacks used.
247
248     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
251     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
268     The following -O argument is accepted:
269
270     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

ENVIRONMENT

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
280     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
284     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

EXIT STATUS

289     The mandoc utility exits with one of the following values, controlled by
290     the message level associated with the -W option:
291
292     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
311     Note that selecting -T lint output mode implies -W all.
312

EXAMPLES

314     To page manuals to the terminal:
315
316           $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
317
318     To produce HTML manuals with mandoc.css as the style-sheet:
319
320           $ mandoc -T html -O style=mandoc.css mdoc.7 > mdoc.7.html
321
322     To check over a large set of manuals:
323
324           $ mandoc -T lint `find /usr/src -name \*\.[1-9]`
325
326     To produce a series of PostScript manuals for A4 paper:
327
328           $ mandoc -T ps -O paper=a4 mdoc.7 man.7 > manuals.ps
329
330     Convert a modern mdoc(7) manual to the older man(7) format, for use on
331     systems lacking an mdoc(7) parser:
332
333           $ mandoc -T man foo.mdoc > foo.man
334

DIAGNOSTICS

336     Messages displayed by mandoc follow this format:
337
338           mandoc: file:line:column: level: message: macro args (os)
339
340     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
347     Message levels have the following meanings:
348
349     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
353     error    Indicates a risk of information loss or severe misformatting, in
354              most cases caused by serious syntax errors.
355
356     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
361     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
370     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
376     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
381     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
386   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
392     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
396     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
400     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
404     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
409     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
414   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
420     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
425     lower case character in document title
426     (mdoc, man) The title is still used as given in the Dt or TH macro.
427
428     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
433     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
437     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
444     useless macro
445     (mdoc) A Bt, Tn, or Ud macro was found.  Simply delete it: it serves no
446     useful purpose.
447
448     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
452     errnos out of order
453     (mdoc, NetBSD) The Er items in a Bl list are not in alphabetical order.
454
455     duplicate errno
456     (mdoc, NetBSD) A Bl list contains two consecutive It entries describing
457     the same Er number.
458
459     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
464     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
470     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
474     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
478     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
483     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
487     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
492     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
498   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
503     missing manual title, using ""
504     (man) There is no TH macro, or it has no arguments.
505
506     missing manual section, using ""
507     (mdoc, man) A Dt or TH macro lacks the mandatory section argument.
508
509     unknown manual section
510     (mdoc) The section number in a Dt line is invalid, but still used.
511
512     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
518     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
522     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
526     missing Os macro, using ""
527     (mdoc) The default or current system is not shown in this case.
528
529     late prologue macro
530     (mdoc) A Dd or Os macro occurs after some non-prologue macro, but still
531     takes effect.
532
533     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
537   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
542     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
546     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
551     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
555     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
559     NAME section without description
560     (mdoc) The NAME section lacks the mandatory Nd child macro.
561
562     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
566     bad NAME section content
567     (mdoc) The NAME section contains plain text or macros other than Nm and
568     Nd.
569
570     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
574     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
578     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
583     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
588     duplicate section title
589     (mdoc) The same standard section title occurs more than once.
590
591     unexpected section
592     (mdoc) A standard section header occurs in a section of the manual where
593     it normally isn't useful.
594
595     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
601     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
606     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
611     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
615   Warnings related to macros and nesting
616     obsolete macro
617     (mdoc) See the mdoc(7) manual for replacements.
618
619     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
624     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
635     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
639     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
643     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
651     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
655     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
659     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
663     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
668   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
674     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
690     skipping empty macro
691     (mdoc) The indicated macro has no arguments and hence no effect.
692
693     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
697     empty argument, using 0n
698     (mdoc) The required width is missing after Bd or Bl -offset or -width.
699
700     missing display type, using -ragged
701     (mdoc) The Bd macro is invoked without the required display type.
702
703     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
708     missing -width in -tag list, using 8n
709     (mdoc) Every Bl macro having the -tag argument requires -width, too.
710
711     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
715     missing function name, using ""
716     (mdoc) The Fo macro is called without an argument.  No function name is
717     printed.
718
719     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
723     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
727     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
732     missing font type, using \fR
733     (mdoc) A Bf macro has no argument.  It switches to the default font.
734
735     unknown font type, using \fR
736     (mdoc) The Bf argument is invalid.  The default font is used instead.
737
738     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
744     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
748     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
752     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
757     missing option string, using ""
758     (man) The OP macro is invoked without any argument.  An empty pair of
759     square brackets is shown.
760
761     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
765     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
769   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
775     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
779     skipping duplicate display type
780     (mdoc) A Bd macro has more than one type argument; the first one is used.
781
782     skipping duplicate list type
783     (mdoc) A Bl macro has more than one type argument; the first one is used.
784
785     skipping -width argument
786     (mdoc) A Bl -column, -diag, -ohang, -inset, or -item list has a -width
787     argument.  That has no effect.
788
789     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
795     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
799     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
803     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
808     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
812     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
816     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
821     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
825     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
829   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
836     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
844     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
848     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
855     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
860   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
866     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
871     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
876   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
882     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
886     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
891     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
895     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
900     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
905     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
910     tbl without any data cells
911     (tbl) A table does not contain any data cells.  It will probably produce
912     no output.
913
914     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
918     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
922     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
927   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
932     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
939     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
949     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
956     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
962     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
966     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
971     skipping column outside column list
972     (mdoc) A Ta macro occurs outside any Bl -column block.  It is discarded
973     including its arguments.
974
975     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
983     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
987     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
993     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
999     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
1014     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
1021     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
1026     missing list type, using -item
1027     (mdoc) A Bl macro fails to specify the list type.
1028
1029     argument is not numeric, using 1
1030     (roff) The argument of a ce request is not a number.
1031
1032     missing manual name, using ""
1033     (mdoc) The first call to Nm, or any call in the NAME section, lacks the
1034     required argument.
1035
1036     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
1041     unknown standard specifier
1042     (mdoc) An St macro has an unknown argument and is discarded.
1043
1044     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
1049     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
1057     .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
1062     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
1069     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
1080   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
1087     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
1092     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
1097     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
1101     unsupported table layout modifier
1102     (tbl) A table layout specification contains an ‘m’ modifier.  The modi‐
1103     fier is discarded.
1104
1105     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

SEE ALSO

1111     apropos(1), man(1), eqn(7), man(7), mandoc_char(7), mdoc(7), roff(7),
1112     tbl(7)
1113

HISTORY

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

AUTHORS

1119     The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1120     is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1121
1122BSD                              June 20, 2019                             BSD
Impressum