logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

mandoc.1 (58653B)


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