1 MANDOC(1) User Commands MANDOC(1)
2
3 NAME
4 mandoc - format manual pages
5
6 SYNOPSIS
7 mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
8 [-T output] [-W level] [file ...]
9
10 DESCRIPTION
11 The mandoc utility formats UNIX manual pages for display.
12
13 By default, mandoc reads mdoc(5) or man(5) text from stdin and produces
14 -T locale output.
15
16 The options are as follows:
17
18 -a If the standard output is a terminal device and -c is not
19 specified, use more(1) to paginate the output, just like man(1)
20 would.
21
22 -c Copy the formatted manual pages to the standard output without
23 using more(1) to paginate them. This is the default. It can be
24 specified to override -a.
25
26 -I os=name
27 Override the default operating system name for the mdoc(5) Os and
28 for the man(5) TH macro.
29
30 -K encoding
31 Specify the input encoding. The supported encoding arguments are
35 1. If the first three bytes of the input file are the UTF-8
36 byte order mark (BOM, 0xefbbbf), input is interpreted as
37 utf-8.
38
39 2. If the first or second line of the input file matches the
40 emacs mode line format
41
42 .\" -*- [...;] coding: encoding; -*-
43
44 then input is interpreted according to encoding.
45
46 3. If the first non-ASCII byte in the file introduces a valid
47 UTF-8 sequence, input is interpreted as utf-8.
48
49 4. Otherwise, input is interpreted as iso-8859-1.
50
51 -mdoc | -man
52 With -mdoc, all input files are interpreted as mdoc(5). With
53 -man, all input files are interpreted as man(5). By default, the
54 input language is automatically detected for each file: if the
55 the first macro is Dd or Dt, the mdoc(5) parser is used;
56 otherwise, the man(5) parser is used. With other arguments, -m
57 is silently ignored.
58
59 -O options
60 Comma-separated output options.
61
62 -T output
63 Output format. See Output Formats for available formats.
64 Defaults to -T locale.
65
66 -W level
67 Specify the minimum message level to be reported on the standard
68 error output and to affect the exit status. The level can be
69 base, style, warning, error, or unsupp. The base level
70 automatically derives the operating system from the contents of
71 the Os macro, from the -Ios command line option, or from the
72 uname(2) return value. The levels openbsd and netbsd are
73 variants of base that bypass autodetection and request validation
74 of base system conventions for a particular operating system.
75 The level all is an alias for base. By default, mandoc is
76 silent. See EXIT STATUS and DIAGNOSTICS for details.
77
78 The special option -W stop tells mandoc to exit after parsing a
79 file that causes warnings or errors of at least the requested
80 level. No formatted output will be produced from that file. If
81 both a level and stop are requested, they can be joined with a
82 comma, for example -W error,stop.
83
84 file Read input from zero or more files. If unspecified, reads from
85 stdin. If multiple files are specified, mandoc will halt with
86 the first failed parse.
87
88 Output Formats
89 The mandoc utility accepts the following -T arguments, which correspond
90 to output modes:
91
92 -T ascii Produce 7-bit ASCII output. See ASCII Output.
93
94 -T html Produce HTML5, CSS1, and MathML output. See HTML Output.
95
96 -Tlint Parse only: produce no output. Implies -W all and redirects
97 parser messages, which usually appear on standard error
98 output, to standard output.
99
100 -T locale Encode output using the current locale. This is the
101 default. See Locale Output.
102
103 -T man Produce man(5) format output. See Man Output.
104
105 -T markdown Produce output in markdown format. See Markdown Output.
106
107 -T pdf Produce PDF output. See PDF Output.
108
109 -T ps Produce PostScript output. See PostScript Output.
110
111 -T tree Produce an indented parse tree.
112
113 -T utf8 Encode output in the UTF-8 multi-byte format. See UTF-8
114 Output.
115
116 If multiple input files are specified, these will be processed by the
117 corresponding filter in-order.
118
119 ASCII Output
120 Output produced by -T ascii is rendered in standard 7-bit ASCII
121 documented in ascii(5).
122
123 Font styles are applied by using back-spaced encoding such that an
124 underlined character `c' is rendered as `_\[bs]c', where `\[bs]' is the
125 back-space character number 8. Emboldened characters are rendered as
126 `c\[bs]c'.
127
128 The special characters documented in mandoc_char(5) are rendered best-
129 effort in an ASCII equivalent.
130
131 Output width is limited to 78 visible columns unless literal input lines
132 exceed this limit.
133
134 The following -O arguments are accepted:
135
136 indent=indent
137 The left margin for normal text is set to indent blank characters
138 instead of the default of five for mdoc(5) and seven for man(5).
139 Increasing this is not recommended; it may result in degraded
140 formatting, for example overfull lines or ugly line breaks.
141
142 width=width
143 The output width is set to width.
144
145 HTML Output
146 Output produced by -T html conforms to HTML5 using optional self-closing
147 tags. Default styles use only CSS1. Equations rendered from eqn(5)
148 blocks use MathML.
149
150 The mandoc.css file documents style-sheet classes available for
151 customising output. If a style-sheet is not specified with -O style, -T
152 html defaults to simple output (via an embedded style-sheet) readable in
153 any graphical or text-based web browser.
154
155 Special characters are rendered in decimal-encoded UTF-8.
156
157 The following -O arguments are accepted:
158
159 fragment
160 Omit the <!DOCTYPE> declaration and the <html>, <head>, and
161 <body> elements and only emit the subtree below the <body>
162 element. The style argument will be ignored. This is useful
163 when embedding manual content within existing documents.
164
165 includes=fmt
166 The string fmt, for example, ../src/%I.html, is used as a
167 template for linked header files (usually via the In macro).
168 Instances of `%I' are replaced with the include filename. The
169 default is not to present a hyperlink.
170
171 man=fmt
172 The string fmt, for example, ../html%S/%N.%S.html, is used as a
173 template for linked manuals (usually via the Xr macro).
174 Instances of `%N' and `%S' are replaced with the linked manual's
175 name and section, respectively. If no section is included,
176 section 1 is assumed. The default is not to present a hyperlink.
177
178 style=style.css
179 The file style.css is used for an external style-sheet. This
180 must be a valid absolute or relative URI.
181
182 Locale Output
183 Locale-depending output encoding is triggered with -T locale. This is
184 the default.
185
186 Man Output
187 Translate input format into man(5) output format. This is useful for
188 distributing manual sources to legacy systems lacking mdoc(5) formatters.
189
190 If mdoc(5) is passed as input, it is translated into man(5). If the
191 input format is man(5), the input is copied to the output, expanding any
192 mandoc_roff(5) so requests. The parser is also run, and as usual, the -W
193 level controls which DIAGNOSTICS are displayed before copying the input
194 to the output.
195
196 Markdown Output
197 Translate mdoc(5) input to the markdown format conforming to John
198 Gruber's 2004 specification:
199 http://daringfireball.net/projects/markdown/syntax.text. The output also
200 almost conforms to the CommonMark: http://commonmark.org/ specification.
201
202 The character set used for the markdown output is ASCII. Non-ASCII
203 characters are encoded as HTML entities. Since that is not possible in
204 literal font contexts, because these are rendered as code spans and code
205 blocks in the markdown output, non-ASCII characters are transliterated to
206 ASCII approximations in these contexts.
207
208 Markdown is a very weak markup language, so all semantic markup is lost,
209 and even part of the presentational markup may be lost. Do not use this
210 as an intermediate step in converting to HTML; instead, use -T html
211 directly.
212
213 The man(5), tbl(5), and eqn(5) input languages are not supported by -T
214 markdown output mode.
215
216 PDF Output
217 PDF-1.1 output may be generated by -T pdf. See PostScript Output for -O
218 arguments and defaults.
219
220 PostScript Output
221 PostScript "Adobe-3.0" Level-2 pages may be generated by -T ps. Output
222 pages default to letter sized and are rendered in the Times font family,
223 11-point. Margins are calculated as 1/9 the page length and width.
224 Line-height is 1.4m.
225
226 Special characters are rendered as in ASCII Output.
227
228 The following -O arguments are accepted:
229
230 paper=name
231 The paper size name may be one of a3, a4, a5, legal, or letter.
232 You may also manually specify dimensions as NNxNN, width by
233 height in millimetres. If an unknown value is encountered,
234 letter is used.
235
236 UTF-8 Output
237 Use -T utf8 to force a UTF-8 locale. See Locale Output for details and
238 options.
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(5) prologue, on the
246 man(5) 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(5) nodes, the
252 content. There is a special format for eqn(5) 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
275 EXIT STATUS
276 The mandoc utility exits with one of the following values, controlled by
277 the message level associated with the -W option:
278
279 0 No base system convention violations, style suggestions,
280 warnings, or errors occurred, or those that did were ignored
281 because they were lower than the requested level.
282 1 At least one base system convention violation or style suggestion
283 occurred, but no warning or error, and -W base or -W style was
284 specified.
285 2 At least one warning occurred, but no error, and -W warning or a
286 lower level was requested.
287 3 At least one parsing error occurred, but no unsupported feature
288 was encountered, and -W error or a lower level was requested.
289 4 At least one unsupported feature was encountered, and -W unsupp
290 or a lower level was requested.
291 5 Invalid command line arguments were specified. No input files
292 have been read.
293 6 An operating system error occurred, for example exhaustion of
294 memory, file descriptors, or process table entries. Such errors
339 using GNU troff instead of mandoc to process the file may be
340 preferable.
341
342 error Indicates a risk of information loss or severe misformatting, in
343 most cases caused by serious syntax errors.
344
345 warning Indicates a risk that the information shown or its formatting
346 may mismatch the author's intent in minor ways. Additionally,
347 syntax errors are classified at least as warnings, even if they
348 do not usually cause misformatting.
349
350 style An input file uses dubious or discouraged style. This is not a
351 complaint about the syntax, and probably neither formatting nor
352 portability are in danger. While great care is taken to avoid
353 false positives on the higher message levels, the style level
354 tries to reduce the probability that issues go unnoticed, so it
355 may occasionally issue bogus suggestions. Please use your good
356 judgement to decide whether any particular style suggestion
357 really justifies a change to the input file.
358
359 base A convertion used in the base system of a specific operating
360 system is not adhered to. These are not markup mistakes, and
361 neither the quality of formatting nor portability are in danger.
362 Messages of the base level are printed with the more intuitive
363 style level tag.
364
365 Messages of the base, style, warning, error, and unsupp levels except
366 those about non-existent or unreadable input files are hidden unless
367 their level, or a lower level, is requested using a -W option or -T lint
368 output mode.
369
370 As indicated below, all base and some style checks are only performed if
371 a specific operating system name occurs in the arguments of the -W
372 command line option, of the Os macro, of the -Ios command line option,
373 or, if neither are present, in the return value of the uname(3) function.
374
375 Conventions for base system manuals
376 Mdocdate found
377 (mdoc, NetBSD) The Dd macro uses CVS Mdocdate keyword substitution, which
378 is not supported by the NetBSD base system. Consider using the
379 conventional "Month dd, yyyy" format instead.
390 operating system explicitly specified
391 (mdoc, OpenBSD, NetBSD) The Os macro has an argument. In the base
392 system, it is conventionally left blank.
393
394 RCS id missing
395 (OpenBSD, NetBSD) The manual page lacks the comment line with the RCS
396 identifier generated by CVS OpenBSD or NetBSD keyword substitution as
397 conventionally used in these operating systems.
398
399 referenced manual not found
400 (mdoc) An Xr macro references a manual page that is not found in the base
401 system. The path to look for base system manuals is configurable at
402 compile time and defaults to /usr/share/man: /usr/X11R6/man.
403
404 Style suggestions
405 legacy man(7) date format
406 (mdoc) The Dd macro uses the legacy man(5) date format "yyyy-dd-mm".
407 Consider using the conventional mdoc(5) date format "Month dd, yyyy"
408 instead.
409
410 lower case character in document title
411 (mdoc, man) The title is still used as given in the Dt or TH macro.
412
413 duplicate RCS id
414 A single manual page contains two copies of the RCS identifier for the
415 same operating system. Consider deleting the later instance and moving
416 the first one up to the top of the page.
417
418 typo in section name
419 (mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
420 similar, but not identical to a standard section name.
421
422 unterminated quoted argument
423 (roff) Macro arguments can be enclosed in double quote characters such
424 that space characters and macro names contained in the quoted argument
425 need not be escaped. The closing quote of the last argument of a macro
426 can be omitted. However, omitting it is not recommended because it makes
427 the code harder to read.
428
429 useless macro
430 (mdoc) A Bt, Tn, or Ud macro was found. Simply delete it: it serves no
431 useful purpose.
432
433 consider using OS macro
434 (mdoc) A string was found in plain text or in a Bx macro that could be
435 represented using Ox, Nx, Fx, or Dx.
436
437 errnos out of order
438 (mdoc, NetBSD) The Er items in a Bl list are not in alphabetical order.
443
444 trailing delimiter
445 (mdoc) The last argument of an Ex, Fo, Nd, Nm, Os, Sh, Ss, St, or Sx
446 macro ends with a trailing delimiter. This is usually bad style and
447 often indicates typos. Most likely, the delimiter can be removed.
448
449 no blank before trailing delimiter
450 (mdoc) The last argument of a macro that supports trailing delimiter
451 arguments is longer than one byte and ends with a trailing delimiter.
452 Consider inserting a blank such that the delimiter becomes a separate
453 argument, thus moving it out of the scope of the macro.
454
455 fill mode already enabled, skipping
456 (man) A fi request occurs even though the document is still in fill mode,
457 or already switched back to fill mode. It has no effect.
458
459 fill mode already disabled, skipping
460 (man) An nf request occurs even though the document already switched to
461 no-fill mode and did not switch back to fill mode yet. It has no effect.
462
463 function name without markup
464 (mdoc) A word followed by an empty pair of parentheses occurs on a text
465 line. Consider using an Fn or Xr macro.
466
467 whitespace at end of input line
468 (mdoc, man, roff) Whitespace at the end of input lines is almost never
469 semantically significant -- but in the odd case where it might be, it is
470 extremely confusing when reviewing and maintaining documents.
471
472 bad comment style
473 (roff) Comment lines start with a dot, a backslash, and a double-quote
474 character. The mandoc utility treats the line as a comment line even
475 without the backslash, but leaving out the backslash might not be
476 portable.
477
478 Warnings related to the document prologue
479 missing manual title, using UNTITLED
480 (mdoc) A Dt macro has no arguments, or there is no Dt macro before the
481 first non-prologue macro.
482
1084 unsupported table layout modifier
1085 (tbl) A table layout specification contains an `m' modifier. The
1086 modifier is discarded.
1087
1088 ignoring macro in table
1089 (tbl, mdoc, man) A table contains an invocation of an mdoc(5) or man(5)
1090 macro or of an undefined macro. The macro is ignored, and its arguments
1091 are handled as if they were a text line.
1092
1093 SEE ALSO
1094 eqn(5), man(5), mandoc_char(5), mandoc_roff(5), mdoc(5), tbl(5)
1095
1096 HISTORY
1097 The mandoc utility first appeared in OpenBSD 4.8. The option -I appeared
1098 in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
1099
1100 AUTHORS
1101 The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1102 is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1103
1104 illumos July 20, 2017 illumos
|
1 MANDOC(1) User Commands MANDOC(1)
2
3 NAME
4 mandoc - format manual pages
5
6 SYNOPSIS
7 mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
8 [-T output] [-W level] [file ...]
9
10 DESCRIPTION
11 The mandoc utility formats manual pages for display.
12
13 By default, mandoc reads mdoc(5) or man(5) text from stdin and produces
14 -T locale output.
15
16 The options are as follows:
17
18 -a If the standard output is a terminal device and -c is not
19 specified, use more(1) to paginate the output, just like man(1)
20 would.
21
22 -c Copy the formatted manual pages to the standard output without
23 using more(1) to paginate them. This is the default. It can be
24 specified to override -a.
25
26 -I os=name
27 Override the default operating system name for the mdoc(5) Os and
28 for the man(5) TH macro.
29
30 -K encoding
31 Specify the input encoding. The supported encoding arguments are
35 1. If the first three bytes of the input file are the UTF-8
36 byte order mark (BOM, 0xefbbbf), input is interpreted as
37 utf-8.
38
39 2. If the first or second line of the input file matches the
40 emacs mode line format
41
42 .\" -*- [...;] coding: encoding; -*-
43
44 then input is interpreted according to encoding.
45
46 3. If the first non-ASCII byte in the file introduces a valid
47 UTF-8 sequence, input is interpreted as utf-8.
48
49 4. Otherwise, input is interpreted as iso-8859-1.
50
51 -mdoc | -man
52 With -mdoc, all input files are interpreted as mdoc(5). With
53 -man, all input files are interpreted as man(5). By default, the
54 input language is automatically detected for each file: if the
55 first macro is Dd or Dt, the mdoc(5) parser is used; otherwise,
56 the man(5) parser is used. With other arguments, -m is silently
57 ignored.
58
59 -O options
60 Comma-separated output options. See the descriptions of the
61 individual output formats for supported options.
62
63 -T output
64 Select the output format. Supported values for the output
65 argument are ascii, html, the default of locale, man, markdown,
66 pdf, ps, tree, and utf8.
67
68 The special -T lint mode only parses the input and produces no
69 output. It implies -W all and redirects parser messages, which
70 usually appear on standard error output, to standard output.
71
72 -W level
73 Specify the minimum message level to be reported on the standard
74 error output and to affect the exit status. The level can be
75 base, style, warning, error, or unsupp. The base level
76 automatically derives the operating system from the contents of
77 the Os macro, from the -Ios command line option, or from the
78 uname(2) return value. The levels openbsd and netbsd are
79 variants of base that bypass autodetection and request validation
80 of base system conventions for a particular operating system.
81 The level all is an alias for base. By default, mandoc is
82 silent. See EXIT STATUS and DIAGNOSTICS for details.
83
84 The special option -W stop tells mandoc to exit after parsing a
85 file that causes warnings or errors of at least the requested
86 level. No formatted output will be produced from that file. If
87 both a level and stop are requested, they can be joined with a
88 comma, for example -W error,stop.
89
90 file Read from the given input file. If multiple files are specified,
91 they are processed in the given order. If unspecified, mandoc
92 reads from standard input.
93
94 ASCII Output
95 Use -T ascii to force text output in 7-bit ASCII character encoding
96 documented in the ascii(5) manual page, ignoring the locale(1) set in the
97 environment.
98
99 Font styles are applied by using back-spaced encoding such that an
100 underlined character `c' is rendered as `_\[bs]c', where `\[bs]' is the
101 back-space character number 8. Emboldened characters are rendered as
102 `c\[bs]c'.
103
104 The special characters documented in mandoc_char(5) are rendered best-
105 effort in an ASCII equivalent.
106
107 The following -O arguments are accepted:
108
109 indent=indent
110 The left margin for normal text is set to indent blank characters
111 instead of the default of five for mdoc(5) and seven for man(5).
112 Increasing this is not recommended; it may result in degraded
113 formatting, for example overfull lines or ugly line breaks. When
114 output is to a pager on a terminal that is less than 66 columns
115 wide, the default is reduced to three columns.
116
117 mdoc Format man(5) input files in mdoc(5) output style. Specifically,
118 this suppresses the two additional blank lines near the top and
119 the bottom of each page, and it implies -O indent=5. One useful
120 application is for checking that -T man output formats in the
121 same way as the mdoc(5) source it was generated from.
122
123 width=width
124 The output width is set to width instead of the default of 78.
125 When output is to a pager on a terminal that is less than 79
126 columns wide, the default is reduced to one less than the
127 terminal width. In any case, lines that are output in literal
128 mode are never wrapped and may exceed the output width.
129
130 HTML Output
131 Output produced by -T html conforms to HTML5 using optional self-closing
132 tags. Default styles use only CSS1. Equations rendered from eqn(5)
133 blocks use MathML.
134
135 The mandoc.css file documents style-sheet classes available for
136 customising output. If a style-sheet is not specified with -O style, -T
137 html defaults to simple output (via an embedded style-sheet) readable in
138 any graphical or text-based web browser.
139
140 Non-ASCII characters are rendered as hexadecimal Unicode character
141 references.
142
143 The following -O arguments are accepted:
144
145 fragment
146 Omit the <!DOCTYPE> declaration and the <html>, <head>, and
147 <body> elements and only emit the subtree below the <body>
148 element. The style argument will be ignored. This is useful
149 when embedding manual content within existing documents.
150
151 includes=fmt
152 The string fmt, for example, ../src/%I.html, is used as a
153 template for linked header files (usually via the In macro).
154 Instances of `%I' are replaced with the include filename. The
155 default is not to present a hyperlink.
156
157 man=fmt
158 The string fmt, for example, ../html%S/%N.%S.html, is used as a
159 template for linked manuals (usually via the Xr macro).
160 Instances of `%N' and `%S' are replaced with the linked manual's
161 name and section, respectively. If no section is included,
162 section 1 is assumed. The default is not to present a hyperlink.
163
164 style=style.css
165 The file style.css is used for an external style-sheet. This
166 must be a valid absolute or relative URI.
167
168 Locale Output
169 By default, mandoc automatically selects UTF-8 or ASCII output according
170 to the current locale(1). If any of the environment variables LC_ALL,
171 LC_CTYPE, or LANG are set and the first one that is set selects the UTF-8
172 character encoding, it produces UTF-8 Output; otherwise, it falls back to
173 ASCII Output. This output mode can also be selected explicitly with -T
174 locale.
175
176 Man Output
177 Use -T man to translate mdoc(5) input into man(5) output format. This is
178 useful for distributing manual sources to legacy systems lacking mdoc(5)
179 formatters.
180
181 If the input format of a file is man(5), the input is copied to the
182 output, expanding any mandoc_roff(5) so requests. The parser is also
183 run, and as usual, the -W level controls which DIAGNOSTICS are displayed
184 before copying the input to the output.
185
186 Markdown Output
187 Use -T markdown to translate mdoc(5) input to the markdown format
188 conforming to John Gruber's 2004 specification:
189 http://daringfireball.net/projects/markdown/syntax.text. The output also
190 almost conforms to the CommonMark: http://commonmark.org/ specification.
191
192 The character set used for the markdown output is ASCII. Non-ASCII
193 characters are encoded as HTML entities. Since that is not possible in
194 literal font contexts, because these are rendered as code spans and code
195 blocks in the markdown output, non-ASCII characters are transliterated to
196 ASCII approximations in these contexts.
197
198 Markdown is a very weak markup language, so all semantic markup is lost,
199 and even part of the presentational markup may be lost. Do not use this
200 as an intermediate step in converting to HTML; instead, use -T html
201 directly.
202
203 The man(5), tbl(5), and eqn(5) input languages are not supported by -T
204 markdown output mode.
205
206 PDF Output
207 PDF-1.1 output may be generated by -T pdf. See PostScript Output for -O
208 arguments and defaults.
209
210 PostScript Output
211 PostScript "Adobe-3.0" Level-2 pages may be generated by -T ps. Output
212 pages default to letter sized and are rendered in the Times font family,
213 11-point. Margins are calculated as 1/9 the page length and width.
214 Line-height is 1.4m.
215
216 Special characters are rendered as in ASCII Output.
217
218 The following -O arguments are accepted:
219
220 paper=name
221 The paper size name may be one of a3, a4, a5, legal, or letter.
222 You may also manually specify dimensions as NNxNN, width by
223 height in millimetres. If an unknown value is encountered,
224 letter is used.
225
226 UTF-8 Output
227 Use -T utf8 to force text output in UTF-8 multi-byte character encoding,
228 ignoring the locale(1) settings in the environment. See ASCII Output
229 regarding font styles and -O arguments.
230
231 On operating systems lacking locale or wide character support, and on
232 those where the internal character representation is not UCS-4, mandoc
233 always falls back to ASCII Output.
234
235 Syntax tree output
236 Use -T tree to show a human readable representation of the syntax tree.
237 It is useful for debugging the source code of manual pages. The exact
238 format is subject to change, so don't write parsers for it.
239
240 The first paragraph shows meta data found in the mdoc(5) prologue, on the
241 man(5) TH line, or the fallbacks used.
242
243 In the tree dump, each output line shows one syntax tree node. Child
244 nodes are indented with respect to their parent node. The columns are:
245
246 1. For macro nodes, the macro name; for text and tbl(5) nodes, the
247 content. There is a special format for eqn(5) nodes.
248 2. Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
249 3. Flags:
250 - An opening parenthesis if the node is an opening delimiter.
251 - An asterisk if the node starts a new input line.
252 - The input line number (starting at one).
253 - A colon.
254 - The input column number (starting at one).
255 - A closing parenthesis if the node is a closing delimiter.
256 - A full stop if the node ends a sentence.
257 - BROKEN if the node is a block broken by another block.
258 - NOSRC if the node is not in the input file, but automatically
259 generated from macros.
260 - NOPRT if the node is not supposed to generate output for any
261 output format.
262
263 The following -O argument is accepted:
264
265 noval Skip validation and show the unvalidated syntax tree. This can
266 help to find out whether a given behaviour is caused by the
267 parser or by the validator. Meta data is not available in this
268 case.
269
270 ENVIRONMENT
271 LC_CTYPE The character encoding locale(1). When Locale Output is
272 selected, it decides whether to use ASCII or UTF-8
273 output format. It never affects the interpretation of
274 input files.
275
276 EXIT STATUS
277 The mandoc utility exits with one of the following values, controlled by
278 the message level associated with the -W option:
279
280 0 No base system convention violations, style suggestions,
281 warnings, or errors occurred, or those that did were ignored
282 because they were lower than the requested level.
283 1 At least one base system convention violation or style suggestion
284 occurred, but no warning or error, and -W base or -W style was
285 specified.
286 2 At least one warning occurred, but no error, and -W warning or a
287 lower level was requested.
288 3 At least one parsing error occurred, but no unsupported feature
289 was encountered, and -W error or a lower level was requested.
290 4 At least one unsupported feature was encountered, and -W unsupp
291 or a lower level was requested.
292 5 Invalid command line arguments were specified. No input files
293 have been read.
294 6 An operating system error occurred, for example exhaustion of
295 memory, file descriptors, or process table entries. Such errors
340 using GNU troff instead of mandoc to process the file may be
341 preferable.
342
343 error Indicates a risk of information loss or severe misformatting, in
344 most cases caused by serious syntax errors.
345
346 warning Indicates a risk that the information shown or its formatting
347 may mismatch the author's intent in minor ways. Additionally,
348 syntax errors are classified at least as warnings, even if they
349 do not usually cause misformatting.
350
351 style An input file uses dubious or discouraged style. This is not a
352 complaint about the syntax, and probably neither formatting nor
353 portability are in danger. While great care is taken to avoid
354 false positives on the higher message levels, the style level
355 tries to reduce the probability that issues go unnoticed, so it
356 may occasionally issue bogus suggestions. Please use your good
357 judgement to decide whether any particular style suggestion
358 really justifies a change to the input file.
359
360 base A convention used in the base system of a specific operating
361 system is not adhered to. These are not markup mistakes, and
362 neither the quality of formatting nor portability are in danger.
363 Messages of the base level are printed with the more intuitive
364 style level tag.
365
366 Messages of the base, style, warning, error, and unsupp levels except
367 those about non-existent or unreadable input files are hidden unless
368 their level, or a lower level, is requested using a -W option or -T lint
369 output mode.
370
371 As indicated below, all base and some style checks are only performed if
372 a specific operating system name occurs in the arguments of the -W
373 command line option, of the Os macro, of the -Ios command line option,
374 or, if neither are present, in the return value of the uname(3) function.
375
376 Conventions for base system manuals
377 Mdocdate found
378 (mdoc, NetBSD) The Dd macro uses CVS Mdocdate keyword substitution, which
379 is not supported by the NetBSD base system. Consider using the
380 conventional "Month dd, yyyy" format instead.
391 operating system explicitly specified
392 (mdoc, OpenBSD, NetBSD) The Os macro has an argument. In the base
393 system, it is conventionally left blank.
394
395 RCS id missing
396 (OpenBSD, NetBSD) The manual page lacks the comment line with the RCS
397 identifier generated by CVS OpenBSD or NetBSD keyword substitution as
398 conventionally used in these operating systems.
399
400 referenced manual not found
401 (mdoc) An Xr macro references a manual page that is not found in the base
402 system. The path to look for base system manuals is configurable at
403 compile time and defaults to /usr/share/man: /usr/X11R6/man.
404
405 Style suggestions
406 legacy man(7) date format
407 (mdoc) The Dd macro uses the legacy man(5) date format "yyyy-dd-mm".
408 Consider using the conventional mdoc(5) date format "Month dd, yyyy"
409 instead.
410
411 normalizing date format to: ...
412 (mdoc, man) The Dd or TH macro provides an abbreviated month name or a
413 day number with a leading zero. In the formatted output, the month name
414 is written out in full and the leading zero is omitted.
415
416 lower case character in document title
417 (mdoc, man) The title is still used as given in the Dt or TH macro.
418
419 duplicate RCS id
420 A single manual page contains two copies of the RCS identifier for the
421 same operating system. Consider deleting the later instance and moving
422 the first one up to the top of the page.
423
424 possible typo in section name
425 (mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
426 similar, but not identical to a standard section name.
427
428 unterminated quoted argument
429 (roff) Macro arguments can be enclosed in double quote characters such
430 that space characters and macro names contained in the quoted argument
431 need not be escaped. The closing quote of the last argument of a macro
432 can be omitted. However, omitting it is not recommended because it makes
433 the code harder to read.
434
435 useless macro
436 (mdoc) A Bt, Tn, or Ud macro was found. Simply delete it: it serves no
437 useful purpose.
438
439 consider using OS macro
440 (mdoc) A string was found in plain text or in a Bx macro that could be
441 represented using Ox, Nx, Fx, or Dx.
442
443 errnos out of order
444 (mdoc, NetBSD) The Er items in a Bl list are not in alphabetical order.
449
450 trailing delimiter
451 (mdoc) The last argument of an Ex, Fo, Nd, Nm, Os, Sh, Ss, St, or Sx
452 macro ends with a trailing delimiter. This is usually bad style and
453 often indicates typos. Most likely, the delimiter can be removed.
454
455 no blank before trailing delimiter
456 (mdoc) The last argument of a macro that supports trailing delimiter
457 arguments is longer than one byte and ends with a trailing delimiter.
458 Consider inserting a blank such that the delimiter becomes a separate
459 argument, thus moving it out of the scope of the macro.
460
461 fill mode already enabled, skipping
462 (man) A fi request occurs even though the document is still in fill mode,
463 or already switched back to fill mode. It has no effect.
464
465 fill mode already disabled, skipping
466 (man) An nf request occurs even though the document already switched to
467 no-fill mode and did not switch back to fill mode yet. It has no effect.
468
469 verbatim "--", maybe consider using \(em
470 (mdoc) Even though the ASCII output device renders an em-dash as "--",
471 that is not a good way to write it in an input file because it renders
472 poorly on all other output devices.
473
474 function name without markup
475 (mdoc) A word followed by an empty pair of parentheses occurs on a text
476 line. Consider using an Fn or Xr macro.
477
478 whitespace at end of input line
479 (mdoc, man, roff) Whitespace at the end of input lines is almost never
480 semantically significant -- but in the odd case where it might be, it is
481 extremely confusing when reviewing and maintaining documents.
482
483 bad comment style
484 (roff) Comment lines start with a dot, a backslash, and a double-quote
485 character. The mandoc utility treats the line as a comment line even
486 without the backslash, but leaving out the backslash might not be
487 portable.
488
489 Warnings related to the document prologue
490 missing manual title, using UNTITLED
491 (mdoc) A Dt macro has no arguments, or there is no Dt macro before the
492 first non-prologue macro.
493
1095 unsupported table layout modifier
1096 (tbl) A table layout specification contains an `m' modifier. The
1097 modifier is discarded.
1098
1099 ignoring macro in table
1100 (tbl, mdoc, man) A table contains an invocation of an mdoc(5) or man(5)
1101 macro or of an undefined macro. The macro is ignored, and its arguments
1102 are handled as if they were a text line.
1103
1104 SEE ALSO
1105 eqn(5), man(5), mandoc_char(5), mandoc_roff(5), mdoc(5), tbl(5)
1106
1107 HISTORY
1108 The mandoc utility first appeared in OpenBSD 4.8. The option -I appeared
1109 in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
1110
1111 AUTHORS
1112 The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1113 is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1114
1115 illumos July 28, 2018 illumos
|