Print this page
9718 update mandoc to 1.14.4
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1/mandoc.1.man.txt
+++ new/usr/src/man/man1/mandoc.1.man.txt
1 1 MANDOC(1) User Commands MANDOC(1)
2 2
3 3 NAME
4 4 mandoc - format manual pages
5 5
6 6 SYNOPSIS
7 7 mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
8 8 [-T output] [-W level] [file ...]
9 9
10 10 DESCRIPTION
11 - The mandoc utility formats UNIX manual pages for display.
11 + The mandoc utility formats manual pages for display.
12 12
13 13 By default, mandoc reads mdoc(5) or man(5) text from stdin and produces
14 14 -T locale output.
15 15
16 16 The options are as follows:
17 17
18 18 -a If the standard output is a terminal device and -c is not
19 19 specified, use more(1) to paginate the output, just like man(1)
20 20 would.
21 21
22 22 -c Copy the formatted manual pages to the standard output without
23 23 using more(1) to paginate them. This is the default. It can be
24 24 specified to override -a.
25 25
26 26 -I os=name
27 27 Override the default operating system name for the mdoc(5) Os and
28 28 for the man(5) TH macro.
29 29
30 30 -K encoding
31 31 Specify the input encoding. The supported encoding arguments are
32 32 us-ascii, iso-8859-1, and utf-8. If not specified, autodetection
33 33 uses the first match in the following list:
34 34
35 35 1. If the first three bytes of the input file are the UTF-8
36 36 byte order mark (BOM, 0xefbbbf), input is interpreted as
37 37 utf-8.
38 38
39 39 2. If the first or second line of the input file matches the
40 40 emacs mode line format
41 41
42 42 .\" -*- [...;] coding: encoding; -*-
43 43
44 44 then input is interpreted according to encoding.
|
↓ open down ↓ |
23 lines elided |
↑ open up ↑ |
45 45
46 46 3. If the first non-ASCII byte in the file introduces a valid
47 47 UTF-8 sequence, input is interpreted as utf-8.
48 48
49 49 4. Otherwise, input is interpreted as iso-8859-1.
50 50
51 51 -mdoc | -man
52 52 With -mdoc, all input files are interpreted as mdoc(5). With
53 53 -man, all input files are interpreted as man(5). By default, the
54 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.
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 58
59 59 -O options
60 - Comma-separated output options.
60 + Comma-separated output options. See the descriptions of the
61 + individual output formats for supported options.
61 62
62 63 -T output
63 - Output format. See Output Formats for available formats.
64 - Defaults to -T locale.
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.
65 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 +
66 72 -W level
67 73 Specify the minimum message level to be reported on the standard
68 74 error output and to affect the exit status. The level can be
69 75 base, style, warning, error, or unsupp. The base level
70 76 automatically derives the operating system from the contents of
71 77 the Os macro, from the -Ios command line option, or from the
72 78 uname(2) return value. The levels openbsd and netbsd are
73 79 variants of base that bypass autodetection and request validation
74 80 of base system conventions for a particular operating system.
75 81 The level all is an alias for base. By default, mandoc is
76 82 silent. See EXIT STATUS and DIAGNOSTICS for details.
77 83
78 84 The special option -W stop tells mandoc to exit after parsing a
79 85 file that causes warnings or errors of at least the requested
80 86 level. No formatted output will be produced from that file. If
81 87 both a level and stop are requested, they can be joined with a
82 88 comma, for example -W error,stop.
83 89
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.
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.
87 93
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 94 ASCII Output
120 - Output produced by -T ascii is rendered in standard 7-bit ASCII
121 - documented in ascii(5).
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.
122 98
123 99 Font styles are applied by using back-spaced encoding such that an
124 100 underlined character `c' is rendered as `_\[bs]c', where `\[bs]' is the
125 101 back-space character number 8. Emboldened characters are rendered as
126 102 `c\[bs]c'.
127 103
128 104 The special characters documented in mandoc_char(5) are rendered best-
129 105 effort in an ASCII equivalent.
130 106
131 - Output width is limited to 78 visible columns unless literal input lines
132 - exceed this limit.
133 -
134 107 The following -O arguments are accepted:
135 108
136 109 indent=indent
137 110 The left margin for normal text is set to indent blank characters
138 111 instead of the default of five for mdoc(5) and seven for man(5).
139 112 Increasing this is not recommended; it may result in degraded
140 - formatting, for example overfull lines or ugly line breaks.
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.
141 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 +
142 123 width=width
143 - The output width is set to 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.
144 129
145 130 HTML Output
146 131 Output produced by -T html conforms to HTML5 using optional self-closing
147 132 tags. Default styles use only CSS1. Equations rendered from eqn(5)
148 133 blocks use MathML.
149 134
150 135 The mandoc.css file documents style-sheet classes available for
151 136 customising output. If a style-sheet is not specified with -O style, -T
152 137 html defaults to simple output (via an embedded style-sheet) readable in
153 138 any graphical or text-based web browser.
154 139
155 - Special characters are rendered in decimal-encoded UTF-8.
140 + Non-ASCII characters are rendered as hexadecimal Unicode character
141 + references.
156 142
157 143 The following -O arguments are accepted:
158 144
159 145 fragment
160 146 Omit the <!DOCTYPE> declaration and the <html>, <head>, and
161 147 <body> elements and only emit the subtree below the <body>
162 148 element. The style argument will be ignored. This is useful
163 149 when embedding manual content within existing documents.
164 150
165 151 includes=fmt
166 152 The string fmt, for example, ../src/%I.html, is used as a
167 153 template for linked header files (usually via the In macro).
168 154 Instances of `%I' are replaced with the include filename. The
169 155 default is not to present a hyperlink.
170 156
171 157 man=fmt
172 158 The string fmt, for example, ../html%S/%N.%S.html, is used as a
|
↓ open down ↓ |
7 lines elided |
↑ open up ↑ |
173 159 template for linked manuals (usually via the Xr macro).
174 160 Instances of `%N' and `%S' are replaced with the linked manual's
175 161 name and section, respectively. If no section is included,
176 162 section 1 is assumed. The default is not to present a hyperlink.
177 163
178 164 style=style.css
179 165 The file style.css is used for an external style-sheet. This
180 166 must be a valid absolute or relative URI.
181 167
182 168 Locale Output
183 - Locale-depending output encoding is triggered with -T locale. This is
184 - the default.
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.
185 175
186 176 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.
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.
189 180
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.
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.
195 185
196 186 Markdown Output
197 - Translate mdoc(5) input to the markdown format conforming to John
198 - Gruber's 2004 specification:
187 + Use -T markdown to translate mdoc(5) input to the markdown format
188 + conforming to John Gruber's 2004 specification:
199 189 http://daringfireball.net/projects/markdown/syntax.text. The output also
200 190 almost conforms to the CommonMark: http://commonmark.org/ specification.
201 191
202 192 The character set used for the markdown output is ASCII. Non-ASCII
203 193 characters are encoded as HTML entities. Since that is not possible in
204 194 literal font contexts, because these are rendered as code spans and code
205 195 blocks in the markdown output, non-ASCII characters are transliterated to
206 196 ASCII approximations in these contexts.
207 197
208 198 Markdown is a very weak markup language, so all semantic markup is lost,
209 199 and even part of the presentational markup may be lost. Do not use this
210 200 as an intermediate step in converting to HTML; instead, use -T html
211 201 directly.
212 202
213 203 The man(5), tbl(5), and eqn(5) input languages are not supported by -T
214 204 markdown output mode.
215 205
216 206 PDF Output
217 207 PDF-1.1 output may be generated by -T pdf. See PostScript Output for -O
218 208 arguments and defaults.
219 209
220 210 PostScript Output
221 211 PostScript "Adobe-3.0" Level-2 pages may be generated by -T ps. Output
222 212 pages default to letter sized and are rendered in the Times font family,
223 213 11-point. Margins are calculated as 1/9 the page length and width.
224 214 Line-height is 1.4m.
225 215
226 216 Special characters are rendered as in ASCII Output.
|
↓ open down ↓ |
18 lines elided |
↑ open up ↑ |
227 217
228 218 The following -O arguments are accepted:
229 219
230 220 paper=name
231 221 The paper size name may be one of a3, a4, a5, legal, or letter.
232 222 You may also manually specify dimensions as NNxNN, width by
233 223 height in millimetres. If an unknown value is encountered,
234 224 letter is used.
235 225
236 226 UTF-8 Output
237 - Use -T utf8 to force a UTF-8 locale. See Locale Output for details and
238 - options.
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.
239 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 +
240 235 Syntax tree output
241 236 Use -T tree to show a human readable representation of the syntax tree.
242 237 It is useful for debugging the source code of manual pages. The exact
243 238 format is subject to change, so don't write parsers for it.
244 239
245 240 The first paragraph shows meta data found in the mdoc(5) prologue, on the
246 241 man(5) TH line, or the fallbacks used.
247 242
248 243 In the tree dump, each output line shows one syntax tree node. Child
249 244 nodes are indented with respect to their parent node. The columns are:
250 245
251 246 1. For macro nodes, the macro name; for text and tbl(5) nodes, the
252 247 content. There is a special format for eqn(5) nodes.
253 248 2. Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
254 249 3. Flags:
255 250 - An opening parenthesis if the node is an opening delimiter.
256 251 - An asterisk if the node starts a new input line.
257 252 - The input line number (starting at one).
258 253 - A colon.
259 254 - The input column number (starting at one).
260 255 - A closing parenthesis if the node is a closing delimiter.
261 256 - A full stop if the node ends a sentence.
262 257 - BROKEN if the node is a block broken by another block.
263 258 - NOSRC if the node is not in the input file, but automatically
264 259 generated from macros.
|
↓ open down ↓ |
15 lines elided |
↑ open up ↑ |
265 260 - NOPRT if the node is not supposed to generate output for any
266 261 output format.
267 262
268 263 The following -O argument is accepted:
269 264
270 265 noval Skip validation and show the unvalidated syntax tree. This can
271 266 help to find out whether a given behaviour is caused by the
272 267 parser or by the validator. Meta data is not available in this
273 268 case.
274 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 +
275 276 EXIT STATUS
276 277 The mandoc utility exits with one of the following values, controlled by
277 278 the message level associated with the -W option:
278 279
279 280 0 No base system convention violations, style suggestions,
280 281 warnings, or errors occurred, or those that did were ignored
281 282 because they were lower than the requested level.
282 283 1 At least one base system convention violation or style suggestion
283 284 occurred, but no warning or error, and -W base or -W style was
284 285 specified.
285 286 2 At least one warning occurred, but no error, and -W warning or a
286 287 lower level was requested.
287 288 3 At least one parsing error occurred, but no unsupported feature
288 289 was encountered, and -W error or a lower level was requested.
289 290 4 At least one unsupported feature was encountered, and -W unsupp
290 291 or a lower level was requested.
291 292 5 Invalid command line arguments were specified. No input files
292 293 have been read.
293 294 6 An operating system error occurred, for example exhaustion of
294 295 memory, file descriptors, or process table entries. Such errors
295 296 cause mandoc to exit at once, possibly in the middle of parsing
296 297 or formatting a file.
297 298
298 299 Note that selecting -T lint output mode implies -W all.
299 300
300 301 EXAMPLES
301 302 To page manuals to the terminal:
302 303
303 304 $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
304 305
305 306 To produce HTML manuals with mandoc.css as the style-sheet:
306 307
307 308 $ mandoc -T html -Ostyle=mandoc.css mdoc.5 > mdoc.5.html
308 309
309 310 To check over a large set of manuals:
310 311
311 312 $ mandoc -T lint `find /usr/src -name \*\.[1-9]`
312 313
313 314 To produce a series of PostScript manuals for A4 paper:
314 315
315 316 $ mandoc -T ps -O paper=a4 mdoc.5 man.5 > manuals.ps
316 317
317 318 Convert a modern mdoc(5) manual to the older man(5) format, for use on
318 319 systems lacking an mdoc(5) parser:
319 320
320 321 $ mandoc -T man foo.mdoc > foo.man
321 322
322 323 DIAGNOSTICS
323 324 Messages displayed by mandoc follow this format:
324 325
325 326 mandoc: file:line:column: level: message: macro args (os)
326 327
327 328 Line and column numbers start at 1. Both are omitted for messages
328 329 referring to an input file as a whole. Macro names and arguments are
329 330 omitted where meaningless. The os operating system specifier is omitted
330 331 for messages that are relevant for all operating systems. Fatal messages
331 332 about invalid command line arguments or operating system errors, for
332 333 example when memory is exhausted, may also omit the file and level
333 334 fields.
334 335
335 336 Message levels have the following meanings:
336 337
337 338 unsupp An input file uses unsupported low-level mandoc_roff(5)
338 339 features. The output may be incomplete and/or misformatted, so
339 340 using GNU troff instead of mandoc to process the file may be
340 341 preferable.
341 342
342 343 error Indicates a risk of information loss or severe misformatting, in
343 344 most cases caused by serious syntax errors.
344 345
345 346 warning Indicates a risk that the information shown or its formatting
346 347 may mismatch the author's intent in minor ways. Additionally,
347 348 syntax errors are classified at least as warnings, even if they
348 349 do not usually cause misformatting.
|
↓ open down ↓ |
64 lines elided |
↑ open up ↑ |
349 350
350 351 style An input file uses dubious or discouraged style. This is not a
351 352 complaint about the syntax, and probably neither formatting nor
352 353 portability are in danger. While great care is taken to avoid
353 354 false positives on the higher message levels, the style level
354 355 tries to reduce the probability that issues go unnoticed, so it
355 356 may occasionally issue bogus suggestions. Please use your good
356 357 judgement to decide whether any particular style suggestion
357 358 really justifies a change to the input file.
358 359
359 - base A convertion used in the base system of a specific operating
360 + base A convention used in the base system of a specific operating
360 361 system is not adhered to. These are not markup mistakes, and
361 362 neither the quality of formatting nor portability are in danger.
362 363 Messages of the base level are printed with the more intuitive
363 364 style level tag.
364 365
365 366 Messages of the base, style, warning, error, and unsupp levels except
366 367 those about non-existent or unreadable input files are hidden unless
367 368 their level, or a lower level, is requested using a -W option or -T lint
368 369 output mode.
369 370
370 371 As indicated below, all base and some style checks are only performed if
371 372 a specific operating system name occurs in the arguments of the -W
372 373 command line option, of the Os macro, of the -Ios command line option,
373 374 or, if neither are present, in the return value of the uname(3) function.
374 375
375 376 Conventions for base system manuals
376 377 Mdocdate found
377 378 (mdoc, NetBSD) The Dd macro uses CVS Mdocdate keyword substitution, which
378 379 is not supported by the NetBSD base system. Consider using the
379 380 conventional "Month dd, yyyy" format instead.
380 381
381 382 Mdocdate missing
382 383 (mdoc, OpenBSD) The Dd macro does not use CVS Mdocdate keyword
383 384 substitution, but using it is conventionally expected in the OpenBSD base
384 385 system.
385 386
386 387 unknown architecture
387 388 (mdoc, OpenBSD, NetBSD) The third argument of the Dt macro does not match
388 389 any of the architectures this operating system is running on.
389 390
390 391 operating system explicitly specified
391 392 (mdoc, OpenBSD, NetBSD) The Os macro has an argument. In the base
392 393 system, it is conventionally left blank.
393 394
394 395 RCS id missing
395 396 (OpenBSD, NetBSD) The manual page lacks the comment line with the RCS
396 397 identifier generated by CVS OpenBSD or NetBSD keyword substitution as
397 398 conventionally used in these operating systems.
398 399
399 400 referenced manual not found
|
↓ open down ↓ |
30 lines elided |
↑ open up ↑ |
400 401 (mdoc) An Xr macro references a manual page that is not found in the base
401 402 system. The path to look for base system manuals is configurable at
402 403 compile time and defaults to /usr/share/man: /usr/X11R6/man.
403 404
404 405 Style suggestions
405 406 legacy man(7) date format
406 407 (mdoc) The Dd macro uses the legacy man(5) date format "yyyy-dd-mm".
407 408 Consider using the conventional mdoc(5) date format "Month dd, yyyy"
408 409 instead.
409 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 +
410 416 lower case character in document title
411 417 (mdoc, man) The title is still used as given in the Dt or TH macro.
412 418
413 419 duplicate RCS id
414 420 A single manual page contains two copies of the RCS identifier for the
415 421 same operating system. Consider deleting the later instance and moving
416 422 the first one up to the top of the page.
417 423
418 - typo in section name
424 + possible typo in section name
419 425 (mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
420 426 similar, but not identical to a standard section name.
421 427
422 428 unterminated quoted argument
423 429 (roff) Macro arguments can be enclosed in double quote characters such
424 430 that space characters and macro names contained in the quoted argument
425 431 need not be escaped. The closing quote of the last argument of a macro
426 432 can be omitted. However, omitting it is not recommended because it makes
427 433 the code harder to read.
428 434
429 435 useless macro
430 436 (mdoc) A Bt, Tn, or Ud macro was found. Simply delete it: it serves no
431 437 useful purpose.
432 438
433 439 consider using OS macro
434 440 (mdoc) A string was found in plain text or in a Bx macro that could be
435 441 represented using Ox, Nx, Fx, or Dx.
436 442
437 443 errnos out of order
438 444 (mdoc, NetBSD) The Er items in a Bl list are not in alphabetical order.
439 445
440 446 duplicate errno
441 447 (mdoc, NetBSD) A Bl list contains two consecutive It entries describing
442 448 the same Er number.
443 449
444 450 trailing delimiter
445 451 (mdoc) The last argument of an Ex, Fo, Nd, Nm, Os, Sh, Ss, St, or Sx
446 452 macro ends with a trailing delimiter. This is usually bad style and
447 453 often indicates typos. Most likely, the delimiter can be removed.
448 454
449 455 no blank before trailing delimiter
450 456 (mdoc) The last argument of a macro that supports trailing delimiter
451 457 arguments is longer than one byte and ends with a trailing delimiter.
452 458 Consider inserting a blank such that the delimiter becomes a separate
|
↓ open down ↓ |
24 lines elided |
↑ open up ↑ |
453 459 argument, thus moving it out of the scope of the macro.
454 460
455 461 fill mode already enabled, skipping
456 462 (man) A fi request occurs even though the document is still in fill mode,
457 463 or already switched back to fill mode. It has no effect.
458 464
459 465 fill mode already disabled, skipping
460 466 (man) An nf request occurs even though the document already switched to
461 467 no-fill mode and did not switch back to fill mode yet. It has no effect.
462 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 +
463 474 function name without markup
464 475 (mdoc) A word followed by an empty pair of parentheses occurs on a text
465 476 line. Consider using an Fn or Xr macro.
466 477
467 478 whitespace at end of input line
468 479 (mdoc, man, roff) Whitespace at the end of input lines is almost never
469 480 semantically significant -- but in the odd case where it might be, it is
470 481 extremely confusing when reviewing and maintaining documents.
471 482
472 483 bad comment style
473 484 (roff) Comment lines start with a dot, a backslash, and a double-quote
474 485 character. The mandoc utility treats the line as a comment line even
475 486 without the backslash, but leaving out the backslash might not be
476 487 portable.
477 488
478 489 Warnings related to the document prologue
479 490 missing manual title, using UNTITLED
480 491 (mdoc) A Dt macro has no arguments, or there is no Dt macro before the
481 492 first non-prologue macro.
482 493
483 494 missing manual title, using ""
484 495 (man) There is no TH macro, or it has no arguments.
485 496
486 497 missing manual section, using ""
487 498 (mdoc, man) A Dt or TH macro lacks the mandatory section argument.
488 499
489 500 unknown manual section
490 501 (mdoc) The section number in a Dt line is invalid, but still used.
491 502
492 503 missing date, using today's date
493 504 (mdoc, man) The document was parsed as mdoc(5) and it has no Dd macro, or
494 505 the Dd macro has no arguments or only empty arguments; or the document
495 506 was parsed as man(5) and it has no TH macro, or the TH macro has less
496 507 than three arguments or its third argument is empty.
497 508
498 509 cannot parse date, using it verbatim
499 510 (mdoc, man) The date given in a Dd or TH macro does not follow the
500 511 conventional format.
501 512
502 513 date in the future, using it anyway
503 514 (mdoc, man) The date given in a Dd or TH macro is more than a day ahead
504 515 of the current system time(3).
505 516
506 517 missing Os macro, using ""
507 518 (mdoc) The default or current system is not shown in this case.
508 519
509 520 late prologue macro
510 521 (mdoc) A Dd or Os macro occurs after some non-prologue macro, but still
511 522 takes effect.
512 523
513 524 prologue macros out of order
514 525 (mdoc) The prologue macros are not given in the conventional order Dd,
515 526 Dt, Os. All three macros are used even when given in another order.
516 527
517 528 Warnings regarding document structure
518 529 .so is fragile, better use ln(1)
519 530 (roff) Including files only works when the parser program runs with the
520 531 correct current working directory.
521 532
522 533 no document body
523 534 (mdoc, man) The document body contains neither text nor macros. An empty
524 535 document is shown, consisting only of a header and a footer line.
525 536
526 537 content before first section header
527 538 (mdoc, man) Some macros or text precede the first Sh or SH section
528 539 header. The offending macros and text are parsed and added to the top
529 540 level of the syntax tree, outside any section block.
530 541
531 542 first section is not NAME
532 543 (mdoc) The argument of the first Sh macro is not `NAME'. This may
533 544 confuse apropos(1) or confuse man(1) when updating the whatis(1)
534 545 database.
535 546
536 547 NAME section without Nm before Nd
537 548 (mdoc) The NAME section does not contain any Nm child macro before the
538 549 first Nd macro.
539 550
540 551 NAME section without description
541 552 (mdoc) The NAME section lacks the mandatory Nd child macro.
542 553
543 554 description not at the end of NAME
544 555 (mdoc) The NAME section does contain an Nd child macro, but other content
545 556 follows it.
546 557
547 558 bad NAME section content
548 559 (mdoc) The NAME section contains plain text or macros other than Nm and
549 560 Nd.
550 561
551 562 missing comma before name
552 563 (mdoc) The NAME section contains an Nm macro that is neither the first
553 564 one nor preceded by a comma.
554 565
555 566 missing description line, using ""
556 567 (mdoc) The Nd macro lacks the required argument. The title line of the
557 568 manual will end after the dash.
558 569
559 570 description line outside NAME section
560 571 (mdoc) An Nd macro appears outside the NAME section. The arguments are
561 572 printed anyway and the following text is used for apropos(1), but none of
562 573 that behaviour is portable.
563 574
564 575 sections out of conventional order
565 576 (mdoc) A standard section occurs after another section it usually
566 577 precedes. All section titles are used as given, and the order of
567 578 sections is not changed.
568 579
569 580 duplicate section title
570 581 (mdoc) The same standard section title occurs more than once.
571 582
572 583 unexpected section
573 584 (mdoc) A standard section header occurs in a section of the manual where
574 585 it normally isn't useful.
575 586
576 587 cross reference to self
577 588 (mdoc) An Xr macro refers to a name and section matching the section of
578 589 the present manual page and a name mentioned in an Nm macro in the NAME
579 590 or SYNOPSIS section, or in an Fn or Fo macro in the SYNOPSIS. Consider
580 591 using Nm or Fn instead of Xr.
581 592
582 593 unusual Xr order
583 594 (mdoc) In the SEE ALSO section, an Xr macro with a lower section number
584 595 follows one with a higher number, or two Xr macros referring to the same
585 596 section are out of alphabetical order.
586 597
587 598 unusual Xr punctuation
588 599 (mdoc) In the SEE ALSO section, punctuation between two Xr macros differs
589 600 from a single comma, or there is trailing punctuation after the last Xr
590 601 macro.
591 602
592 603 AUTHORS section without An macro
593 604 (mdoc) An AUTHORS sections contains no An macros, or only empty ones.
594 605 Probably, there are author names lacking markup.
595 606
596 607 Warnings related to macros and nesting
597 608 obsolete macro
598 609 (mdoc) See the mdoc(5) manual for replacements.
599 610
600 611 macro neither callable nor escaped
601 612 (mdoc) The name of a macro that is not callable appears on a macro line.
602 613 It is printed verbatim. If the intention is to call it, move it to its
603 614 own input line; otherwise, escape it by prepending `\&'.
604 615
605 616 skipping paragraph macro
606 617 In mdoc(5) documents, this happens
607 618 - at the beginning and end of sections and subsections
608 619 - right before non-compact lists and displays
609 620 - at the end of items in non-column, non-compact lists
610 621 - and for multiple consecutive paragraph macros.
611 622 In man(5) documents, it happens
612 623 - for empty P, PP, and LP macros
613 624 - for IP macros having neither head nor body arguments
614 625 - for br or sp right after SH or SS
615 626
616 627 moving paragraph macro out of list
617 628 (mdoc) A list item in a Bl list contains a trailing paragraph macro. The
618 629 paragraph macro is moved after the end of the list.
619 630
620 631 skipping no-space macro
621 632 (mdoc) An input line begins with an Ns macro, or the next argument after
622 633 an Ns macro is an isolated closing delimiter. The macro is ignored.
623 634
624 635 blocks badly nested
625 636 (mdoc) If two blocks intersect, one should completely contain the other.
626 637 Otherwise, rendered output is likely to look strange in any output
627 638 format, and rendering in SGML-based output formats is likely to be
628 639 outright wrong because such languages do not support badly nested blocks
629 640 at all. Typical examples of badly nested blocks are "Ao Bo Ac Bc" and
630 641 "Ao Bq Ac". In these examples, Ac breaks Bo and Bq, respectively.
631 642
632 643 nested displays are not portable
633 644 (mdoc) A Bd, D1, or Dl display occurs nested inside another Bd display.
634 645 This works with mandoc, but fails with most other implementations.
635 646
636 647 moving content out of list
637 648 (mdoc) A Bl list block contains text or macros before the first It macro.
638 649 The offending children are moved before the beginning of the list.
639 650
640 651 first macro on line
641 652 Inside a Bl -column list, a Ta macro occurs as the first macro on a line,
642 653 which is not portable.
643 654
644 655 line scope broken
645 656 (man) While parsing the next-line scope of the previous macro, another
646 657 macro is found that prematurely terminates the previous one. The
647 658 previous, interrupted macro is deleted from the parse tree.
648 659
649 660 Warnings related to missing arguments
650 661 skipping empty request
651 662 (roff, eqn) The macro name is missing from a macro definition request, or
652 663 an eqn(5) control statement or operation keyword lacks its required
653 664 argument.
654 665
655 666 conditional request controls empty scope
656 667 (roff) A conditional request is only useful if any of the following
657 668 follows it on the same logical input line:
658 669 - The `\{' keyword to open a multi-line scope.
659 670 - A request or macro or some text, resulting in a single-line scope.
660 671 - The immediate end of the logical line without any intervening
661 672 whitespace, resulting in next-line scope.
662 673 Here, a conditional request is followed by trailing whitespace only, and
663 674 there is no other content on its logical input line. Note that it
664 675 doesn't matter whether the logical input line is split across multiple
665 676 physical input lines using `\' line continuation characters. This is one
666 677 of the rare cases where trailing whitespace is syntactically significant.
667 678 The conditional request controls a scope containing whitespace only, so
668 679 it is unlikely to have a significant effect, except that it may control a
669 680 following el clause.
670 681
671 682 skipping empty macro
672 683 (mdoc) The indicated macro has no arguments and hence no effect.
673 684
674 685 empty block
675 686 (mdoc, man) A Bd, Bk, Bl, D1, Dl, MT, RS, or UR block contains nothing in
676 687 its body and will produce no output.
677 688
678 689 empty argument, using 0n
679 690 (mdoc) The required width is missing after Bd or Bl -offset or -width.
680 691
681 692 missing display type, using -ragged
682 693 (mdoc) The Bd macro is invoked without the required display type.
683 694
684 695 list type is not the first argument
685 696 (mdoc) In a Bl macro, at least one other argument precedes the type
686 697 argument. The mandoc utility copes with any argument order, but some
687 698 other mdoc(5) implementations do not.
688 699
689 700 missing -width in -tag list, using 8n
690 701 (mdoc) Every Bl macro having the -tag argument requires -width, too.
691 702
692 703 missing utility name, using ""
693 704 (mdoc) The Ex -std macro is called without an argument before Nm has
694 705 first been called with an argument.
695 706
696 707 missing function name, using ""
697 708 (mdoc) The Fo macro is called without an argument. No function name is
698 709 printed.
699 710
700 711 empty head in list item
701 712 (mdoc) In a Bl -diag, -hang, -inset, -ohang, or -tag list, an It macro
702 713 lacks the required argument. The item head is left empty.
703 714
704 715 empty list item
705 716 (mdoc) In a Bl -bullet, -dash, -enum, or -hyphen list, an It block is
706 717 empty. An empty list item is shown.
707 718
708 719 missing argument, using next line
709 720 (mdoc) An It macro in a Bd -column list has no arguments. While mandoc
710 721 uses the text or macros of the following line, if any, for the cell,
711 722 other formatters may misformat the list.
712 723
713 724 missing font type, using \fR
714 725 (mdoc) A Bf macro has no argument. It switches to the default font.
715 726
716 727 unknown font type, using \fR
717 728 (mdoc) The Bf argument is invalid. The default font is used instead.
718 729
719 730 nothing follows prefix
720 731 (mdoc) A Pf macro has no argument, or only one argument and no macro
721 732 follows on the same input line. This defeats its purpose; in particular,
722 733 spacing is not suppressed before the text or macros following on the next
723 734 input line.
724 735
725 736 empty reference block
726 737 (mdoc) An Rs macro is immediately followed by an Re macro on the next
727 738 input line. Such an empty block does not produce any output.
728 739
729 740 missing section argument
730 741 (mdoc) An Xr macro lacks its second, section number argument. The first
731 742 argument, i.e. the name, is printed, but without subsequent parentheses.
732 743
733 744 missing -std argument, adding it
734 745 (mdoc) An Ex or Rv macro lacks the required -std argument. The mandoc
735 746 utility assumes -std even when it is not specified, but other
736 747 implementations may not.
737 748
738 749 missing option string, using ""
739 750 (man) The OP macro is invoked without any argument. An empty pair of
740 751 square brackets is shown.
741 752
742 753 missing resource identifier, using ""
743 754 (man) The MT or UR macro is invoked without any argument. An empty pair
744 755 of angle brackets is shown.
745 756
746 757 missing eqn box, using ""
747 758 (eqn) A diacritic mark or a binary operator is found, but there is
748 759 nothing to the left of it. An empty box is inserted.
749 760
750 761 Warnings related to bad macro arguments
751 762 duplicate argument
752 763 (mdoc) A Bd or Bl macro has more than one -compact, more than one
753 764 -offset, or more than one -width argument. All but the last instances of
754 765 these arguments are ignored.
755 766
756 767 skipping duplicate argument
757 768 (mdoc) An An macro has more than one -split or -nosplit argument. All
758 769 but the first of these arguments are ignored.
759 770
760 771 skipping duplicate display type
761 772 (mdoc) A Bd macro has more than one type argument; the first one is used.
762 773
763 774 skipping duplicate list type
764 775 (mdoc) A Bl macro has more than one type argument; the first one is used.
765 776
766 777 skipping -width argument
767 778 (mdoc) A Bl -column, -diag, -ohang, -inset, or -item list has a -width
768 779 argument. That has no effect.
769 780
770 781 wrong number of cells
771 782 In a line of a Bl -column list, the number of tabs or Ta macros is less
772 783 than the number expected from the list header line or exceeds the
773 784 expected number by more than one. Missing cells remain empty, and all
774 785 cells exceeding the number of columns are joined into one single cell.
775 786
776 787 unknown AT&T UNIX version
777 788 (mdoc) An At macro has an invalid argument. It is used verbatim, with
778 789 "AT&T UNIX " prefixed to it.
779 790
780 791 comma in function argument
781 792 (mdoc) An argument of an Fa or Fn macro contains a comma; it should
782 793 probably be split into two arguments.
783 794
784 795 parenthesis in function name
785 796 (mdoc) The first argument of an Fc or Fn macro contains an opening or
786 797 closing parenthesis; that's probably wrong, parentheses are added
787 798 automatically.
788 799
789 800 unknown library name
790 801 (mdoc, not on OpenBSD) An Lb macro has an unknown name argument and will
791 802 be rendered as "library "name"".
792 803
793 804 invalid content in Rs block
794 805 (mdoc) An Rs block contains plain text or non-% macros. The bogus
795 806 content is left in the syntax tree. Formatting may be poor.
796 807
797 808 invalid Boolean argument
798 809 (mdoc) An Sm macro has an argument other than on or off. The invalid
799 810 argument is moved out of the macro, which leaves the macro empty, causing
800 811 it to toggle the spacing mode.
801 812
802 813 unknown font, skipping request
803 814 (man, tbl) A mandoc_roff(5) ft request or a tbl(5) f layout modifier has
804 815 an unknown font argument.
805 816
806 817 odd number of characters in request
807 818 (roff) A tr request contains an odd number of characters. The last
808 819 character is mapped to the blank character.
809 820
810 821 Warnings related to plain text
811 822 blank line in fill mode, using .sp
812 823 (mdoc) The meaning of blank input lines is only well-defined in non-fill
813 824 mode: In fill mode, line breaks of text input lines are not supposed to
814 825 be significant. However, for compatibility with groff, blank lines in
815 826 fill mode are replaced with sp requests.
816 827
817 828 tab in filled text
818 829 (mdoc, man) The meaning of tab characters is only well-defined in non-
819 830 fill mode: In fill mode, whitespace is not supposed to be significant on
820 831 text input lines. As an implementation dependent choice, tab characters
821 832 on text lines are passed through to the formatters in any case. Given
822 833 that the text before the tab character will be filled, it is hard to
823 834 predict which tab stop position the tab will advance to.
824 835
825 836 new sentence, new line
826 837 (mdoc) A new sentence starts in the middle of a text line. Start it on a
827 838 new input line to help formatters produce correct spacing.
828 839
829 840 invalid escape sequence
830 841 (roff) An escape sequence has an invalid opening argument delimiter,
831 842 lacks the closing argument delimiter, or the argument has too few
832 843 characters. If the argument is incomplete, \* and \n expand to an empty
833 844 string, \B to the digit `0', and \w to the length of the incomplete
834 845 argument. All other invalid escape sequences are ignored.
835 846
836 847 undefined string, using ""
837 848 (roff) If a string is used without being defined before, its value is
838 849 implicitly set to the empty string. However, defining strings explicitly
839 850 before use keeps the code more readable.
840 851
841 852 Warnings related to tables
842 853 tbl line starts with span
843 854 (tbl) The first cell in a table layout line is a horizontal span (`s').
844 855 Data provided for this cell is ignored, and nothing is printed in the
845 856 cell.
846 857
847 858 tbl column starts with span
848 859 (tbl) The first line of a table layout specification requests a vertical
849 860 span (`^'). Data provided for this cell is ignored, and nothing is
850 861 printed in the cell.
851 862
852 863 skipping vertical bar in tbl layout
853 864 (tbl) A table layout specification contains more than two consecutive
854 865 vertical bars. A double bar is printed, all additional bars are
855 866 discarded.
856 867
857 868 Errors related to tables
858 869 non-alphabetic character in tbl options
859 870 (tbl) The table options line contains a character other than a letter,
860 871 blank, or comma where the beginning of an option name is expected. The
861 872 character is ignored.
862 873
863 874 skipping unknown tbl option
864 875 (tbl) The table options line contains a string of letters that does not
865 876 match any known option name. The word is ignored.
866 877
867 878 missing tbl option argument
868 879 (tbl) A table option that requires an argument is not followed by an
869 880 opening parenthesis, or the opening parenthesis is immediately followed
870 881 by a closing parenthesis. The option is ignored.
871 882
872 883 wrong tbl option argument size
873 884 (tbl) A table option argument contains an invalid number of characters.
874 885 Both the option and the argument are ignored.
875 886
876 887 empty tbl layout
877 888 (tbl) A table layout specification is completely empty, specifying zero
878 889 lines and zero columns. As a fallback, a single left-justified column is
879 890 used.
880 891
881 892 invalid character in tbl layout
882 893 (tbl) A table layout specification contains a character that can neither
883 894 be interpreted as a layout key character nor as a layout modifier, or a
884 895 modifier precedes the first key. The invalid character is discarded.
885 896
886 897 unmatched parenthesis in tbl layout
887 898 (tbl) A table layout specification contains an opening parenthesis, but
888 899 no matching closing parenthesis. The rest of the input line, starting
889 900 from the parenthesis, has no effect.
890 901
891 902 tbl without any data cells
892 903 (tbl) A table does not contain any data cells. It will probably produce
893 904 no output.
894 905
895 906 ignoring data in spanned tbl cell
896 907 (tbl) A table cell is marked as a horizontal span (`s') or vertical span
897 908 (`^') in the table layout, but it contains data. The data is ignored.
898 909
899 910 ignoring extra tbl data cells
900 911 (tbl) A data line contains more cells than the corresponding layout line.
901 912 The data in the extra cells is ignored.
902 913
903 914 data block open at end of tbl
904 915 (tbl) A data block is opened with T{, but never closed with a matching
905 916 T}. The remaining data lines of the table are all put into one cell, and
906 917 any remaining cells stay empty.
907 918
908 919 Errors related to roff, mdoc, and man code
909 920 duplicate prologue macro
910 921 (mdoc) One of the prologue macros occurs more than once. The last
911 922 instance overrides all previous ones.
912 923
913 924 skipping late title macro
914 925 (mdoc) The Dt macro appears after the first non-prologue macro.
915 926 Traditional formatters cannot handle this because they write the page
916 927 header before parsing the document body. Even though this technical
917 928 restriction does not apply to mandoc, traditional semantics is preserved.
918 929 The late macro is discarded including its arguments.
919 930
920 931 input stack limit exceeded, infinite loop?
921 932 (roff) Explicit recursion limits are implemented for the following
922 933 features, in order to prevent infinite loops:
923 934 - expansion of nested escape sequences including expansion of strings
924 935 and number registers,
925 936 - expansion of nested user-defined macros,
926 937 - and so file inclusion.
927 938 When a limit is hit, the output is incorrect, typically losing some
928 939 content, but the parser can continue.
929 940
930 941 skipping bad character
931 942 (mdoc, man, roff) The input file contains a byte that is not a printable
932 943 ascii(5) character. The message mentions the character number. The
933 944 offending byte is replaced with a question mark (`?'). Consider editing
934 945 the input file to replace the byte with an ASCII transliteration of the
935 946 intended character.
936 947
937 948 skipping unknown macro
938 949 (mdoc, man, roff) The first identifier on a request or macro line is
939 950 neither recognized as a mandoc_roff(5) request, nor as a user-defined
940 951 macro, nor, respectively, as an mdoc(5) or man(5) macro. It may be
941 952 mistyped or unsupported. The request or macro is discarded including its
942 953 arguments.
943 954
944 955 skipping insecure request
945 956 (roff) An input file attempted to run a shell command or to read or write
946 957 an external file. Such attempts are denied for security reasons.
947 958
948 959 skipping item outside list
949 960 (mdoc, eqn) An It macro occurs outside any Bl list, or an eqn(5) above
950 961 delimiter occurs outside any pile. It is discarded including its
951 962 arguments.
952 963
953 964 skipping column outside column list
954 965 (mdoc) A Ta macro occurs outside any Bl -column block. It is discarded
955 966 including its arguments.
956 967
957 968 skipping end of block that is not open
958 969 (mdoc, man, eqn, tbl, roff) Various syntax elements can only be used to
959 970 explicitly close blocks that have previously been opened. An mdoc(5)
960 971 block closing macro, a man(5) ME, RE or UE macro, an eqn(5) right
961 972 delimiter or closing brace, or the end of an equation, table, or
962 973 mandoc_roff(5) conditional request is encountered but no matching block
963 974 is open. The offending request or macro is discarded.
964 975
965 976 fewer RS blocks open, skipping
966 977 (man) The RE macro is invoked with an argument, but less than the
967 978 specified number of RS blocks is open. The RE macro is discarded.
968 979
969 980 inserting missing end of block
970 981 (mdoc, tbl) Various mdoc(5) macros as well as tables require explicit
971 982 closing by dedicated macros. A block that doesn't support bad nesting
972 983 ends before all of its children are properly closed. The open child
973 984 nodes are closed implicitly.
974 985
975 986 appending missing end of block
976 987 (mdoc, man, eqn, tbl, roff) At the end of the document, an explicit
977 988 mdoc(5) block, a man(5) next-line scope or MT, RS or UR block, an
978 989 equation, table, or mandoc_roff(5) conditional or ignore block is still
979 990 open. The open block is closed implicitly.
980 991
981 992 escaped character not allowed in a name
982 993 (roff) Macro, string and register identifiers consist of printable, non-
983 994 whitespace ASCII characters. Escape sequences and characters and strings
984 995 expressed in terms of them cannot form part of a name. The first
985 996 argument of an am, as, de, ds, nr, or rr request, or any argument of an
986 997 rm request, or the name of a request or user defined macro being called,
987 998 is terminated by an escape sequence. In the cases of as, ds, and nr, the
988 999 request has no effect at all. In the cases of am, de, rr, and rm, what
989 1000 was parsed up to this point is used as the arguments to the request, and
990 1001 the rest of the input line is discarded including the escape sequence.
991 1002 When parsing for a request or a user-defined macro name to be called,
992 1003 only the escape sequence is discarded. The characters preceding it are
993 1004 used as the request or macro name, the characters following it are used
994 1005 as the arguments to the request or macro.
995 1006
996 1007 NOT IMPLEMENTED: Bd -file
997 1008 (mdoc) For security reasons, the Bd macro does not support the -file
998 1009 argument. By requesting the inclusion of a sensitive file, a malicious
999 1010 document might otherwise trick a privileged user into inadvertently
1000 1011 displaying the file on the screen, revealing the file content to
1001 1012 bystanders. The argument is ignored including the file name following
1002 1013 it.
1003 1014
1004 1015 skipping display without arguments
1005 1016 (mdoc) A Bd block macro does not have any arguments. The block is
1006 1017 discarded, and the block content is displayed in whatever mode was active
1007 1018 before the block.
1008 1019
1009 1020 missing list type, using -item
1010 1021 (mdoc) A Bl macro fails to specify the list type.
1011 1022
1012 1023 argument is not numeric, using 1
1013 1024 (roff) The argument of a ce request is not a number.
1014 1025
1015 1026 missing manual name, using ""
1016 1027 (mdoc) The first call to Nm, or any call in the NAME section, lacks the
1017 1028 required argument.
1018 1029
1019 1030 uname(3) system call failed, using UNKNOWN
1020 1031 (mdoc) The Os macro is called without arguments, and the uname(3) system
1021 1032 call failed. As a workaround, mandoc can be compiled with
1022 1033 -DOSNAME="\"string\"".
1023 1034
1024 1035 unknown standard specifier
1025 1036 (mdoc) An St macro has an unknown argument and is discarded.
1026 1037
1027 1038 skipping request without numeric argument
1028 1039 (roff, eqn) An it request or an eqn(5) size or gsize statement has a non-
1029 1040 numeric or negative argument or no argument at all. The invalid request
1030 1041 or statement is ignored.
1031 1042
1032 1043 NOT IMPLEMENTED: .so with absolute path or ".."
1033 1044 (roff) For security reasons, mandoc allows so file inclusion requests
1034 1045 only with relative paths and only without ascending to any parent
1035 1046 directory. By requesting the inclusion of a sensitive file, a malicious
1036 1047 document might otherwise trick a privileged user into inadvertently
1037 1048 displaying the file on the screen, revealing the file content to
1038 1049 bystanders. mandoc only shows the path as it appears behind so.
1039 1050
1040 1051 .so request failed
1041 1052 (roff) Servicing a so request requires reading an external file, but the
1042 1053 file could not be opened. mandoc only shows the path as it appears
1043 1054 behind so.
1044 1055
1045 1056 skipping all arguments
1046 1057 (mdoc, man, eqn, roff) An mdoc(5) Bt, Ed, Ef, Ek, El, Lp, Pp, Re, Rs, or
1047 1058 Ud macro, an It macro in a list that don't support item heads, a man(5)
1048 1059 LP, P, or PP macro, an eqn(5) EQ or EN macro, or a mandoc_roff(5) br, fi,
1049 1060 or nf request or `..' block closing request is invoked with at least one
1050 1061 argument. All arguments are ignored.
1051 1062
1052 1063 skipping excess arguments
1053 1064 (mdoc, man, roff) A macro or request is invoked with too many arguments:
1054 1065 - Fo, MT, PD, RS, UR, ft, or sp with more than one argument
1055 1066 - An with another argument after -split or -nosplit
1056 1067 - RE with more than one argument or with a non-integer argument
1057 1068 - OP or a request of the de family with more than two arguments
1058 1069 - Dt with more than three arguments
1059 1070 - TH with more than five arguments
1060 1071 - Bd, Bk, or Bl with invalid arguments
1061 1072 The excess arguments are ignored.
1062 1073
1063 1074 Unsupported features
1064 1075 input too large
1065 1076 (mdoc, man) Currently, mandoc cannot handle input files larger than its
1066 1077 arbitrary size limit of 2^31 bytes (2 Gigabytes). Since useful manuals
1067 1078 are always small, this is not a problem in practice. Parsing is aborted
1068 1079 as soon as the condition is detected.
1069 1080
1070 1081 unsupported control character
1071 1082 (roff) An ASCII control character supported by other mandoc_roff(5)
1072 1083 implementations but not by mandoc was found in an input file. It is
1073 1084 replaced by a question mark.
1074 1085
1075 1086 unsupported roff request
1076 1087 (roff) An input file contains a mandoc_roff(5) request supported by GNU
1077 1088 troff or Heirloom troff but not by mandoc, and it is likely that this
1078 1089 will cause information loss or considerable misformatting.
1079 1090
1080 1091 eqn delim option in tbl
1081 1092 (eqn, tbl) The options line of a table defines equation delimiters. Any
1082 1093 equation source code contained in the table will be printed unformatted.
1083 1094
1084 1095 unsupported table layout modifier
1085 1096 (tbl) A table layout specification contains an `m' modifier. The
1086 1097 modifier is discarded.
1087 1098
1088 1099 ignoring macro in table
1089 1100 (tbl, mdoc, man) A table contains an invocation of an mdoc(5) or man(5)
1090 1101 macro or of an undefined macro. The macro is ignored, and its arguments
1091 1102 are handled as if they were a text line.
1092 1103
1093 1104 SEE ALSO
|
↓ open down ↓ |
621 lines elided |
↑ open up ↑ |
1094 1105 eqn(5), man(5), mandoc_char(5), mandoc_roff(5), mdoc(5), tbl(5)
1095 1106
1096 1107 HISTORY
1097 1108 The mandoc utility first appeared in OpenBSD 4.8. The option -I appeared
1098 1109 in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
1099 1110
1100 1111 AUTHORS
1101 1112 The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1102 1113 is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1103 1114
1104 -illumos July 20, 2017 illumos
1115 +illumos July 28, 2018 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX