version 1.223, 2018/04/13 19:55:30 |
version 1.225, 2018/05/03 14:21:46 |
|
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
utility formats |
utility formats manual pages for display. |
.Ux |
|
manual pages for display. |
|
.Pp |
.Pp |
By default, |
By default, |
.Nm |
.Nm |
Line 132 With other arguments, |
|
Line 130 With other arguments, |
|
is silently ignored. |
is silently ignored. |
.It Fl O Ar options |
.It Fl O Ar options |
Comma-separated output options. |
Comma-separated output options. |
|
See the descriptions of the individual output formats for supported |
|
.Ar options . |
.It Fl T Ar output |
.It Fl T Ar output |
Output format. |
Select the output format. |
See |
Supported values for the |
.Sx Output Formats |
.Ar output |
for available formats. |
argument are |
Defaults to |
.Cm ascii , |
.Fl T Cm locale . |
.Cm html , |
|
the default of |
|
.Cm locale , |
|
.Cm man , |
|
.Cm markdown , |
|
.Cm pdf , |
|
.Cm ps , |
|
.Cm tree , |
|
and |
|
.Cm utf8 . |
|
.Pp |
|
The special |
|
.Fl T Cm lint |
|
mode only parses the input and produces no output. |
|
It implies |
|
.Fl W Cm all |
|
and redirects parser messages, which usually appear on standard |
|
error output, to standard output. |
.It Fl W Ar level |
.It Fl W Ar level |
Specify the minimum message |
Specify the minimum message |
.Ar level |
.Ar level |
|
|
are requested, they can be joined with a comma, for example |
are requested, they can be joined with a comma, for example |
.Fl W Cm error , Ns Cm stop . |
.Fl W Cm error , Ns Cm stop . |
.It Ar file |
.It Ar file |
Read input from zero or more files. |
Read from the given input file. |
If unspecified, reads from stdin. |
If multiple files are specified, they are processed in the given order. |
If multiple files are specified, |
If unspecified, |
.Nm |
.Nm |
will halt with the first failed parse. |
reads from standard input. |
.El |
.El |
.Pp |
.Pp |
The options |
The options |
|
|
The options |
The options |
.Fl fkl |
.Fl fkl |
are mutually exclusive and override each other. |
are mutually exclusive and override each other. |
.Ss Output Formats |
|
The |
|
.Nm |
|
utility accepts the following |
|
.Fl T |
|
arguments, which correspond to output modes: |
|
.Bl -tag -width "-T markdown" |
|
.It Fl T Cm ascii |
|
Produce 7-bit ASCII output. |
|
See |
|
.Sx ASCII Output . |
|
.It Fl T Cm html |
|
Produce HTML5, CSS1, and MathML output. |
|
See |
|
.Sx HTML Output . |
|
.It Fl T Cm lint |
|
Parse only: produce no output. |
|
Implies |
|
.Fl W Cm all |
|
and redirects parser messages, which usually appear |
|
on standard error output, to standard output. |
|
.It Fl T Cm locale |
|
Encode output using the current locale. |
|
This is the default. |
|
See |
|
.Sx Locale Output . |
|
.It Fl T Cm man |
|
Produce |
|
.Xr man 7 |
|
format output. |
|
See |
|
.Sx Man Output . |
|
.It Fl T Cm markdown |
|
Produce output in |
|
.Sy markdown |
|
format. |
|
See |
|
.Sx Markdown Output . |
|
.It Fl T Cm pdf |
|
Produce PDF output. |
|
See |
|
.Sx PDF Output . |
|
.It Fl T Cm ps |
|
Produce PostScript output. |
|
See |
|
.Sx PostScript Output . |
|
.It Fl T Cm tree |
|
Produce an indented parse tree. |
|
See |
|
.Sx Syntax tree output . |
|
.It Fl T Cm utf8 |
|
Encode output in the UTF\-8 multi-byte format. |
|
See |
|
.Sx UTF\-8 Output . |
|
.El |
|
.Pp |
|
If multiple input files are specified, these will be processed by the |
|
corresponding filter in-order. |
|
.Ss ASCII Output |
.Ss ASCII Output |
Output produced by |
Use |
.Fl T Cm ascii |
.Fl T Cm ascii |
is rendered in standard 7-bit ASCII documented in |
to force text output in 7-bit ASCII character encoding documented in the |
.Xr ascii 7 . |
.Xr ascii 7 |
|
manual page, ignoring the |
|
.Xr locale 1 |
|
set in the environment. |
.Pp |
.Pp |
Font styles are applied by using back-spaced encoding such that an |
Font styles are applied by using back-spaced encoding such that an |
underlined character |
underlined character |
Line 356 defaults to simple output (via an embedded style-sheet |
|
Line 318 defaults to simple output (via an embedded style-sheet |
|
readable in any graphical or text-based web |
readable in any graphical or text-based web |
browser. |
browser. |
.Pp |
.Pp |
Special characters are rendered in decimal-encoded UTF\-8. |
Non-ASCII characters are rendered |
|
as hexadecimal Unicode character references. |
.Pp |
.Pp |
The following |
The following |
.Fl O |
.Fl O |
Line 406 This must be a valid absolute or |
|
Line 369 This must be a valid absolute or |
|
relative URI. |
relative URI. |
.El |
.El |
.Ss Locale Output |
.Ss Locale Output |
Locale-depending output encoding is triggered with |
By default, |
|
.Nm |
|
automatically selects UTF-8 or ASCII output according to the current |
|
.Xr locale 1 . |
|
If any of the environment variables |
|
.Ev LC_ALL , |
|
.Ev LC_CTYPE , |
|
or |
|
.Ev LANG |
|
are set and the first one that is set |
|
selects the UTF-8 character encoding, it produces |
|
.Sx UTF-8 Output ; |
|
otherwise, it falls back to |
|
.Sx ASCII Output . |
|
This output mode can also be selected explicitly with |
.Fl T Cm locale . |
.Fl T Cm locale . |
This is the default. |
|
.Pp |
|
This option is not available on all systems: systems without locale |
|
support, or those whose internal representation is not natively UCS-4, |
|
will fall back to |
|
.Fl T Cm ascii . |
|
See |
|
.Sx ASCII Output |
|
for font style specification and available command-line arguments. |
|
.Ss Man Output |
.Ss Man Output |
Translate input format into |
Use |
|
.Fl T Cm man |
|
to translate |
|
.Xr mdoc 7 |
|
input into |
.Xr man 7 |
.Xr man 7 |
output format. |
output format. |
This is useful for distributing manual sources to legacy systems |
This is useful for distributing manual sources to legacy systems |
|
|
.Xr mdoc 7 |
.Xr mdoc 7 |
formatters. |
formatters. |
.Pp |
.Pp |
If |
If the input format of a file is |
.Xr mdoc 7 |
|
is passed as input, it is translated into |
|
.Xr man 7 . |
|
If the input format is |
|
.Xr man 7 , |
.Xr man 7 , |
the input is copied to the output, expanding any |
the input is copied to the output, expanding any |
.Xr roff 7 |
.Xr roff 7 |
Line 442 level controls which |
|
Line 410 level controls which |
|
.Sx DIAGNOSTICS |
.Sx DIAGNOSTICS |
are displayed before copying the input to the output. |
are displayed before copying the input to the output. |
.Ss Markdown Output |
.Ss Markdown Output |
Translate |
Use |
|
.Fl T Cm markdown |
|
to translate |
.Xr mdoc 7 |
.Xr mdoc 7 |
input to the |
input to the markdown format conforming to |
.Sy markdown |
|
format conforming to |
|
.Lk http://daringfireball.net/projects/markdown/syntax.text\ |
.Lk http://daringfireball.net/projects/markdown/syntax.text\ |
"John Gruber's 2004 specification" . |
"John Gruber's 2004 specification" . |
The output also almost conforms to the |
The output also almost conforms to the |
Line 517 If an unknown value is encountered, |
|
Line 485 If an unknown value is encountered, |
|
.Ar letter |
.Ar letter |
is used. |
is used. |
.El |
.El |
.Ss UTF\-8 Output |
.Ss UTF-8 Output |
Use |
Use |
.Fl T Cm utf8 |
.Fl T Cm utf8 |
to force a UTF\-8 locale. |
to force text output in UTF-8 multi-byte character encoding, |
|
ignoring the |
|
.Xr locale 1 |
|
settings in the environment. |
See |
See |
.Sx Locale Output |
.Sx ASCII Output |
for details and options. |
regarding font styles and |
|
.Fl O |
|
arguments. |
|
.Pp |
|
On operating systems lacking locale or wide character support, and |
|
on those where the internal character representation is not UCS-4, |
|
.Nm |
|
always falls back to |
|
.Sx ASCII Output . |
.Ss Syntax tree output |
.Ss Syntax tree output |
Use |
Use |
.Fl T Cm tree |
.Fl T Cm tree |
Line 592 Meta data is not available in this case. |
|
Line 571 Meta data is not available in this case. |
|
.El |
.El |
.Sh ENVIRONMENT |
.Sh ENVIRONMENT |
.Bl -tag -width MANPAGER |
.Bl -tag -width MANPAGER |
|
.It Ev LC_CTYPE |
|
The character encoding |
|
.Xr locale 1 . |
|
When |
|
.Sx Locale Output |
|
is selected, it decides whether to use ASCII or UTF-8 output format. |
|
It never affects the interpretation of input files. |
.It Ev MANPAGER |
.It Ev MANPAGER |
Any non-empty value of the environment variable |
Any non-empty value of the environment variable |
.Ev MANPAGER |
.Ev MANPAGER |