version 1.218, 2017/08/19 22:00:05 |
version 1.229, 2018/10/02 12:33:37 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2012, 2014-2018 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.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 |
|
|
all input files are interpreted as |
all input files are interpreted as |
.Xr man 7 . |
.Xr man 7 . |
By default, the input language is automatically detected for each file: |
By default, the input language is automatically detected for each file: |
if the the first macro is |
if the first macro is |
.Ic \&Dd |
.Ic \&Dd |
or |
or |
.Ic \&Dt , |
.Ic \&Dt , |
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 299 The special characters documented in |
|
Line 261 The special characters documented in |
|
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
are rendered best-effort in an ASCII equivalent. |
are rendered best-effort in an ASCII equivalent. |
.Pp |
.Pp |
Output width is limited to 78 visible columns unless literal input lines |
|
exceed this limit. |
|
.Pp |
|
The following |
The following |
.Fl O |
.Fl O |
arguments are accepted: |
arguments are accepted: |
|
|
.Xr man 7 . |
.Xr man 7 . |
Increasing this is not recommended; it may result in degraded formatting, |
Increasing this is not recommended; it may result in degraded formatting, |
for example overfull lines or ugly line breaks. |
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. |
.It Cm mdoc |
.It Cm mdoc |
Format |
Format |
.Xr man 7 |
.Xr man 7 |
Line 331 output formats in the same way as the |
|
Line 292 output formats in the same way as the |
|
source it was generated from. |
source it was generated from. |
.It Cm width Ns = Ns Ar width |
.It Cm width Ns = Ns Ar width |
The output width is set to |
The output width is set to |
.Ar width . |
.Ar 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. |
.El |
.El |
.Ss HTML Output |
.Ss HTML Output |
Output produced by |
Output produced by |
Line 352 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 |
|
|
are replaced with the include filename. |
are replaced with the include filename. |
The default is not to present a |
The default is not to present a |
hyperlink. |
hyperlink. |
.It Cm man Ns = Ns Ar fmt |
.It Cm man Ns = Ns Ar fmt Ns Op ; Ns Ar fmt |
The string |
The string |
.Ar fmt , |
.Ar fmt , |
for example, |
for example, |
Line 394 are replaced with the linked manual's name and section |
|
Line 361 are replaced with the linked manual's name and section |
|
If no section is included, section 1 is assumed. |
If no section is included, section 1 is assumed. |
The default is not to |
The default is not to |
present a hyperlink. |
present a hyperlink. |
|
If two formats are given and a file |
|
.Ar %N.%S |
|
exists in the current directory, the first format is used; |
|
otherwise, the second format is used. |
.It Cm style Ns = Ns Ar style.css |
.It Cm style Ns = Ns Ar style.css |
The file |
The file |
.Ar style.css |
.Ar style.css |
Line 402 This must be a valid absolute or |
|
Line 373 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 438 level controls which |
|
Line 414 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 513 If an unknown value is encountered, |
|
Line 489 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 588 Meta data is not available in this case. |
|
Line 575 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 |
Line 755 Please use your good judgement to decide whether any p |
|
Line 749 Please use your good judgement to decide whether any p |
|
.Cm style |
.Cm style |
suggestion really justifies a change to the input file. |
suggestion really justifies a change to the input file. |
.It Cm base |
.It Cm base |
A convertion used in the base system of a specific operating system |
A convention used in the base system of a specific operating system |
is not adhered to. |
is not adhered to. |
These are not markup mistakes, and neither the quality of formatting |
These are not markup mistakes, and neither the quality of formatting |
nor portability are in danger. |
nor portability are in danger. |
Line 863 Consider using the conventional |
|
Line 857 Consider using the conventional |
|
date format |
date format |
.Dq "Month dd, yyyy" |
.Dq "Month dd, yyyy" |
instead. |
instead. |
|
.It Sy "normalizing date format to" : No ... |
|
.Pq mdoc , man |
|
The |
|
.Ic \&Dd |
|
or |
|
.Ic \&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. |
.It Sy "lower case character in document title" |
.It Sy "lower case character in document title" |
.Pq mdoc , man |
.Pq mdoc , man |
The title is still used as given in the |
The title is still used as given in the |
Line 875 A single manual page contains two copies of the RCS id |
|
Line 879 A single manual page contains two copies of the RCS id |
|
the same operating system. |
the same operating system. |
Consider deleting the later instance and moving the first one up |
Consider deleting the later instance and moving the first one up |
to the top of the page. |
to the top of the page. |
.It Sy "typo in section name" |
.It Sy "possible typo in section name" |
.Pq mdoc |
.Pq mdoc |
Fuzzy string matching revealed that the argument of an |
Fuzzy string matching revealed that the argument of an |
.Ic \&Sh |
.Ic \&Sh |
|
|
request occurs even though the document already switched to no-fill mode |
request occurs even though the document already switched to no-fill mode |
and did not switch back to fill mode yet. |
and did not switch back to fill mode yet. |
It has no effect. |
It has no effect. |
|
.It Sy "verbatim \(dq--\(dq, maybe consider using \e(em" |
|
.Pq mdoc |
|
Even though the ASCII output device renders an em-dash as |
|
.Qq \-\- , |
|
that is not a good way to write it in an input file |
|
because it renders poorly on all other output devices. |
.It Sy "function name without markup" |
.It Sy "function name without markup" |
.Pq mdoc |
.Pq mdoc |
A word followed by an empty pair of parentheses occurs on a text line. |
A word followed by an empty pair of parentheses occurs on a text line. |
|
|
.Cm off . |
.Cm off . |
The invalid argument is moved out of the macro, which leaves the macro |
The invalid argument is moved out of the macro, which leaves the macro |
empty, causing it to toggle the spacing mode. |
empty, causing it to toggle the spacing mode. |
|
.It Sy "argument contains two font escapes" |
|
.Pq roff |
|
The second argument of a |
|
.Ic char |
|
request contains more than one font escape sequence. |
|
A wrong font may remain active after using the character. |
.It Sy "unknown font, skipping request" |
.It Sy "unknown font, skipping request" |
.Pq man , tbl |
.Pq man , tbl |
A |
A |
|
|
macro. |
macro. |
It may be mistyped or unsupported. |
It may be mistyped or unsupported. |
The request or macro is discarded including its arguments. |
The request or macro is discarded including its arguments. |
|
.It Sy "skipping request outside macro" |
|
.Pq roff |
|
A |
|
.Ic shift |
|
or |
|
.Ic return |
|
request occurs outside any macro definition and has no effect. |
.It Sy "skipping insecure request" |
.It Sy "skipping insecure request" |
.Pq roff |
.Pq roff |
An input file attempted to run a shell command |
An input file attempted to run a shell command |
Line 1910 When parsing for a request or a user-defined macro nam |
|
Line 1933 When parsing for a request or a user-defined macro nam |
|
only the escape sequence is discarded. |
only the escape sequence is discarded. |
The characters preceding it are used as the request or macro name, |
The characters preceding it are used as the request or macro name, |
the characters following it are used as the arguments to the request or macro. |
the characters following it are used as the arguments to the request or macro. |
|
.It Sy "using macro argument outside macro" |
|
.Pq roff |
|
The escape sequence \e$ occurs outside any macro definition |
|
and expands to the empty string. |
|
.It Sy "argument number is not numeric" |
|
.Pq roff |
|
The argument of the escape sequence \e$ is not a digit; |
|
the escape sequence expands to the empty string. |
.It Sy "NOT IMPLEMENTED: Bd -file" |
.It Sy "NOT IMPLEMENTED: Bd -file" |
.Pq mdoc |
.Pq mdoc |
For security reasons, the |
For security reasons, the |
Line 1938 macro fails to specify the list type. |
|
Line 1969 macro fails to specify the list type. |
|
The argument of a |
The argument of a |
.Ic \&ce |
.Ic \&ce |
request is not a number. |
request is not a number. |
|
.It Sy "argument is not a character" |
|
.Pq roff |
|
The first argument of a |
|
.Ic char |
|
request is neither a single ASCII character |
|
nor a single character escape sequence. |
|
The request is ignored including all its arguments. |
.It Sy "missing manual name, using \(dq\(dq" |
.It Sy "missing manual name, using \(dq\(dq" |
.Pq mdoc |
.Pq mdoc |
The first call to |
The first call to |
|
|
.Ic \&gsize |
.Ic \&gsize |
statement has a non-numeric or negative argument or no argument at all. |
statement has a non-numeric or negative argument or no argument at all. |
The invalid request or statement is ignored. |
The invalid request or statement is ignored. |
|
.It Sy "excessive shift" |
|
.Pq roff |
|
The argument of a |
|
.Ic shift |
|
request is larger than the number of arguments of the macro that is |
|
currently being executed. |
|
All macro arguments are deleted and \en(.$ is set to zero. |
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" |
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" |
.Pq roff |
.Pq roff |
For security reasons, |
For security reasons, |