Print this page
9718 update mandoc to 1.14.4
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1/mandoc.1
+++ new/usr/src/man/man1/mandoc.1
1 -.\" $Id: mandoc.1,v 1.217 2017/07/20 15:26:41 schwarze Exp $
1 +.\" $Id: mandoc.1,v 1.226 2018/07/28 18:34:15 schwarze Exp $
2 2 .\"
3 3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 -.\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
4 +.\" Copyright (c) 2012, 2014-2018 Ingo Schwarze <schwarze@openbsd.org>
5 5 .\"
6 6 .\" Permission to use, copy, modify, and distribute this software for any
7 7 .\" purpose with or without fee is hereby granted, provided that the above
8 8 .\" copyright notice and this permission notice appear in all copies.
9 9 .\"
10 10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17 .\"
18 -.Dd $Mdocdate: July 20 2017 $
18 +.Dd $Mdocdate: July 28 2018 $
19 19 .Dt MANDOC 1
20 20 .Os
21 21 .Sh NAME
22 22 .Nm mandoc
23 23 .Nd format manual pages
24 24 .Sh SYNOPSIS
25 25 .Nm mandoc
26 26 .Op Fl ac
27 27 .Op Fl I Cm os Ns = Ns Ar name
28 28 .Op Fl K Ar encoding
29 29 .Op Fl mdoc | man
30 30 .Op Fl O Ar options
31 31 .Op Fl T Ar output
32 32 .Op Fl W Ar level
33 33 .Op Ar
34 34 .Sh DESCRIPTION
35 35 The
36 36 .Nm
37 -utility formats
38 -.Ux
39 -manual pages for display.
37 +utility formats manual pages for display.
40 38 .Pp
41 39 By default,
42 40 .Nm
43 41 reads
44 42 .Xr mdoc 5
45 43 or
46 44 .Xr man 5
47 45 text from stdin and produces
48 46 .Fl T Cm locale
49 47 output.
50 48 .Pp
51 49 The options are as follows:
52 50 .Bl -tag -width Ds
53 51 .It Fl a
54 52 If the standard output is a terminal device and
55 53 .Fl c
56 54 is not specified, use
57 55 .Xr more 1
58 56 to paginate the output, just like
59 57 .Xr man 1
60 58 would.
61 59 .It Fl c
62 60 Copy the formatted manual pages to the standard output without using
63 61 .Xr more 1
64 62 to paginate them.
65 63 This is the default.
66 64 It can be specified to override
67 65 .Fl a .
68 66 .It Fl I Cm os Ns = Ns Ar name
69 67 Override the default operating system
70 68 .Ar name
71 69 for the
72 70 .Xr mdoc 5
73 71 .Ic \&Os
74 72 and for the
75 73 .Xr man 5
76 74 .Ic \&TH
77 75 macro.
78 76 .It Fl K Ar encoding
79 77 Specify the input encoding.
80 78 The supported
81 79 .Ar encoding
82 80 arguments are
83 81 .Cm us-ascii ,
84 82 .Cm iso-8859-1 ,
85 83 and
86 84 .Cm utf-8 .
87 85 If not specified, autodetection uses the first match in the following
88 86 list:
89 87 .Bl -enum
90 88 .It
91 89 If the first three bytes of the input file are the UTF-8 byte order
92 90 mark (BOM, 0xefbbbf), input is interpreted as
93 91 .Cm utf-8 .
94 92 .It
95 93 If the first or second line of the input file matches the
96 94 .Sy emacs
97 95 mode line format
98 96 .Pp
99 97 .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
100 98 .Pp
101 99 then input is interpreted according to
102 100 .Ar encoding .
103 101 .It
104 102 If the first non-ASCII byte in the file introduces a valid UTF-8
105 103 sequence, input is interpreted as
106 104 .Cm utf-8 .
107 105 .It
108 106 Otherwise, input is interpreted as
109 107 .Cm iso-8859-1 .
110 108 .El
|
↓ open down ↓ |
61 lines elided |
↑ open up ↑ |
111 109 .It Fl mdoc | man
112 110 With
113 111 .Fl mdoc ,
114 112 all input files are interpreted as
115 113 .Xr mdoc 5 .
116 114 With
117 115 .Fl man ,
118 116 all input files are interpreted as
119 117 .Xr man 5 .
120 118 By default, the input language is automatically detected for each file:
121 -if the the first macro is
119 +if the first macro is
122 120 .Ic \&Dd
123 121 or
124 122 .Ic \&Dt ,
125 123 the
126 124 .Xr mdoc 5
127 125 parser is used; otherwise, the
128 126 .Xr man 5
129 127 parser is used.
130 128 With other arguments,
131 129 .Fl m
132 130 is silently ignored.
133 131 .It Fl O Ar options
134 132 Comma-separated output options.
133 +See the descriptions of the individual output formats for supported
134 +.Ar options .
135 135 .It Fl T Ar output
136 -Output format.
137 -See
138 -.Sx Output Formats
139 -for available formats.
140 -Defaults to
141 -.Fl T Cm locale .
136 +Select the output format.
137 +Supported values for the
138 +.Ar output
139 +argument are
140 +.Cm ascii ,
141 +.Cm html ,
142 +the default of
143 +.Cm locale ,
144 +.Cm man ,
145 +.Cm markdown ,
146 +.Cm pdf ,
147 +.Cm ps ,
148 +.Cm tree ,
149 +and
150 +.Cm utf8 .
151 +.Pp
152 +The special
153 +.Fl T Cm lint
154 +mode only parses the input and produces no output.
155 +It implies
156 +.Fl W Cm all
157 +and redirects parser messages, which usually appear on standard
158 +error output, to standard output.
142 159 .It Fl W Ar level
143 160 Specify the minimum message
144 161 .Ar level
145 162 to be reported on the standard error output and to affect the exit status.
146 163 The
147 164 .Ar level
148 165 can be
149 166 .Cm base ,
150 167 .Cm style ,
151 168 .Cm warning ,
152 169 .Cm error ,
153 170 or
154 171 .Cm unsupp .
155 172 The
156 173 .Cm base
157 174 level automatically derives the operating system from the contents of the
158 175 .Ic \&Os
159 176 macro, from the
160 177 .Fl Ios
161 178 command line option, or from the
162 179 .Xr uname 2
163 180 return value.
164 181 The levels
165 182 .Cm openbsd
166 183 and
167 184 .Cm netbsd
168 185 are variants of
169 186 .Cm base
170 187 that bypass autodetection and request validation of base system
171 188 conventions for a particular operating system.
172 189 The level
173 190 .Cm all
174 191 is an alias for
175 192 .Cm base .
176 193 By default,
177 194 .Nm
178 195 is silent.
179 196 See
180 197 .Sx EXIT STATUS
181 198 and
182 199 .Sx DIAGNOSTICS
183 200 for details.
184 201 .Pp
185 202 The special option
186 203 .Fl W Cm stop
187 204 tells
188 205 .Nm
|
↓ open down ↓ |
37 lines elided |
↑ open up ↑ |
189 206 to exit after parsing a file that causes warnings or errors of at least
190 207 the requested level.
191 208 No formatted output will be produced from that file.
192 209 If both a
193 210 .Ar level
194 211 and
195 212 .Cm stop
196 213 are requested, they can be joined with a comma, for example
197 214 .Fl W Cm error , Ns Cm stop .
198 215 .It Ar file
199 -Read input from zero or more files.
200 -If unspecified, reads from stdin.
201 -If multiple files are specified,
216 +Read from the given input file.
217 +If multiple files are specified, they are processed in the given order.
218 +If unspecified,
202 219 .Nm
203 -will halt with the first failed parse.
220 +reads from standard input.
204 221 .El
205 -.Ss Output Formats
206 -The
207 -.Nm
208 -utility accepts the following
209 -.Fl T
210 -arguments, which correspond to output modes:
211 -.Bl -tag -width "-T markdown"
212 -.It Fl T Cm ascii
213 -Produce 7-bit ASCII output.
214 -See
215 -.Sx ASCII Output .
216 -.It Fl T Cm html
217 -Produce HTML5, CSS1, and MathML output.
218 -See
219 -.Sx HTML Output .
220 -.It Fl T Ns Cm lint
221 -Parse only: produce no output.
222 -Implies
223 -.Fl W Cm all
224 -and redirects parser messages, which usually appear
225 -on standard error output, to standard output.
226 -.It Fl T Cm locale
227 -Encode output using the current locale.
228 -This is the default.
229 -See
230 -.Sx Locale Output .
231 -.It Fl T Cm man
232 -Produce
233 -.Xr man 5
234 -format output.
235 -See
236 -.Sx Man Output .
237 -.It Fl T Cm markdown
238 -Produce output in
239 -.Sy markdown
240 -format.
241 -See
242 -.Sx Markdown Output .
243 -.It Fl T Cm pdf
244 -Produce PDF output.
245 -See
246 -.Sx PDF Output .
247 -.It Fl T Cm ps
248 -Produce PostScript output.
249 -See
250 -.Sx PostScript Output .
251 -.It Fl T Cm tree
252 -Produce an indented parse tree.
253 -.It Fl T Cm utf8
254 -Encode output in the UTF\-8 multi-byte format.
255 -See
256 -.Sx UTF\-8 Output .
257 -.El
258 -.Pp
259 -If multiple input files are specified, these will be processed by the
260 -corresponding filter in-order.
261 222 .Ss ASCII Output
262 -Output produced by
223 +Use
263 224 .Fl T Cm ascii
264 -is rendered in standard 7-bit ASCII documented in
265 -.Xr ascii 5 .
225 +to force text output in 7-bit ASCII character encoding documented in the
226 +.Xr ascii 5
227 +manual page, ignoring the
228 +.Xr locale 1
229 +set in the environment.
266 230 .Pp
267 231 Font styles are applied by using back-spaced encoding such that an
268 232 underlined character
269 233 .Sq c
270 234 is rendered as
271 235 .Sq _ Ns \e[bs] Ns c ,
272 236 where
273 237 .Sq \e[bs]
274 238 is the back-space character number 8.
275 239 Emboldened characters are rendered as
276 240 .Sq c Ns \e[bs] Ns c .
277 241 .Pp
278 242 The special characters documented in
279 243 .Xr mandoc_char 5
280 244 are rendered best-effort in an ASCII equivalent.
281 245 .Pp
282 -Output width is limited to 78 visible columns unless literal input lines
283 -exceed this limit.
284 -.Pp
285 246 The following
286 247 .Fl O
287 248 arguments are accepted:
288 249 .Bl -tag -width Ds
289 250 .It Cm indent Ns = Ns Ar indent
290 251 The left margin for normal text is set to
291 252 .Ar indent
292 253 blank characters instead of the default of five for
293 254 .Xr mdoc 5
294 255 and seven for
295 256 .Xr man 5 .
296 257 Increasing this is not recommended; it may result in degraded formatting,
297 258 for example overfull lines or ugly line breaks.
259 +When output is to a pager on a terminal that is less than 66 columns
260 +wide, the default is reduced to three columns.
261 +.It Cm mdoc
262 +Format
263 +.Xr man 5
264 +input files in
265 +.Xr mdoc 5
266 +output style.
267 +Specifically, this suppresses the two additional blank lines near the
268 +top and the bottom of each page, and it implies
269 +.Fl O Cm indent Ns =5 .
270 +One useful application is for checking that
271 +.Fl T Cm man
272 +output formats in the same way as the
273 +.Xr mdoc 5
274 +source it was generated from.
298 275 .It Cm width Ns = Ns Ar width
299 276 The output width is set to
300 -.Ar width .
277 +.Ar width
278 +instead of the default of 78.
279 +When output is to a pager on a terminal that is less than 79 columns
280 +wide, the default is reduced to one less than the terminal width.
281 +In any case, lines that are output in literal mode are never wrapped
282 +and may exceed the output width.
301 283 .El
302 284 .Ss HTML Output
303 285 Output produced by
304 286 .Fl T Cm html
305 287 conforms to HTML5 using optional self-closing tags.
306 288 Default styles use only CSS1.
307 289 Equations rendered from
308 290 .Xr eqn 5
309 291 blocks use MathML.
310 292 .Pp
311 293 The
312 294 .Pa mandoc.css
313 295 file documents style-sheet classes available for customising output.
314 296 If a style-sheet is not specified with
315 297 .Fl O Cm style ,
316 298 .Fl T Cm html
317 299 defaults to simple output (via an embedded style-sheet)
318 300 readable in any graphical or text-based web
319 301 browser.
320 302 .Pp
321 -Special characters are rendered in decimal-encoded UTF\-8.
303 +Non-ASCII characters are rendered
304 +as hexadecimal Unicode character references.
322 305 .Pp
323 306 The following
324 307 .Fl O
325 308 arguments are accepted:
326 309 .Bl -tag -width Ds
327 310 .It Cm fragment
328 311 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
329 312 elements and only emit the subtree below the <body> element.
330 313 The
331 314 .Cm style
332 315 argument will be ignored.
333 316 This is useful when embedding manual content within existing documents.
334 317 .It Cm includes Ns = Ns Ar fmt
335 318 The string
336 319 .Ar fmt ,
337 320 for example,
338 321 .Ar ../src/%I.html ,
339 322 is used as a template for linked header files (usually via the
340 323 .Ic \&In
341 324 macro).
342 325 Instances of
343 326 .Sq \&%I
344 327 are replaced with the include filename.
345 328 The default is not to present a
346 329 hyperlink.
347 330 .It Cm man Ns = Ns Ar fmt
348 331 The string
349 332 .Ar fmt ,
350 333 for example,
351 334 .Ar ../html%S/%N.%S.html ,
352 335 is used as a template for linked manuals (usually via the
353 336 .Ic \&Xr
354 337 macro).
355 338 Instances of
356 339 .Sq \&%N
357 340 and
358 341 .Sq %S
359 342 are replaced with the linked manual's name and section, respectively.
360 343 If no section is included, section 1 is assumed.
|
↓ open down ↓ |
29 lines elided |
↑ open up ↑ |
361 344 The default is not to
362 345 present a hyperlink.
363 346 .It Cm style Ns = Ns Ar style.css
364 347 The file
365 348 .Ar style.css
366 349 is used for an external style-sheet.
367 350 This must be a valid absolute or
368 351 relative URI.
369 352 .El
370 353 .Ss Locale Output
371 -Locale-depending output encoding is triggered with
354 +By default,
355 +.Nm
356 +automatically selects UTF-8 or ASCII output according to the current
357 +.Xr locale 1 .
358 +If any of the environment variables
359 +.Ev LC_ALL ,
360 +.Ev LC_CTYPE ,
361 +or
362 +.Ev LANG
363 +are set and the first one that is set
364 +selects the UTF-8 character encoding, it produces
365 +.Sx UTF-8 Output ;
366 +otherwise, it falls back to
367 +.Sx ASCII Output .
368 +This output mode can also be selected explicitly with
372 369 .Fl T Cm locale .
373 -This is the default.
374 370 .Ss Man Output
375 -Translate input format into
371 +Use
372 +.Fl T Cm man
373 +to translate
374 +.Xr mdoc 5
375 +input into
376 376 .Xr man 5
377 377 output format.
378 378 This is useful for distributing manual sources to legacy systems
379 379 lacking
380 380 .Xr mdoc 5
381 381 formatters.
382 382 .Pp
383 -If
384 -.Xr mdoc 5
385 -is passed as input, it is translated into
386 -.Xr man 5 .
387 -If the input format is
383 +If the input format of a file is
388 384 .Xr man 5 ,
389 385 the input is copied to the output, expanding any
390 386 .Xr mandoc_roff 5
391 387 .Ic so
392 388 requests.
393 389 The parser is also run, and as usual, the
394 390 .Fl W
395 391 level controls which
396 392 .Sx DIAGNOSTICS
397 393 are displayed before copying the input to the output.
398 394 .Ss Markdown Output
399 -Translate
395 +Use
396 +.Fl T Cm markdown
397 +to translate
400 398 .Xr mdoc 5
401 -input to the
402 -.Sy markdown
403 -format conforming to
399 +input to the markdown format conforming to
404 400 .Lk http://daringfireball.net/projects/markdown/syntax.text\
405 401 "John Gruber's 2004 specification" .
406 402 The output also almost conforms to the
407 403 .Lk http://commonmark.org/ CommonMark
408 404 specification.
409 405 .Pp
410 406 The character set used for the markdown output is ASCII.
411 407 Non-ASCII characters are encoded as HTML entities.
412 408 Since that is not possible in literal font contexts, because these
413 409 are rendered as code spans and code blocks in the markdown output,
414 410 non-ASCII characters are transliterated to ASCII approximations in
415 411 these contexts.
416 412 .Pp
417 413 Markdown is a very weak markup language, so all semantic markup is
418 414 lost, and even part of the presentational markup may be lost.
419 415 Do not use this as an intermediate step in converting to HTML;
420 416 instead, use
421 417 .Fl T Cm html
422 418 directly.
423 419 .Pp
424 420 The
425 421 .Xr man 5 ,
426 422 .Xr tbl 5 ,
427 423 and
428 424 .Xr eqn 5
429 425 input languages are not supported by
430 426 .Fl T Cm markdown
431 427 output mode.
432 428 .Ss PDF Output
433 429 PDF-1.1 output may be generated by
434 430 .Fl T Cm pdf .
435 431 See
436 432 .Sx PostScript Output
437 433 for
438 434 .Fl O
439 435 arguments and defaults.
440 436 .Ss PostScript Output
441 437 PostScript
442 438 .Qq Adobe-3.0
443 439 Level-2 pages may be generated by
444 440 .Fl T Cm ps .
445 441 Output pages default to letter sized and are rendered in the Times font
446 442 family, 11-point.
447 443 Margins are calculated as 1/9 the page length and width.
448 444 Line-height is 1.4m.
449 445 .Pp
450 446 Special characters are rendered as in
451 447 .Sx ASCII Output .
452 448 .Pp
453 449 The following
454 450 .Fl O
455 451 arguments are accepted:
456 452 .Bl -tag -width Ds
457 453 .It Cm paper Ns = Ns Ar name
458 454 The paper size
459 455 .Ar name
460 456 may be one of
461 457 .Ar a3 ,
462 458 .Ar a4 ,
463 459 .Ar a5 ,
|
↓ open down ↓ |
50 lines elided |
↑ open up ↑ |
464 460 .Ar legal ,
465 461 or
466 462 .Ar letter .
467 463 You may also manually specify dimensions as
468 464 .Ar NNxNN ,
469 465 width by height in millimetres.
470 466 If an unknown value is encountered,
471 467 .Ar letter
472 468 is used.
473 469 .El
474 -.Ss UTF\-8 Output
470 +.Ss UTF-8 Output
475 471 Use
476 472 .Fl T Cm utf8
477 -to force a UTF\-8 locale.
473 +to force text output in UTF-8 multi-byte character encoding,
474 +ignoring the
475 +.Xr locale 1
476 +settings in the environment.
478 477 See
479 -.Sx Locale Output
480 -for details and options.
478 +.Sx ASCII Output
479 +regarding font styles and
480 +.Fl O
481 +arguments.
482 +.Pp
483 +On operating systems lacking locale or wide character support, and
484 +on those where the internal character representation is not UCS-4,
485 +.Nm
486 +always falls back to
487 +.Sx ASCII Output .
481 488 .Ss Syntax tree output
482 489 Use
483 490 .Fl T Cm tree
484 491 to show a human readable representation of the syntax tree.
485 492 It is useful for debugging the source code of manual pages.
486 493 The exact format is subject to change, so don't write parsers for it.
487 494 .Pp
488 495 The first paragraph shows meta data found in the
489 496 .Xr mdoc 5
490 497 prologue, on the
491 498 .Xr man 5
492 499 .Ic \&TH
493 500 line, or the fallbacks used.
494 501 .Pp
495 502 In the tree dump, each output line shows one syntax tree node.
496 503 Child nodes are indented with respect to their parent node.
497 504 The columns are:
498 505 .Pp
499 506 .Bl -enum -compact
500 507 .It
501 508 For macro nodes, the macro name; for text and
502 509 .Xr tbl 5
503 510 nodes, the content.
504 511 There is a special format for
505 512 .Xr eqn 5
506 513 nodes.
507 514 .It
508 515 Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
509 516 .It
510 517 Flags:
511 518 .Bl -dash -compact
512 519 .It
513 520 An opening parenthesis if the node is an opening delimiter.
514 521 .It
515 522 An asterisk if the node starts a new input line.
516 523 .It
517 524 The input line number (starting at one).
518 525 .It
519 526 A colon.
520 527 .It
521 528 The input column number (starting at one).
522 529 .It
523 530 A closing parenthesis if the node is a closing delimiter.
524 531 .It
525 532 A full stop if the node ends a sentence.
526 533 .It
527 534 BROKEN if the node is a block broken by another block.
528 535 .It
529 536 NOSRC if the node is not in the input file,
530 537 but automatically generated from macros.
531 538 .It
532 539 NOPRT if the node is not supposed to generate output
533 540 for any output format.
534 541 .El
535 542 .El
536 543 .Pp
|
↓ open down ↓ |
46 lines elided |
↑ open up ↑ |
537 544 The following
538 545 .Fl O
539 546 argument is accepted:
540 547 .Bl -tag -width Ds
541 548 .It Cm noval
542 549 Skip validation and show the unvalidated syntax tree.
543 550 This can help to find out whether a given behaviour is caused by
544 551 the parser or by the validator.
545 552 Meta data is not available in this case.
546 553 .El
554 +.Sh ENVIRONMENT
555 +.Bl -tag -width Ev
556 +.It Ev LC_CTYPE
557 +The character encoding
558 +.Xr locale 1 .
559 +When
560 +.Sx Locale Output
561 +is selected, it decides whether to use ASCII or UTF-8 output format.
562 +It never affects the interpretation of input files.
563 +.El
547 564 .Sh EXIT STATUS
548 565 The
549 566 .Nm
550 567 utility exits with one of the following values, controlled by the message
551 568 .Ar level
552 569 associated with the
553 570 .Fl W
554 571 option:
555 572 .Pp
556 573 .Bl -tag -width Ds -compact
557 574 .It 0
558 575 No base system convention violations, style suggestions, warnings,
559 576 or errors occurred, or those that did were ignored because they
560 577 were lower than the requested
561 578 .Ar level .
562 579 .It 1
563 580 At least one base system convention violation or style suggestion
564 581 occurred, but no warning or error, and
565 582 .Fl W Cm base
566 583 or
567 584 .Fl W Cm style
568 585 was specified.
569 586 .It 2
570 587 At least one warning occurred, but no error, and
571 588 .Fl W Cm warning
572 589 or a lower
573 590 .Ar level
574 591 was requested.
575 592 .It 3
576 593 At least one parsing error occurred,
577 594 but no unsupported feature was encountered, and
578 595 .Fl W Cm error
579 596 or a lower
580 597 .Ar level
581 598 was requested.
582 599 .It 4
583 600 At least one unsupported feature was encountered, and
584 601 .Fl W Cm unsupp
585 602 or a lower
586 603 .Ar level
587 604 was requested.
588 605 .It 5
589 606 Invalid command line arguments were specified.
590 607 No input files have been read.
591 608 .It 6
592 609 An operating system error occurred, for example exhaustion
593 610 of memory, file descriptors, or process table entries.
594 611 Such errors cause
595 612 .Nm
596 613 to exit at once, possibly in the middle of parsing or formatting a file.
597 614 .El
598 615 .Pp
599 616 Note that selecting
600 617 .Fl T Cm lint
601 618 output mode implies
602 619 .Fl W Cm all .
603 620 .Sh EXAMPLES
604 621 To page manuals to the terminal:
605 622 .Pp
606 623 .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
607 624 .Pp
608 625 To produce HTML manuals with
609 626 .Pa mandoc.css
610 627 as the style-sheet:
611 628 .Pp
612 629 .Dl $ mandoc \-T html -Ostyle=mandoc.css mdoc.5 \*(Gt mdoc.5.html
613 630 .Pp
614 631 To check over a large set of manuals:
615 632 .Pp
616 633 .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
617 634 .Pp
618 635 To produce a series of PostScript manuals for A4 paper:
619 636 .Pp
620 637 .Dl $ mandoc \-T ps \-O paper=a4 mdoc.5 man.5 \*(Gt manuals.ps
621 638 .Pp
622 639 Convert a modern
623 640 .Xr mdoc 5
624 641 manual to the older
625 642 .Xr man 5
626 643 format, for use on systems lacking an
627 644 .Xr mdoc 5
628 645 parser:
629 646 .Pp
630 647 .Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
631 648 .Sh DIAGNOSTICS
632 649 Messages displayed by
633 650 .Nm
634 651 follow this format:
635 652 .Bd -ragged -offset indent
636 653 .Nm :
637 654 .Ar file : Ns Ar line : Ns Ar column : level : message : macro args
638 655 .Pq Ar os
639 656 .Ed
640 657 .Pp
641 658 Line and column numbers start at 1.
642 659 Both are omitted for messages referring to an input file as a whole.
643 660 Macro names and arguments are omitted where meaningless.
644 661 The
645 662 .Ar os
646 663 operating system specifier is omitted for messages that are relevant
647 664 for all operating systems.
648 665 Fatal messages about invalid command line arguments
649 666 or operating system errors, for example when memory is exhausted,
650 667 may also omit the
651 668 .Ar file
652 669 and
653 670 .Ar level
654 671 fields.
655 672 .Pp
656 673 Message levels have the following meanings:
657 674 .Bl -tag -width "warning"
658 675 .It Cm unsupp
659 676 An input file uses unsupported low-level
660 677 .Xr mandoc_roff 5
661 678 features.
662 679 The output may be incomplete and/or misformatted,
663 680 so using GNU troff instead of
664 681 .Nm
665 682 to process the file may be preferable.
666 683 .It Cm error
667 684 Indicates a risk of information loss or severe misformatting,
668 685 in most cases caused by serious syntax errors.
669 686 .It Cm warning
670 687 Indicates a risk that the information shown or its formatting
671 688 may mismatch the author's intent in minor ways.
672 689 Additionally, syntax errors are classified at least as warnings,
673 690 even if they do not usually cause misformatting.
674 691 .It Cm style
675 692 An input file uses dubious or discouraged style.
676 693 This is not a complaint about the syntax, and probably neither
|
↓ open down ↓ |
120 lines elided |
↑ open up ↑ |
677 694 formatting nor portability are in danger.
678 695 While great care is taken to avoid false positives on the higher
679 696 message levels, the
680 697 .Cm style
681 698 level tries to reduce the probability that issues go unnoticed,
682 699 so it may occasionally issue bogus suggestions.
683 700 Please use your good judgement to decide whether any particular
684 701 .Cm style
685 702 suggestion really justifies a change to the input file.
686 703 .It Cm base
687 -A convertion used in the base system of a specific operating system
704 +A convention used in the base system of a specific operating system
688 705 is not adhered to.
689 706 These are not markup mistakes, and neither the quality of formatting
690 707 nor portability are in danger.
691 708 Messages of the
692 709 .Cm base
693 710 level are printed with the more intuitive
694 711 .Cm style
695 712 .Ar level
696 713 tag.
697 714 .El
698 715 .Pp
699 716 Messages of the
700 717 .Cm base ,
701 718 .Cm style ,
702 719 .Cm warning ,
703 720 .Cm error ,
704 721 and
705 722 .Cm unsupp
706 723 levels except those about non-existent or unreadable input files
707 724 are hidden unless their level, or a lower level, is requested using a
708 725 .Fl W
709 726 option or
710 727 .Fl T Cm lint
711 728 output mode.
712 729 .Pp
713 730 As indicated below, all
714 731 .Cm base
715 732 and some
716 733 .Cm style
717 734 checks are only performed if a specific operating system name occurs
718 735 in the arguments of the
719 736 .Fl W
720 737 command line option, of the
721 738 .Ic \&Os
722 739 macro, of the
723 740 .Fl Ios
724 741 command line option, or, if neither are present, in the return value
725 742 of the
726 743 .Xr uname 3
727 744 function.
728 745 .Ss Conventions for base system manuals
729 746 .Bl -ohang
730 747 .It Sy "Mdocdate found"
731 748 .Pq mdoc , Nx
732 749 The
733 750 .Ic \&Dd
734 751 macro uses CVS
735 752 .Ic Mdocdate
736 753 keyword substitution, which is not supported by the
737 754 .Nx
738 755 base system.
739 756 Consider using the conventional
740 757 .Dq "Month dd, yyyy"
741 758 format instead.
742 759 .It Sy "Mdocdate missing"
743 760 .Pq mdoc , Ox
744 761 The
745 762 .Ic \&Dd
746 763 macro does not use CVS
747 764 .Ic Mdocdate
748 765 keyword substitution, but using it is conventionally expected in the
749 766 .Ox
750 767 base system.
751 768 .It Sy "unknown architecture"
752 769 .Pq mdoc , Ox , Nx
753 770 The third argument of the
754 771 .Ic \&Dt
755 772 macro does not match any of the architectures this operating system
756 773 is running on.
757 774 .It Sy "operating system explicitly specified"
758 775 .Pq mdoc , Ox , Nx
759 776 The
760 777 .Ic \&Os
761 778 macro has an argument.
762 779 In the base system, it is conventionally left blank.
763 780 .It Sy "RCS id missing"
764 781 .Pq Ox , Nx
765 782 The manual page lacks the comment line with the RCS identifier
766 783 generated by CVS
767 784 .Ic OpenBSD
768 785 or
769 786 .Ic NetBSD
770 787 keyword substitution as conventionally used in these operating systems.
771 788 .It Sy "referenced manual not found"
772 789 .Pq mdoc
773 790 An
774 791 .Ic \&Xr
775 792 macro references a manual page that is not found in the base system.
776 793 The path to look for base system manuals is configurable at compile
777 794 time and defaults to
778 795 .Pa /usr/share/man : /usr/X11R6/man .
779 796 .El
780 797 .Ss Style suggestions
781 798 .Bl -ohang
782 799 .It Sy "legacy man(7) date format"
783 800 .Pq mdoc
784 801 The
|
↓ open down ↓ |
87 lines elided |
↑ open up ↑ |
785 802 .Ic \&Dd
786 803 macro uses the legacy
787 804 .Xr man 5
788 805 date format
789 806 .Dq yyyy-dd-mm .
790 807 Consider using the conventional
791 808 .Xr mdoc 5
792 809 date format
793 810 .Dq "Month dd, yyyy"
794 811 instead.
812 +.It Sy "normalizing date format to" : No ...
813 +.Pq mdoc , man
814 +The
815 +.Ic \&Dd
816 +or
817 +.Ic \&TH
818 +macro provides an abbreviated month name or a day number with a
819 +leading zero.
820 +In the formatted output, the month name is written out in full
821 +and the leading zero is omitted.
795 822 .It Sy "lower case character in document title"
796 823 .Pq mdoc , man
797 824 The title is still used as given in the
798 825 .Ic \&Dt
799 826 or
800 827 .Ic \&TH
801 828 macro.
802 829 .It Sy "duplicate RCS id"
803 830 A single manual page contains two copies of the RCS identifier for
804 831 the same operating system.
805 832 Consider deleting the later instance and moving the first one up
806 833 to the top of the page.
807 -.It Sy "typo in section name"
834 +.It Sy "possible typo in section name"
808 835 .Pq mdoc
809 836 Fuzzy string matching revealed that the argument of an
810 837 .Ic \&Sh
811 838 macro is similar, but not identical to a standard section name.
812 839 .It Sy "unterminated quoted argument"
813 840 .Pq roff
814 841 Macro arguments can be enclosed in double quote characters
815 842 such that space characters and macro names contained in the quoted
816 843 argument need not be escaped.
817 844 The closing quote of the last argument of a macro can be omitted.
818 845 However, omitting it is not recommended because it makes the code
819 846 harder to read.
820 847 .It Sy "useless macro"
821 848 .Pq mdoc
822 849 A
823 850 .Ic \&Bt ,
824 851 .Ic \&Tn ,
825 852 or
826 853 .Ic \&Ud
827 854 macro was found.
828 855 Simply delete it: it serves no useful purpose.
829 856 .It Sy "consider using OS macro"
830 857 .Pq mdoc
831 858 A string was found in plain text or in a
832 859 .Ic \&Bx
833 860 macro that could be represented using
834 861 .Ic \&Ox ,
835 862 .Ic \&Nx ,
836 863 .Ic \&Fx ,
837 864 or
838 865 .Ic \&Dx .
839 866 .It Sy "errnos out of order"
840 867 .Pq mdoc, Nx
841 868 The
842 869 .Ic \&Er
843 870 items in a
844 871 .Ic \&Bl
845 872 list are not in alphabetical order.
846 873 .It Sy "duplicate errno"
847 874 .Pq mdoc, Nx
848 875 A
849 876 .Ic \&Bl
850 877 list contains two consecutive
851 878 .Ic \&It
852 879 entries describing the same
853 880 .Ic \&Er
854 881 number.
855 882 .It Sy "trailing delimiter"
856 883 .Pq mdoc
857 884 The last argument of an
858 885 .Ic \&Ex , \&Fo , \&Nd , \&Nm , \&Os , \&Sh , \&Ss , \&St ,
859 886 or
860 887 .Ic \&Sx
861 888 macro ends with a trailing delimiter.
862 889 This is usually bad style and often indicates typos.
863 890 Most likely, the delimiter can be removed.
864 891 .It Sy "no blank before trailing delimiter"
865 892 .Pq mdoc
866 893 The last argument of a macro that supports trailing delimiter
867 894 arguments is longer than one byte and ends with a trailing delimiter.
868 895 Consider inserting a blank such that the delimiter becomes a separate
869 896 argument, thus moving it out of the scope of the macro.
870 897 .It Sy "fill mode already enabled, skipping"
871 898 .Pq man
872 899 A
873 900 .Ic \&fi
|
↓ open down ↓ |
56 lines elided |
↑ open up ↑ |
874 901 request occurs even though the document is still in fill mode,
875 902 or already switched back to fill mode.
876 903 It has no effect.
877 904 .It Sy "fill mode already disabled, skipping"
878 905 .Pq man
879 906 An
880 907 .Ic \&nf
881 908 request occurs even though the document already switched to no-fill mode
882 909 and did not switch back to fill mode yet.
883 910 It has no effect.
911 +.It Sy "verbatim \(dq--\(dq, maybe consider using \e(em"
912 +.Pq mdoc
913 +Even though the ASCII output device renders an em-dash as
914 +.Qq \-\- ,
915 +that is not a good way to write it in an input file
916 +because it renders poorly on all other output devices.
884 917 .It Sy "function name without markup"
885 918 .Pq mdoc
886 919 A word followed by an empty pair of parentheses occurs on a text line.
887 920 Consider using an
888 921 .Ic \&Fn
889 922 or
890 923 .Ic \&Xr
891 924 macro.
892 925 .It Sy "whitespace at end of input line"
893 926 .Pq mdoc , man , roff
894 927 Whitespace at the end of input lines is almost never semantically
895 928 significant \(em but in the odd case where it might be, it is
896 929 extremely confusing when reviewing and maintaining documents.
897 930 .It Sy "bad comment style"
898 931 .Pq roff
899 932 Comment lines start with a dot, a backslash, and a double-quote character.
900 933 The
901 934 .Nm
902 935 utility treats the line as a comment line even without the backslash,
903 936 but leaving out the backslash might not be portable.
904 937 .El
905 938 .Ss Warnings related to the document prologue
906 939 .Bl -ohang
907 940 .It Sy "missing manual title, using UNTITLED"
908 941 .Pq mdoc
909 942 A
910 943 .Ic \&Dt
911 944 macro has no arguments, or there is no
912 945 .Ic \&Dt
913 946 macro before the first non-prologue macro.
914 947 .It Sy "missing manual title, using \(dq\(dq"
915 948 .Pq man
916 949 There is no
917 950 .Ic \&TH
918 951 macro, or it has no arguments.
919 952 .It Sy "missing manual section, using \(dq\(dq"
920 953 .Pq mdoc , man
921 954 A
922 955 .Ic \&Dt
923 956 or
924 957 .Ic \&TH
925 958 macro lacks the mandatory section argument.
926 959 .It Sy "unknown manual section"
927 960 .Pq mdoc
928 961 The section number in a
929 962 .Ic \&Dt
930 963 line is invalid, but still used.
931 964 .It Sy "missing date, using today's date"
932 965 .Pq mdoc, man
933 966 The document was parsed as
934 967 .Xr mdoc 5
935 968 and it has no
936 969 .Ic \&Dd
937 970 macro, or the
938 971 .Ic \&Dd
939 972 macro has no arguments or only empty arguments;
940 973 or the document was parsed as
941 974 .Xr man 5
942 975 and it has no
943 976 .Ic \&TH
944 977 macro, or the
945 978 .Ic \&TH
946 979 macro has less than three arguments or its third argument is empty.
947 980 .It Sy "cannot parse date, using it verbatim"
948 981 .Pq mdoc , man
949 982 The date given in a
950 983 .Ic \&Dd
951 984 or
952 985 .Ic \&TH
953 986 macro does not follow the conventional format.
954 987 .It Sy "date in the future, using it anyway"
955 988 .Pq mdoc , man
956 989 The date given in a
957 990 .Ic \&Dd
958 991 or
959 992 .Ic \&TH
960 993 macro is more than a day ahead of the current system
961 994 .Xr time 3 .
962 995 .It Sy "missing Os macro, using \(dq\(dq"
963 996 .Pq mdoc
964 997 The default or current system is not shown in this case.
965 998 .It Sy "late prologue macro"
966 999 .Pq mdoc
967 1000 A
968 1001 .Ic \&Dd
969 1002 or
970 1003 .Ic \&Os
971 1004 macro occurs after some non-prologue macro, but still takes effect.
972 1005 .It Sy "prologue macros out of order"
973 1006 .Pq mdoc
974 1007 The prologue macros are not given in the conventional order
975 1008 .Ic \&Dd ,
976 1009 .Ic \&Dt ,
977 1010 .Ic \&Os .
978 1011 All three macros are used even when given in another order.
979 1012 .El
980 1013 .Ss Warnings regarding document structure
981 1014 .Bl -ohang
982 1015 .It Sy ".so is fragile, better use ln(1)"
983 1016 .Pq roff
984 1017 Including files only works when the parser program runs with the correct
985 1018 current working directory.
986 1019 .It Sy "no document body"
987 1020 .Pq mdoc , man
988 1021 The document body contains neither text nor macros.
989 1022 An empty document is shown, consisting only of a header and a footer line.
990 1023 .It Sy "content before first section header"
991 1024 .Pq mdoc , man
992 1025 Some macros or text precede the first
993 1026 .Ic \&Sh
994 1027 or
995 1028 .Ic \&SH
996 1029 section header.
997 1030 The offending macros and text are parsed and added to the top level
998 1031 of the syntax tree, outside any section block.
999 1032 .It Sy "first section is not NAME"
1000 1033 .Pq mdoc
1001 1034 The argument of the first
1002 1035 .Ic \&Sh
1003 1036 macro is not
1004 1037 .Sq NAME .
1005 1038 This may confuse
1006 1039 .Xr apropos 1
1007 1040 or confuse
1008 1041 .Xr man 1
1009 1042 when updating the
1010 1043 .Xr whatis 1
1011 1044 database.
1012 1045 .It Sy "NAME section without Nm before Nd"
1013 1046 .Pq mdoc
1014 1047 The NAME section does not contain any
1015 1048 .Ic \&Nm
1016 1049 child macro before the first
1017 1050 .Ic \&Nd
1018 1051 macro.
1019 1052 .It Sy "NAME section without description"
1020 1053 .Pq mdoc
1021 1054 The NAME section lacks the mandatory
1022 1055 .Ic \&Nd
1023 1056 child macro.
1024 1057 .It Sy "description not at the end of NAME"
1025 1058 .Pq mdoc
1026 1059 The NAME section does contain an
1027 1060 .Ic \&Nd
1028 1061 child macro, but other content follows it.
1029 1062 .It Sy "bad NAME section content"
1030 1063 .Pq mdoc
1031 1064 The NAME section contains plain text or macros other than
1032 1065 .Ic \&Nm
1033 1066 and
1034 1067 .Ic \&Nd .
1035 1068 .It Sy "missing comma before name"
1036 1069 .Pq mdoc
1037 1070 The NAME section contains an
1038 1071 .Ic \&Nm
1039 1072 macro that is neither the first one nor preceded by a comma.
1040 1073 .It Sy "missing description line, using \(dq\(dq"
1041 1074 .Pq mdoc
1042 1075 The
1043 1076 .Ic \&Nd
1044 1077 macro lacks the required argument.
1045 1078 The title line of the manual will end after the dash.
1046 1079 .It Sy "description line outside NAME section"
1047 1080 .Pq mdoc
1048 1081 An
1049 1082 .Ic \&Nd
1050 1083 macro appears outside the NAME section.
1051 1084 The arguments are printed anyway and the following text is used for
1052 1085 .Xr apropos 1 ,
1053 1086 but none of that behaviour is portable.
1054 1087 .It Sy "sections out of conventional order"
1055 1088 .Pq mdoc
1056 1089 A standard section occurs after another section it usually precedes.
1057 1090 All section titles are used as given,
1058 1091 and the order of sections is not changed.
1059 1092 .It Sy "duplicate section title"
1060 1093 .Pq mdoc
1061 1094 The same standard section title occurs more than once.
1062 1095 .It Sy "unexpected section"
1063 1096 .Pq mdoc
1064 1097 A standard section header occurs in a section of the manual
1065 1098 where it normally isn't useful.
1066 1099 .It Sy "cross reference to self"
1067 1100 .Pq mdoc
1068 1101 An
1069 1102 .Ic \&Xr
1070 1103 macro refers to a name and section matching the section of the present
1071 1104 manual page and a name mentioned in an
1072 1105 .Ic \&Nm
1073 1106 macro in the NAME or SYNOPSIS section, or in an
1074 1107 .Ic \&Fn
1075 1108 or
1076 1109 .Ic \&Fo
1077 1110 macro in the SYNOPSIS.
1078 1111 Consider using
1079 1112 .Ic \&Nm
1080 1113 or
1081 1114 .Ic \&Fn
1082 1115 instead of
1083 1116 .Ic \&Xr .
1084 1117 .It Sy "unusual Xr order"
1085 1118 .Pq mdoc
1086 1119 In the SEE ALSO section, an
1087 1120 .Ic \&Xr
1088 1121 macro with a lower section number follows one with a higher number,
1089 1122 or two
1090 1123 .Ic \&Xr
1091 1124 macros referring to the same section are out of alphabetical order.
1092 1125 .It Sy "unusual Xr punctuation"
1093 1126 .Pq mdoc
1094 1127 In the SEE ALSO section, punctuation between two
1095 1128 .Ic \&Xr
1096 1129 macros differs from a single comma, or there is trailing punctuation
1097 1130 after the last
1098 1131 .Ic \&Xr
1099 1132 macro.
1100 1133 .It Sy "AUTHORS section without An macro"
1101 1134 .Pq mdoc
1102 1135 An AUTHORS sections contains no
1103 1136 .Ic \&An
1104 1137 macros, or only empty ones.
1105 1138 Probably, there are author names lacking markup.
1106 1139 .El
1107 1140 .Ss "Warnings related to macros and nesting"
1108 1141 .Bl -ohang
1109 1142 .It Sy "obsolete macro"
1110 1143 .Pq mdoc
1111 1144 See the
1112 1145 .Xr mdoc 5
1113 1146 manual for replacements.
1114 1147 .It Sy "macro neither callable nor escaped"
1115 1148 .Pq mdoc
1116 1149 The name of a macro that is not callable appears on a macro line.
1117 1150 It is printed verbatim.
1118 1151 If the intention is to call it, move it to its own input line;
1119 1152 otherwise, escape it by prepending
1120 1153 .Sq \e& .
1121 1154 .It Sy "skipping paragraph macro"
1122 1155 In
1123 1156 .Xr mdoc 5
1124 1157 documents, this happens
1125 1158 .Bl -dash -compact
1126 1159 .It
1127 1160 at the beginning and end of sections and subsections
1128 1161 .It
1129 1162 right before non-compact lists and displays
1130 1163 .It
1131 1164 at the end of items in non-column, non-compact lists
1132 1165 .It
1133 1166 and for multiple consecutive paragraph macros.
1134 1167 .El
1135 1168 In
1136 1169 .Xr man 5
1137 1170 documents, it happens
1138 1171 .Bl -dash -compact
1139 1172 .It
1140 1173 for empty
1141 1174 .Ic \&P ,
1142 1175 .Ic \&PP ,
1143 1176 and
1144 1177 .Ic \&LP
1145 1178 macros
1146 1179 .It
1147 1180 for
1148 1181 .Ic \&IP
1149 1182 macros having neither head nor body arguments
1150 1183 .It
1151 1184 for
1152 1185 .Ic \&br
1153 1186 or
1154 1187 .Ic \&sp
1155 1188 right after
1156 1189 .Ic \&SH
1157 1190 or
1158 1191 .Ic \&SS
1159 1192 .El
1160 1193 .It Sy "moving paragraph macro out of list"
1161 1194 .Pq mdoc
1162 1195 A list item in a
1163 1196 .Ic \&Bl
1164 1197 list contains a trailing paragraph macro.
1165 1198 The paragraph macro is moved after the end of the list.
1166 1199 .It Sy "skipping no-space macro"
1167 1200 .Pq mdoc
1168 1201 An input line begins with an
1169 1202 .Ic \&Ns
1170 1203 macro, or the next argument after an
1171 1204 .Ic \&Ns
1172 1205 macro is an isolated closing delimiter.
1173 1206 The macro is ignored.
1174 1207 .It Sy "blocks badly nested"
1175 1208 .Pq mdoc
1176 1209 If two blocks intersect, one should completely contain the other.
1177 1210 Otherwise, rendered output is likely to look strange in any output
1178 1211 format, and rendering in SGML-based output formats is likely to be
1179 1212 outright wrong because such languages do not support badly nested
1180 1213 blocks at all.
1181 1214 Typical examples of badly nested blocks are
1182 1215 .Qq Ic \&Ao \&Bo \&Ac \&Bc
1183 1216 and
1184 1217 .Qq Ic \&Ao \&Bq \&Ac .
1185 1218 In these examples,
1186 1219 .Ic \&Ac
1187 1220 breaks
1188 1221 .Ic \&Bo
1189 1222 and
1190 1223 .Ic \&Bq ,
1191 1224 respectively.
1192 1225 .It Sy "nested displays are not portable"
1193 1226 .Pq mdoc
1194 1227 A
1195 1228 .Ic \&Bd ,
1196 1229 .Ic \&D1 ,
1197 1230 or
1198 1231 .Ic \&Dl
1199 1232 display occurs nested inside another
1200 1233 .Ic \&Bd
1201 1234 display.
1202 1235 This works with
1203 1236 .Nm ,
1204 1237 but fails with most other implementations.
1205 1238 .It Sy "moving content out of list"
1206 1239 .Pq mdoc
1207 1240 A
1208 1241 .Ic \&Bl
1209 1242 list block contains text or macros before the first
1210 1243 .Ic \&It
1211 1244 macro.
1212 1245 The offending children are moved before the beginning of the list.
1213 1246 .It Sy "first macro on line"
1214 1247 Inside a
1215 1248 .Ic \&Bl Fl column
1216 1249 list, a
1217 1250 .Ic \&Ta
1218 1251 macro occurs as the first macro on a line, which is not portable.
1219 1252 .It Sy "line scope broken"
1220 1253 .Pq man
1221 1254 While parsing the next-line scope of the previous macro,
1222 1255 another macro is found that prematurely terminates the previous one.
1223 1256 The previous, interrupted macro is deleted from the parse tree.
1224 1257 .El
1225 1258 .Ss "Warnings related to missing arguments"
1226 1259 .Bl -ohang
1227 1260 .It Sy "skipping empty request"
1228 1261 .Pq roff , eqn
1229 1262 The macro name is missing from a macro definition request,
1230 1263 or an
1231 1264 .Xr eqn 5
1232 1265 control statement or operation keyword lacks its required argument.
1233 1266 .It Sy "conditional request controls empty scope"
1234 1267 .Pq roff
1235 1268 A conditional request is only useful if any of the following
1236 1269 follows it on the same logical input line:
1237 1270 .Bl -dash -compact
1238 1271 .It
1239 1272 The
1240 1273 .Sq \e{
1241 1274 keyword to open a multi-line scope.
1242 1275 .It
1243 1276 A request or macro or some text, resulting in a single-line scope.
1244 1277 .It
1245 1278 The immediate end of the logical line without any intervening whitespace,
1246 1279 resulting in next-line scope.
1247 1280 .El
1248 1281 Here, a conditional request is followed by trailing whitespace only,
1249 1282 and there is no other content on its logical input line.
1250 1283 Note that it doesn't matter whether the logical input line is split
1251 1284 across multiple physical input lines using
1252 1285 .Sq \e
1253 1286 line continuation characters.
1254 1287 This is one of the rare cases
1255 1288 where trailing whitespace is syntactically significant.
1256 1289 The conditional request controls a scope containing whitespace only,
1257 1290 so it is unlikely to have a significant effect,
1258 1291 except that it may control a following
1259 1292 .Ic \&el
1260 1293 clause.
1261 1294 .It Sy "skipping empty macro"
1262 1295 .Pq mdoc
1263 1296 The indicated macro has no arguments and hence no effect.
1264 1297 .It Sy "empty block"
1265 1298 .Pq mdoc , man
1266 1299 A
1267 1300 .Ic \&Bd ,
1268 1301 .Ic \&Bk ,
1269 1302 .Ic \&Bl ,
1270 1303 .Ic \&D1 ,
1271 1304 .Ic \&Dl ,
1272 1305 .Ic \&MT ,
1273 1306 .Ic \&RS ,
1274 1307 or
1275 1308 .Ic \&UR
1276 1309 block contains nothing in its body and will produce no output.
1277 1310 .It Sy "empty argument, using 0n"
1278 1311 .Pq mdoc
1279 1312 The required width is missing after
1280 1313 .Ic \&Bd
1281 1314 or
1282 1315 .Ic \&Bl
1283 1316 .Fl offset
1284 1317 or
1285 1318 .Fl width .
1286 1319 .It Sy "missing display type, using -ragged"
1287 1320 .Pq mdoc
1288 1321 The
1289 1322 .Ic \&Bd
1290 1323 macro is invoked without the required display type.
1291 1324 .It Sy "list type is not the first argument"
1292 1325 .Pq mdoc
1293 1326 In a
1294 1327 .Ic \&Bl
1295 1328 macro, at least one other argument precedes the type argument.
1296 1329 The
1297 1330 .Nm
1298 1331 utility copes with any argument order, but some other
1299 1332 .Xr mdoc 5
1300 1333 implementations do not.
1301 1334 .It Sy "missing -width in -tag list, using 8n"
1302 1335 .Pq mdoc
1303 1336 Every
1304 1337 .Ic \&Bl
1305 1338 macro having the
1306 1339 .Fl tag
1307 1340 argument requires
1308 1341 .Fl width ,
1309 1342 too.
1310 1343 .It Sy "missing utility name, using \(dq\(dq"
1311 1344 .Pq mdoc
1312 1345 The
1313 1346 .Ic \&Ex Fl std
1314 1347 macro is called without an argument before
1315 1348 .Ic \&Nm
1316 1349 has first been called with an argument.
1317 1350 .It Sy "missing function name, using \(dq\(dq"
1318 1351 .Pq mdoc
1319 1352 The
1320 1353 .Ic \&Fo
1321 1354 macro is called without an argument.
1322 1355 No function name is printed.
1323 1356 .It Sy "empty head in list item"
1324 1357 .Pq mdoc
1325 1358 In a
1326 1359 .Ic \&Bl
1327 1360 .Fl diag ,
1328 1361 .Fl hang ,
1329 1362 .Fl inset ,
1330 1363 .Fl ohang ,
1331 1364 or
1332 1365 .Fl tag
1333 1366 list, an
1334 1367 .Ic \&It
1335 1368 macro lacks the required argument.
1336 1369 The item head is left empty.
1337 1370 .It Sy "empty list item"
1338 1371 .Pq mdoc
1339 1372 In a
1340 1373 .Ic \&Bl
1341 1374 .Fl bullet ,
1342 1375 .Fl dash ,
1343 1376 .Fl enum ,
1344 1377 or
1345 1378 .Fl hyphen
1346 1379 list, an
1347 1380 .Ic \&It
1348 1381 block is empty.
1349 1382 An empty list item is shown.
1350 1383 .It Sy "missing argument, using next line"
1351 1384 .Pq mdoc
1352 1385 An
1353 1386 .Ic \&It
1354 1387 macro in a
1355 1388 .Ic \&Bd Fl column
1356 1389 list has no arguments.
1357 1390 While
1358 1391 .Nm
1359 1392 uses the text or macros of the following line, if any, for the cell,
1360 1393 other formatters may misformat the list.
1361 1394 .It Sy "missing font type, using \efR"
1362 1395 .Pq mdoc
1363 1396 A
1364 1397 .Ic \&Bf
1365 1398 macro has no argument.
1366 1399 It switches to the default font.
1367 1400 .It Sy "unknown font type, using \efR"
1368 1401 .Pq mdoc
1369 1402 The
1370 1403 .Ic \&Bf
1371 1404 argument is invalid.
1372 1405 The default font is used instead.
1373 1406 .It Sy "nothing follows prefix"
1374 1407 .Pq mdoc
1375 1408 A
1376 1409 .Ic \&Pf
1377 1410 macro has no argument, or only one argument and no macro follows
1378 1411 on the same input line.
1379 1412 This defeats its purpose; in particular, spacing is not suppressed
1380 1413 before the text or macros following on the next input line.
1381 1414 .It Sy "empty reference block"
1382 1415 .Pq mdoc
1383 1416 An
1384 1417 .Ic \&Rs
1385 1418 macro is immediately followed by an
1386 1419 .Ic \&Re
1387 1420 macro on the next input line.
1388 1421 Such an empty block does not produce any output.
1389 1422 .It Sy "missing section argument"
1390 1423 .Pq mdoc
1391 1424 An
1392 1425 .Ic \&Xr
1393 1426 macro lacks its second, section number argument.
1394 1427 The first argument, i.e. the name, is printed, but without subsequent
1395 1428 parentheses.
1396 1429 .It Sy "missing -std argument, adding it"
1397 1430 .Pq mdoc
1398 1431 An
1399 1432 .Ic \&Ex
1400 1433 or
1401 1434 .Ic \&Rv
1402 1435 macro lacks the required
1403 1436 .Fl std
1404 1437 argument.
1405 1438 The
1406 1439 .Nm
1407 1440 utility assumes
1408 1441 .Fl std
1409 1442 even when it is not specified, but other implementations may not.
1410 1443 .It Sy "missing option string, using \(dq\(dq"
1411 1444 .Pq man
1412 1445 The
1413 1446 .Ic \&OP
1414 1447 macro is invoked without any argument.
1415 1448 An empty pair of square brackets is shown.
1416 1449 .It Sy "missing resource identifier, using \(dq\(dq"
1417 1450 .Pq man
1418 1451 The
1419 1452 .Ic \&MT
1420 1453 or
1421 1454 .Ic \&UR
1422 1455 macro is invoked without any argument.
1423 1456 An empty pair of angle brackets is shown.
1424 1457 .It Sy "missing eqn box, using \(dq\(dq"
1425 1458 .Pq eqn
1426 1459 A diacritic mark or a binary operator is found,
1427 1460 but there is nothing to the left of it.
1428 1461 An empty box is inserted.
1429 1462 .El
1430 1463 .Ss "Warnings related to bad macro arguments"
1431 1464 .Bl -ohang
1432 1465 .It Sy "duplicate argument"
1433 1466 .Pq mdoc
1434 1467 A
1435 1468 .Ic \&Bd
1436 1469 or
1437 1470 .Ic \&Bl
1438 1471 macro has more than one
1439 1472 .Fl compact ,
1440 1473 more than one
1441 1474 .Fl offset ,
1442 1475 or more than one
1443 1476 .Fl width
1444 1477 argument.
1445 1478 All but the last instances of these arguments are ignored.
1446 1479 .It Sy "skipping duplicate argument"
1447 1480 .Pq mdoc
1448 1481 An
1449 1482 .Ic \&An
1450 1483 macro has more than one
1451 1484 .Fl split
1452 1485 or
1453 1486 .Fl nosplit
1454 1487 argument.
1455 1488 All but the first of these arguments are ignored.
1456 1489 .It Sy "skipping duplicate display type"
1457 1490 .Pq mdoc
1458 1491 A
1459 1492 .Ic \&Bd
1460 1493 macro has more than one type argument; the first one is used.
1461 1494 .It Sy "skipping duplicate list type"
1462 1495 .Pq mdoc
1463 1496 A
1464 1497 .Ic \&Bl
1465 1498 macro has more than one type argument; the first one is used.
1466 1499 .It Sy "skipping -width argument"
1467 1500 .Pq mdoc
1468 1501 A
1469 1502 .Ic \&Bl
1470 1503 .Fl column ,
1471 1504 .Fl diag ,
1472 1505 .Fl ohang ,
1473 1506 .Fl inset ,
1474 1507 or
1475 1508 .Fl item
1476 1509 list has a
1477 1510 .Fl width
1478 1511 argument.
1479 1512 That has no effect.
1480 1513 .It Sy "wrong number of cells"
1481 1514 In a line of a
1482 1515 .Ic \&Bl Fl column
1483 1516 list, the number of tabs or
1484 1517 .Ic \&Ta
1485 1518 macros is less than the number expected from the list header line
1486 1519 or exceeds the expected number by more than one.
1487 1520 Missing cells remain empty, and all cells exceeding the number of
1488 1521 columns are joined into one single cell.
1489 1522 .It Sy "unknown AT&T UNIX version"
1490 1523 .Pq mdoc
1491 1524 An
1492 1525 .Ic \&At
1493 1526 macro has an invalid argument.
1494 1527 It is used verbatim, with
1495 1528 .Qq "AT&T UNIX "
1496 1529 prefixed to it.
1497 1530 .It Sy "comma in function argument"
1498 1531 .Pq mdoc
1499 1532 An argument of an
1500 1533 .Ic \&Fa
1501 1534 or
1502 1535 .Ic \&Fn
1503 1536 macro contains a comma; it should probably be split into two arguments.
1504 1537 .It Sy "parenthesis in function name"
1505 1538 .Pq mdoc
1506 1539 The first argument of an
1507 1540 .Ic \&Fc
1508 1541 or
1509 1542 .Ic \&Fn
1510 1543 macro contains an opening or closing parenthesis; that's probably wrong,
1511 1544 parentheses are added automatically.
1512 1545 .It Sy "unknown library name"
1513 1546 .Pq mdoc, not on Ox
1514 1547 An
1515 1548 .Ic \&Lb
1516 1549 macro has an unknown name argument and will be rendered as
1517 1550 .Qq library Dq Ar name .
1518 1551 .It Sy "invalid content in Rs block"
1519 1552 .Pq mdoc
1520 1553 An
1521 1554 .Ic \&Rs
1522 1555 block contains plain text or non-% macros.
1523 1556 The bogus content is left in the syntax tree.
1524 1557 Formatting may be poor.
1525 1558 .It Sy "invalid Boolean argument"
1526 1559 .Pq mdoc
1527 1560 An
1528 1561 .Ic \&Sm
1529 1562 macro has an argument other than
1530 1563 .Cm on
1531 1564 or
1532 1565 .Cm off .
1533 1566 The invalid argument is moved out of the macro, which leaves the macro
1534 1567 empty, causing it to toggle the spacing mode.
1535 1568 .It Sy "unknown font, skipping request"
1536 1569 .Pq man , tbl
1537 1570 A
1538 1571 .Xr mandoc_roff 5
1539 1572 .Ic \&ft
1540 1573 request or a
1541 1574 .Xr tbl 5
1542 1575 .Ic \&f
1543 1576 layout modifier has an unknown
1544 1577 .Ar font
1545 1578 argument.
1546 1579 .It Sy "odd number of characters in request"
1547 1580 .Pq roff
1548 1581 A
1549 1582 .Ic \&tr
1550 1583 request contains an odd number of characters.
1551 1584 The last character is mapped to the blank character.
1552 1585 .El
1553 1586 .Ss "Warnings related to plain text"
1554 1587 .Bl -ohang
1555 1588 .It Sy "blank line in fill mode, using .sp"
1556 1589 .Pq mdoc
1557 1590 The meaning of blank input lines is only well-defined in non-fill mode:
1558 1591 In fill mode, line breaks of text input lines are not supposed to be
1559 1592 significant.
1560 1593 However, for compatibility with groff, blank lines in fill mode
1561 1594 are replaced with
1562 1595 .Ic \&sp
1563 1596 requests.
1564 1597 .It Sy "tab in filled text"
1565 1598 .Pq mdoc , man
1566 1599 The meaning of tab characters is only well-defined in non-fill mode:
1567 1600 In fill mode, whitespace is not supposed to be significant
1568 1601 on text input lines.
1569 1602 As an implementation dependent choice, tab characters on text lines
1570 1603 are passed through to the formatters in any case.
1571 1604 Given that the text before the tab character will be filled,
1572 1605 it is hard to predict which tab stop position the tab will advance to.
1573 1606 .It Sy "new sentence, new line"
1574 1607 .Pq mdoc
1575 1608 A new sentence starts in the middle of a text line.
1576 1609 Start it on a new input line to help formatters produce correct spacing.
1577 1610 .It Sy "invalid escape sequence"
1578 1611 .Pq roff
1579 1612 An escape sequence has an invalid opening argument delimiter, lacks the
1580 1613 closing argument delimiter, or the argument has too few characters.
1581 1614 If the argument is incomplete,
1582 1615 .Ic \e*
1583 1616 and
1584 1617 .Ic \en
1585 1618 expand to an empty string,
1586 1619 .Ic \eB
1587 1620 to the digit
1588 1621 .Sq 0 ,
1589 1622 and
1590 1623 .Ic \ew
1591 1624 to the length of the incomplete argument.
1592 1625 All other invalid escape sequences are ignored.
1593 1626 .It Sy "undefined string, using \(dq\(dq"
1594 1627 .Pq roff
1595 1628 If a string is used without being defined before,
1596 1629 its value is implicitly set to the empty string.
1597 1630 However, defining strings explicitly before use
1598 1631 keeps the code more readable.
1599 1632 .El
1600 1633 .Ss "Warnings related to tables"
1601 1634 .Bl -ohang
1602 1635 .It Sy "tbl line starts with span"
1603 1636 .Pq tbl
1604 1637 The first cell in a table layout line is a horizontal span
1605 1638 .Pq Sq Cm s .
1606 1639 Data provided for this cell is ignored, and nothing is printed in the cell.
1607 1640 .It Sy "tbl column starts with span"
1608 1641 .Pq tbl
1609 1642 The first line of a table layout specification
1610 1643 requests a vertical span
1611 1644 .Pq Sq Cm ^ .
1612 1645 Data provided for this cell is ignored, and nothing is printed in the cell.
1613 1646 .It Sy "skipping vertical bar in tbl layout"
1614 1647 .Pq tbl
1615 1648 A table layout specification contains more than two consecutive vertical bars.
1616 1649 A double bar is printed, all additional bars are discarded.
1617 1650 .El
1618 1651 .Ss "Errors related to tables"
1619 1652 .Bl -ohang
1620 1653 .It Sy "non-alphabetic character in tbl options"
1621 1654 .Pq tbl
1622 1655 The table options line contains a character other than a letter,
1623 1656 blank, or comma where the beginning of an option name is expected.
1624 1657 The character is ignored.
1625 1658 .It Sy "skipping unknown tbl option"
1626 1659 .Pq tbl
1627 1660 The table options line contains a string of letters that does not
1628 1661 match any known option name.
1629 1662 The word is ignored.
1630 1663 .It Sy "missing tbl option argument"
1631 1664 .Pq tbl
1632 1665 A table option that requires an argument is not followed by an
1633 1666 opening parenthesis, or the opening parenthesis is immediately
1634 1667 followed by a closing parenthesis.
1635 1668 The option is ignored.
1636 1669 .It Sy "wrong tbl option argument size"
1637 1670 .Pq tbl
1638 1671 A table option argument contains an invalid number of characters.
1639 1672 Both the option and the argument are ignored.
1640 1673 .It Sy "empty tbl layout"
1641 1674 .Pq tbl
1642 1675 A table layout specification is completely empty,
1643 1676 specifying zero lines and zero columns.
1644 1677 As a fallback, a single left-justified column is used.
1645 1678 .It Sy "invalid character in tbl layout"
1646 1679 .Pq tbl
1647 1680 A table layout specification contains a character that can neither
1648 1681 be interpreted as a layout key character nor as a layout modifier,
1649 1682 or a modifier precedes the first key.
1650 1683 The invalid character is discarded.
1651 1684 .It Sy "unmatched parenthesis in tbl layout"
1652 1685 .Pq tbl
1653 1686 A table layout specification contains an opening parenthesis,
1654 1687 but no matching closing parenthesis.
1655 1688 The rest of the input line, starting from the parenthesis, has no effect.
1656 1689 .It Sy "tbl without any data cells"
1657 1690 .Pq tbl
1658 1691 A table does not contain any data cells.
1659 1692 It will probably produce no output.
1660 1693 .It Sy "ignoring data in spanned tbl cell"
1661 1694 .Pq tbl
1662 1695 A table cell is marked as a horizontal span
1663 1696 .Pq Sq Cm s
1664 1697 or vertical span
1665 1698 .Pq Sq Cm ^
1666 1699 in the table layout, but it contains data.
1667 1700 The data is ignored.
1668 1701 .It Sy "ignoring extra tbl data cells"
1669 1702 .Pq tbl
1670 1703 A data line contains more cells than the corresponding layout line.
1671 1704 The data in the extra cells is ignored.
1672 1705 .It Sy "data block open at end of tbl"
1673 1706 .Pq tbl
1674 1707 A data block is opened with
1675 1708 .Cm T{ ,
1676 1709 but never closed with a matching
1677 1710 .Cm T} .
1678 1711 The remaining data lines of the table are all put into one cell,
1679 1712 and any remaining cells stay empty.
1680 1713 .El
1681 1714 .Ss "Errors related to roff, mdoc, and man code"
1682 1715 .Bl -ohang
1683 1716 .It Sy "duplicate prologue macro"
1684 1717 .Pq mdoc
1685 1718 One of the prologue macros occurs more than once.
1686 1719 The last instance overrides all previous ones.
1687 1720 .It Sy "skipping late title macro"
1688 1721 .Pq mdoc
1689 1722 The
1690 1723 .Ic \&Dt
1691 1724 macro appears after the first non-prologue macro.
1692 1725 Traditional formatters cannot handle this because
1693 1726 they write the page header before parsing the document body.
1694 1727 Even though this technical restriction does not apply to
1695 1728 .Nm ,
1696 1729 traditional semantics is preserved.
1697 1730 The late macro is discarded including its arguments.
1698 1731 .It Sy "input stack limit exceeded, infinite loop?"
1699 1732 .Pq roff
1700 1733 Explicit recursion limits are implemented for the following features,
1701 1734 in order to prevent infinite loops:
1702 1735 .Bl -dash -compact
1703 1736 .It
1704 1737 expansion of nested escape sequences
1705 1738 including expansion of strings and number registers,
1706 1739 .It
1707 1740 expansion of nested user-defined macros,
1708 1741 .It
1709 1742 and
1710 1743 .Ic \&so
1711 1744 file inclusion.
1712 1745 .El
1713 1746 When a limit is hit, the output is incorrect, typically losing
1714 1747 some content, but the parser can continue.
1715 1748 .It Sy "skipping bad character"
1716 1749 .Pq mdoc , man , roff
1717 1750 The input file contains a byte that is not a printable
1718 1751 .Xr ascii 5
1719 1752 character.
1720 1753 The message mentions the character number.
1721 1754 The offending byte is replaced with a question mark
1722 1755 .Pq Sq \&? .
1723 1756 Consider editing the input file to replace the byte with an ASCII
1724 1757 transliteration of the intended character.
1725 1758 .It Sy "skipping unknown macro"
1726 1759 .Pq mdoc , man , roff
1727 1760 The first identifier on a request or macro line is neither recognized as a
1728 1761 .Xr mandoc_roff 5
1729 1762 request, nor as a user-defined macro, nor, respectively, as an
1730 1763 .Xr mdoc 5
1731 1764 or
1732 1765 .Xr man 5
1733 1766 macro.
1734 1767 It may be mistyped or unsupported.
1735 1768 The request or macro is discarded including its arguments.
1736 1769 .It Sy "skipping insecure request"
1737 1770 .Pq roff
1738 1771 An input file attempted to run a shell command
1739 1772 or to read or write an external file.
1740 1773 Such attempts are denied for security reasons.
1741 1774 .It Sy "skipping item outside list"
1742 1775 .Pq mdoc , eqn
1743 1776 An
1744 1777 .Ic \&It
1745 1778 macro occurs outside any
1746 1779 .Ic \&Bl
1747 1780 list, or an
1748 1781 .Xr eqn 5
1749 1782 .Ic above
1750 1783 delimiter occurs outside any pile.
1751 1784 It is discarded including its arguments.
1752 1785 .It Sy "skipping column outside column list"
1753 1786 .Pq mdoc
1754 1787 A
1755 1788 .Ic \&Ta
1756 1789 macro occurs outside any
1757 1790 .Ic \&Bl Fl column
1758 1791 block.
1759 1792 It is discarded including its arguments.
1760 1793 .It Sy "skipping end of block that is not open"
1761 1794 .Pq mdoc , man , eqn , tbl , roff
1762 1795 Various syntax elements can only be used to explicitly close blocks
1763 1796 that have previously been opened.
1764 1797 An
1765 1798 .Xr mdoc 5
1766 1799 block closing macro, a
1767 1800 .Xr man 5
1768 1801 .Ic \&ME, \&RE
1769 1802 or
1770 1803 .Ic \&UE
1771 1804 macro, an
1772 1805 .Xr eqn 5
1773 1806 right delimiter or closing brace, or the end of an equation, table, or
1774 1807 .Xr mandoc_roff 5
1775 1808 conditional request is encountered but no matching block is open.
1776 1809 The offending request or macro is discarded.
1777 1810 .It Sy "fewer RS blocks open, skipping"
1778 1811 .Pq man
1779 1812 The
1780 1813 .Ic \&RE
1781 1814 macro is invoked with an argument, but less than the specified number of
1782 1815 .Ic \&RS
1783 1816 blocks is open.
1784 1817 The
1785 1818 .Ic \&RE
1786 1819 macro is discarded.
1787 1820 .It Sy "inserting missing end of block"
1788 1821 .Pq mdoc , tbl
1789 1822 Various
1790 1823 .Xr mdoc 5
1791 1824 macros as well as tables require explicit closing by dedicated macros.
1792 1825 A block that doesn't support bad nesting
1793 1826 ends before all of its children are properly closed.
1794 1827 The open child nodes are closed implicitly.
1795 1828 .It Sy "appending missing end of block"
1796 1829 .Pq mdoc , man , eqn , tbl , roff
1797 1830 At the end of the document, an explicit
1798 1831 .Xr mdoc 5
1799 1832 block, a
1800 1833 .Xr man 5
1801 1834 next-line scope or
1802 1835 .Ic \&MT , \&RS
1803 1836 or
1804 1837 .Ic \&UR
1805 1838 block, an equation, table, or
1806 1839 .Xr mandoc_roff 5
1807 1840 conditional or ignore block is still open.
1808 1841 The open block is closed implicitly.
1809 1842 .It Sy "escaped character not allowed in a name"
1810 1843 .Pq roff
1811 1844 Macro, string and register identifiers consist of printable,
1812 1845 non-whitespace ASCII characters.
1813 1846 Escape sequences and characters and strings expressed in terms of them
1814 1847 cannot form part of a name.
1815 1848 The first argument of an
1816 1849 .Ic \&am ,
1817 1850 .Ic \&as ,
1818 1851 .Ic \&de ,
1819 1852 .Ic \&ds ,
1820 1853 .Ic \&nr ,
1821 1854 or
1822 1855 .Ic \&rr
1823 1856 request, or any argument of an
1824 1857 .Ic \&rm
1825 1858 request, or the name of a request or user defined macro being called,
1826 1859 is terminated by an escape sequence.
1827 1860 In the cases of
1828 1861 .Ic \&as ,
1829 1862 .Ic \&ds ,
1830 1863 and
1831 1864 .Ic \&nr ,
1832 1865 the request has no effect at all.
1833 1866 In the cases of
1834 1867 .Ic \&am ,
1835 1868 .Ic \&de ,
1836 1869 .Ic \&rr ,
1837 1870 and
1838 1871 .Ic \&rm ,
1839 1872 what was parsed up to this point is used as the arguments to the request,
1840 1873 and the rest of the input line is discarded including the escape sequence.
1841 1874 When parsing for a request or a user-defined macro name to be called,
1842 1875 only the escape sequence is discarded.
1843 1876 The characters preceding it are used as the request or macro name,
1844 1877 the characters following it are used as the arguments to the request or macro.
1845 1878 .It Sy "NOT IMPLEMENTED: Bd -file"
1846 1879 .Pq mdoc
1847 1880 For security reasons, the
1848 1881 .Ic \&Bd
1849 1882 macro does not support the
1850 1883 .Fl file
1851 1884 argument.
1852 1885 By requesting the inclusion of a sensitive file, a malicious document
1853 1886 might otherwise trick a privileged user into inadvertently displaying
1854 1887 the file on the screen, revealing the file content to bystanders.
1855 1888 The argument is ignored including the file name following it.
1856 1889 .It Sy "skipping display without arguments"
1857 1890 .Pq mdoc
1858 1891 A
1859 1892 .Ic \&Bd
1860 1893 block macro does not have any arguments.
1861 1894 The block is discarded, and the block content is displayed in
1862 1895 whatever mode was active before the block.
1863 1896 .It Sy "missing list type, using -item"
1864 1897 .Pq mdoc
1865 1898 A
1866 1899 .Ic \&Bl
1867 1900 macro fails to specify the list type.
1868 1901 .It Sy "argument is not numeric, using 1"
1869 1902 .Pq roff
1870 1903 The argument of a
1871 1904 .Ic \&ce
1872 1905 request is not a number.
1873 1906 .It Sy "missing manual name, using \(dq\(dq"
1874 1907 .Pq mdoc
1875 1908 The first call to
1876 1909 .Ic \&Nm ,
1877 1910 or any call in the NAME section, lacks the required argument.
1878 1911 .It Sy "uname(3) system call failed, using UNKNOWN"
1879 1912 .Pq mdoc
1880 1913 The
1881 1914 .Ic \&Os
1882 1915 macro is called without arguments, and the
1883 1916 .Xr uname 3
1884 1917 system call failed.
1885 1918 As a workaround,
1886 1919 .Nm
1887 1920 can be compiled with
1888 1921 .Sm off
1889 1922 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1890 1923 .Sm on
1891 1924 .It Sy "unknown standard specifier"
1892 1925 .Pq mdoc
1893 1926 An
1894 1927 .Ic \&St
1895 1928 macro has an unknown argument and is discarded.
1896 1929 .It Sy "skipping request without numeric argument"
1897 1930 .Pq roff , eqn
1898 1931 An
1899 1932 .Ic \&it
1900 1933 request or an
1901 1934 .Xr eqn 5
1902 1935 .Ic \&size
1903 1936 or
1904 1937 .Ic \&gsize
1905 1938 statement has a non-numeric or negative argument or no argument at all.
1906 1939 The invalid request or statement is ignored.
1907 1940 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1908 1941 .Pq roff
1909 1942 For security reasons,
1910 1943 .Nm
1911 1944 allows
1912 1945 .Ic \&so
1913 1946 file inclusion requests only with relative paths
1914 1947 and only without ascending to any parent directory.
1915 1948 By requesting the inclusion of a sensitive file, a malicious document
1916 1949 might otherwise trick a privileged user into inadvertently displaying
1917 1950 the file on the screen, revealing the file content to bystanders.
1918 1951 .Nm
1919 1952 only shows the path as it appears behind
1920 1953 .Ic \&so .
1921 1954 .It Sy ".so request failed"
1922 1955 .Pq roff
1923 1956 Servicing a
1924 1957 .Ic \&so
1925 1958 request requires reading an external file, but the file could not be
1926 1959 opened.
1927 1960 .Nm
1928 1961 only shows the path as it appears behind
1929 1962 .Ic \&so .
1930 1963 .It Sy "skipping all arguments"
1931 1964 .Pq mdoc , man , eqn , roff
1932 1965 An
1933 1966 .Xr mdoc 5
1934 1967 .Ic \&Bt ,
1935 1968 .Ic \&Ed ,
1936 1969 .Ic \&Ef ,
1937 1970 .Ic \&Ek ,
1938 1971 .Ic \&El ,
1939 1972 .Ic \&Lp ,
1940 1973 .Ic \&Pp ,
1941 1974 .Ic \&Re ,
1942 1975 .Ic \&Rs ,
1943 1976 or
1944 1977 .Ic \&Ud
1945 1978 macro, an
1946 1979 .Ic \&It
1947 1980 macro in a list that don't support item heads, a
1948 1981 .Xr man 5
1949 1982 .Ic \&LP ,
1950 1983 .Ic \&P ,
1951 1984 or
1952 1985 .Ic \&PP
1953 1986 macro, an
1954 1987 .Xr eqn 5
1955 1988 .Ic \&EQ
1956 1989 or
1957 1990 .Ic \&EN
1958 1991 macro, or a
1959 1992 .Xr mandoc_roff 5
1960 1993 .Ic \&br ,
1961 1994 .Ic \&fi ,
1962 1995 or
1963 1996 .Ic \&nf
1964 1997 request or
1965 1998 .Sq \&..
1966 1999 block closing request is invoked with at least one argument.
1967 2000 All arguments are ignored.
1968 2001 .It Sy "skipping excess arguments"
1969 2002 .Pq mdoc , man , roff
1970 2003 A macro or request is invoked with too many arguments:
1971 2004 .Bl -dash -offset 2n -width 2n -compact
1972 2005 .It
1973 2006 .Ic \&Fo ,
1974 2007 .Ic \&MT ,
1975 2008 .Ic \&PD ,
1976 2009 .Ic \&RS ,
1977 2010 .Ic \&UR ,
1978 2011 .Ic \&ft ,
1979 2012 or
1980 2013 .Ic \&sp
1981 2014 with more than one argument
1982 2015 .It
1983 2016 .Ic \&An
1984 2017 with another argument after
1985 2018 .Fl split
1986 2019 or
1987 2020 .Fl nosplit
1988 2021 .It
1989 2022 .Ic \&RE
1990 2023 with more than one argument or with a non-integer argument
1991 2024 .It
1992 2025 .Ic \&OP
1993 2026 or a request of the
1994 2027 .Ic \&de
1995 2028 family with more than two arguments
1996 2029 .It
1997 2030 .Ic \&Dt
1998 2031 with more than three arguments
1999 2032 .It
2000 2033 .Ic \&TH
2001 2034 with more than five arguments
2002 2035 .It
2003 2036 .Ic \&Bd ,
2004 2037 .Ic \&Bk ,
2005 2038 or
2006 2039 .Ic \&Bl
2007 2040 with invalid arguments
2008 2041 .El
2009 2042 The excess arguments are ignored.
2010 2043 .El
2011 2044 .Ss Unsupported features
2012 2045 .Bl -ohang
2013 2046 .It Sy "input too large"
2014 2047 .Pq mdoc , man
2015 2048 Currently,
2016 2049 .Nm
2017 2050 cannot handle input files larger than its arbitrary size limit
2018 2051 of 2^31 bytes (2 Gigabytes).
2019 2052 Since useful manuals are always small, this is not a problem in practice.
2020 2053 Parsing is aborted as soon as the condition is detected.
2021 2054 .It Sy "unsupported control character"
2022 2055 .Pq roff
2023 2056 An ASCII control character supported by other
2024 2057 .Xr mandoc_roff 5
2025 2058 implementations but not by
2026 2059 .Nm
2027 2060 was found in an input file.
2028 2061 It is replaced by a question mark.
2029 2062 .It Sy "unsupported roff request"
2030 2063 .Pq roff
2031 2064 An input file contains a
2032 2065 .Xr mandoc_roff 5
2033 2066 request supported by GNU troff or Heirloom troff but not by
2034 2067 .Nm ,
2035 2068 and it is likely that this will cause information loss
2036 2069 or considerable misformatting.
2037 2070 .It Sy "eqn delim option in tbl"
2038 2071 .Pq eqn , tbl
2039 2072 The options line of a table defines equation delimiters.
2040 2073 Any equation source code contained in the table will be printed unformatted.
2041 2074 .It Sy "unsupported table layout modifier"
2042 2075 .Pq tbl
2043 2076 A table layout specification contains an
2044 2077 .Sq Cm m
2045 2078 modifier.
2046 2079 The modifier is discarded.
2047 2080 .It Sy "ignoring macro in table"
2048 2081 .Pq tbl , mdoc , man
2049 2082 A table contains an invocation of an
2050 2083 .Xr mdoc 5
2051 2084 or
2052 2085 .Xr man 5
2053 2086 macro or of an undefined macro.
2054 2087 The macro is ignored, and its arguments are handled
2055 2088 as if they were a text line.
2056 2089 .El
2057 2090 .Sh SEE ALSO
2058 2091 .Xr eqn 5 ,
2059 2092 .Xr man 5 ,
2060 2093 .Xr mandoc_char 5 ,
2061 2094 .Xr mandoc_roff 5 ,
2062 2095 .Xr mdoc 5 ,
2063 2096 .Xr tbl 5
2064 2097 .Sh HISTORY
2065 2098 The
2066 2099 .Nm
2067 2100 utility first appeared in
2068 2101 .Ox 4.8 .
2069 2102 The option
2070 2103 .Fl I
2071 2104 appeared in
2072 2105 .Ox 5.2 ,
2073 2106 and
2074 2107 .Fl aCcfhKklMSsw
2075 2108 in
2076 2109 .Ox 5.7 .
2077 2110 .Sh AUTHORS
2078 2111 .An -nosplit
2079 2112 The
2080 2113 .Nm
2081 2114 utility was written by
2082 2115 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
2083 2116 and is maintained by
2084 2117 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
|
↓ open down ↓ |
1191 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX