Print this page
9718 update mandoc to 1.14.4
@@ -6,11 +6,11 @@
SYNOPSIS
mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
[-T output] [-W level] [file ...]
DESCRIPTION
- The mandoc utility formats UNIX manual pages for display.
+ The mandoc utility formats manual pages for display.
By default, mandoc reads mdoc(5) or man(5) text from stdin and produces
-T locale output.
The options are as follows:
@@ -50,21 +50,27 @@
-mdoc | -man
With -mdoc, all input files are interpreted as mdoc(5). With
-man, all input files are interpreted as man(5). By default, the
input language is automatically detected for each file: if the
- the first macro is Dd or Dt, the mdoc(5) parser is used;
- otherwise, the man(5) parser is used. With other arguments, -m
- is silently ignored.
+ first macro is Dd or Dt, the mdoc(5) parser is used; otherwise,
+ the man(5) parser is used. With other arguments, -m is silently
+ ignored.
-O options
- Comma-separated output options.
+ Comma-separated output options. See the descriptions of the
+ individual output formats for supported options.
-T output
- Output format. See Output Formats for available formats.
- Defaults to -T locale.
+ Select the output format. Supported values for the output
+ argument are ascii, html, the default of locale, man, markdown,
+ pdf, ps, tree, and utf8.
+ The special -T lint mode only parses the input and produces no
+ output. It implies -W all and redirects parser messages, which
+ usually appear on standard error output, to standard output.
+
-W level
Specify the minimum message level to be reported on the standard
error output and to affect the exit status. The level can be
base, style, warning, error, or unsupp. The base level
automatically derives the operating system from the contents of
@@ -79,70 +85,49 @@
file that causes warnings or errors of at least the requested
level. No formatted output will be produced from that file. If
both a level and stop are requested, they can be joined with a
comma, for example -W error,stop.
- file Read input from zero or more files. If unspecified, reads from
- stdin. If multiple files are specified, mandoc will halt with
- the first failed parse.
+ file Read from the given input file. If multiple files are specified,
+ they are processed in the given order. If unspecified, mandoc
+ reads from standard input.
- Output Formats
- The mandoc utility accepts the following -T arguments, which correspond
- to output modes:
-
- -T ascii Produce 7-bit ASCII output. See ASCII Output.
-
- -T html Produce HTML5, CSS1, and MathML output. See HTML Output.
-
- -Tlint Parse only: produce no output. Implies -W all and redirects
- parser messages, which usually appear on standard error
- output, to standard output.
-
- -T locale Encode output using the current locale. This is the
- default. See Locale Output.
-
- -T man Produce man(5) format output. See Man Output.
-
- -T markdown Produce output in markdown format. See Markdown Output.
-
- -T pdf Produce PDF output. See PDF Output.
-
- -T ps Produce PostScript output. See PostScript Output.
-
- -T tree Produce an indented parse tree.
-
- -T utf8 Encode output in the UTF-8 multi-byte format. See UTF-8
- Output.
-
- If multiple input files are specified, these will be processed by the
- corresponding filter in-order.
-
ASCII Output
- Output produced by -T ascii is rendered in standard 7-bit ASCII
- documented in ascii(5).
+ Use -T ascii to force text output in 7-bit ASCII character encoding
+ documented in the ascii(5) manual page, ignoring the locale(1) set in the
+ environment.
Font styles are applied by using back-spaced encoding such that an
underlined character `c' is rendered as `_\[bs]c', where `\[bs]' is the
back-space character number 8. Emboldened characters are rendered as
`c\[bs]c'.
The special characters documented in mandoc_char(5) are rendered best-
effort in an ASCII equivalent.
- Output width is limited to 78 visible columns unless literal input lines
- exceed this limit.
-
The following -O arguments are accepted:
indent=indent
The left margin for normal text is set to indent blank characters
instead of the default of five for mdoc(5) and seven for man(5).
Increasing this is not recommended; it may result in degraded
- formatting, for example overfull lines or ugly line breaks.
+ formatting, for example overfull lines or ugly line breaks. When
+ output is to a pager on a terminal that is less than 66 columns
+ wide, the default is reduced to three columns.
+ mdoc Format man(5) input files in mdoc(5) output style. Specifically,
+ this suppresses the two additional blank lines near the top and
+ the bottom of each page, and it implies -O indent=5. One useful
+ application is for checking that -T man output formats in the
+ same way as the mdoc(5) source it was generated from.
+
width=width
- The output width is set to width.
+ The output width is set to width instead of the default of 78.
+ When output is to a pager on a terminal that is less than 79
+ columns wide, the default is reduced to one less than the
+ terminal width. In any case, lines that are output in literal
+ mode are never wrapped and may exceed the output width.
HTML Output
Output produced by -T html conforms to HTML5 using optional self-closing
tags. Default styles use only CSS1. Equations rendered from eqn(5)
blocks use MathML.
@@ -150,11 +135,12 @@
The mandoc.css file documents style-sheet classes available for
customising output. If a style-sheet is not specified with -O style, -T
html defaults to simple output (via an embedded style-sheet) readable in
any graphical or text-based web browser.
- Special characters are rendered in decimal-encoded UTF-8.
+ Non-ASCII characters are rendered as hexadecimal Unicode character
+ references.
The following -O arguments are accepted:
fragment
Omit the <!DOCTYPE> declaration and the <html>, <head>, and
@@ -178,26 +164,30 @@
style=style.css
The file style.css is used for an external style-sheet. This
must be a valid absolute or relative URI.
Locale Output
- Locale-depending output encoding is triggered with -T locale. This is
- the default.
+ By default, mandoc automatically selects UTF-8 or ASCII output according
+ to the current locale(1). If any of the environment variables LC_ALL,
+ LC_CTYPE, or LANG are set and the first one that is set selects the UTF-8
+ character encoding, it produces UTF-8 Output; otherwise, it falls back to
+ ASCII Output. This output mode can also be selected explicitly with -T
+ locale.
Man Output
- Translate input format into man(5) output format. This is useful for
- distributing manual sources to legacy systems lacking mdoc(5) formatters.
+ Use -T man to translate mdoc(5) input into man(5) output format. This is
+ useful for distributing manual sources to legacy systems lacking mdoc(5)
+ formatters.
- If mdoc(5) is passed as input, it is translated into man(5). If the
- input format is man(5), the input is copied to the output, expanding any
- mandoc_roff(5) so requests. The parser is also run, and as usual, the -W
- level controls which DIAGNOSTICS are displayed before copying the input
- to the output.
+ If the input format of a file is man(5), the input is copied to the
+ output, expanding any mandoc_roff(5) so requests. The parser is also
+ run, and as usual, the -W level controls which DIAGNOSTICS are displayed
+ before copying the input to the output.
Markdown Output
- Translate mdoc(5) input to the markdown format conforming to John
- Gruber's 2004 specification:
+ Use -T markdown to translate mdoc(5) input to the markdown format
+ conforming to John Gruber's 2004 specification:
http://daringfireball.net/projects/markdown/syntax.text. The output also
almost conforms to the CommonMark: http://commonmark.org/ specification.
The character set used for the markdown output is ASCII. Non-ASCII
characters are encoded as HTML entities. Since that is not possible in
@@ -232,13 +222,18 @@
You may also manually specify dimensions as NNxNN, width by
height in millimetres. If an unknown value is encountered,
letter is used.
UTF-8 Output
- Use -T utf8 to force a UTF-8 locale. See Locale Output for details and
- options.
+ Use -T utf8 to force text output in UTF-8 multi-byte character encoding,
+ ignoring the locale(1) settings in the environment. See ASCII Output
+ regarding font styles and -O arguments.
+ On operating systems lacking locale or wide character support, and on
+ those where the internal character representation is not UCS-4, mandoc
+ always falls back to ASCII Output.
+
Syntax tree output
Use -T tree to show a human readable representation of the syntax tree.
It is useful for debugging the source code of manual pages. The exact
format is subject to change, so don't write parsers for it.
@@ -270,10 +265,16 @@
noval Skip validation and show the unvalidated syntax tree. This can
help to find out whether a given behaviour is caused by the
parser or by the validator. Meta data is not available in this
case.
+ENVIRONMENT
+ LC_CTYPE The character encoding locale(1). When Locale Output is
+ selected, it decides whether to use ASCII or UTF-8
+ output format. It never affects the interpretation of
+ input files.
+
EXIT STATUS
The mandoc utility exits with one of the following values, controlled by
the message level associated with the -W option:
0 No base system convention violations, style suggestions,
@@ -354,11 +355,11 @@
tries to reduce the probability that issues go unnoticed, so it
may occasionally issue bogus suggestions. Please use your good
judgement to decide whether any particular style suggestion
really justifies a change to the input file.
- base A convertion used in the base system of a specific operating
+ base A convention used in the base system of a specific operating
system is not adhered to. These are not markup mistakes, and
neither the quality of formatting nor portability are in danger.
Messages of the base level are printed with the more intuitive
style level tag.
@@ -405,19 +406,24 @@
legacy man(7) date format
(mdoc) The Dd macro uses the legacy man(5) date format "yyyy-dd-mm".
Consider using the conventional mdoc(5) date format "Month dd, yyyy"
instead.
+ normalizing date format to: ...
+ (mdoc, man) The Dd or TH macro provides an abbreviated month name or a
+ day number with a leading zero. In the formatted output, the month name
+ is written out in full and the leading zero is omitted.
+
lower case character in document title
(mdoc, man) The title is still used as given in the Dt or TH macro.
duplicate RCS id
A single manual page contains two copies of the RCS identifier for the
same operating system. Consider deleting the later instance and moving
the first one up to the top of the page.
- typo in section name
+ possible typo in section name
(mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
similar, but not identical to a standard section name.
unterminated quoted argument
(roff) Macro arguments can be enclosed in double quote characters such
@@ -458,10 +464,15 @@
fill mode already disabled, skipping
(man) An nf request occurs even though the document already switched to
no-fill mode and did not switch back to fill mode yet. It has no effect.
+ verbatim "--", maybe consider using \(em
+ (mdoc) Even though the ASCII output device renders an em-dash as "--",
+ that is not a good way to write it in an input file because it renders
+ poorly on all other output devices.
+
function name without markup
(mdoc) A word followed by an empty pair of parentheses occurs on a text
line. Consider using an Fn or Xr macro.
whitespace at end of input line
@@ -1099,6 +1110,6 @@
AUTHORS
The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
is maintained by Ingo Schwarze <schwarze@openbsd.org>.
-illumos July 20, 2017 illumos
+illumos July 28, 2018 illumos