Return to mandoc.1 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.125, 2014/11/28 18:09:01 | version 1.188, 2017/05/17 23:39:31 | ||
---|---|---|---|
|
|
||
.\" $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 Ingo Schwarze <schwarze@openbsd.org> | .\" Copyright (c) 2012, 2014-2017 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 | ||
|
|
||
.Os | .Os | ||
.Sh NAME | .Sh NAME | ||
.Nm mandoc | .Nm mandoc | ||
.Nd format and display UNIX manuals | .Nd format manual pages | ||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||
.Nm mandoc | .Nm mandoc | ||
.Op Fl acfhklV | .Op Fl ac | ||
.Sm off | .Op Fl I Cm os Ns = Ns Ar name | ||
.Op Fl I Cm os Li = Ar name | .Op Fl K Ar encoding | ||
.Sm on | .Op Fl mdoc | man | ||
.Op Fl K Ns Ar encoding | .Op Fl O Ar options | ||
.Op Fl m Ns Ar format | .Op Fl T Ar output | ||
.Op Fl O Ns Ar option | .Op Fl W Ar level | ||
.Op Fl T Ns Ar output | |||
.Op Fl W Ns Ar level | |||
.Op Ar | .Op Ar | ||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||
The | The | ||
|
|
||
.Xr mdoc 7 | .Xr mdoc 7 | ||
or | or | ||
.Xr man 7 | .Xr man 7 | ||
text from stdin, implying | text from stdin and produces | ||
.Fl m Ns Cm andoc , | .Fl T Cm locale | ||
and produces | |||
.Fl T Ns Cm ascii | |||
output. | output. | ||
.Pp | .Pp | ||
The options are as follows: | The options are as follows: | ||
|
|
||
This is the default. | This is the default. | ||
It can be specified to override | It can be specified to override | ||
.Fl a . | .Fl a . | ||
.It Fl f | .It Fl I Cm os Ns = Ns Ar name | ||
A synonym for | |||
.Xr whatis 1 . | |||
This overrides any earlier | |||
.Fl k | |||
and | |||
.Fl l | |||
options. | |||
.Sm off | |||
.It Fl I Cm os Li = Ar name | |||
.Sm on | |||
Override the default operating system | Override the default operating system | ||
.Ar name | .Ar name | ||
for the | for the | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
.Sq \&Os | .Ic \&Os | ||
and for the | |||
.Xr man 7 | |||
.Ic \&TH | |||
macro. | macro. | ||
.It Fl h | .It Fl K Ar encoding | ||
Display only the SYNOPSIS lines. | |||
Implies | |||
.Fl c . | |||
.It Fl K Ns Ar encoding | |||
Specify the input encoding. | Specify the input encoding. | ||
The supported | The supported | ||
.Ar encoding | .Ar encoding | ||
|
|
||
.Cm iso-8859-1 , | .Cm iso-8859-1 , | ||
and | and | ||
.Cm utf-8 . | .Cm utf-8 . | ||
If not specified, autodetection uses the first match: | If not specified, autodetection uses the first match in the following | ||
.Bl -tag -width iso-8859-1 | list: | ||
.It Cm utf-8 | .Bl -enum | ||
if the first three bytes of the input file | .It | ||
are the UTF-8 byte order mark (BOM, 0xefbbbf) | If the first three bytes of the input file are the UTF-8 byte order | ||
.It Ar encoding | mark (BOM, 0xefbbbf), input is interpreted as | ||
if the first or second line of the input file matches the | .Cm utf-8 . | ||
.It | |||
If the first or second line of the input file matches the | |||
.Sy emacs | .Sy emacs | ||
mode line format | mode line format | ||
.Pp | .Pp | ||
.D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*- | .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*- | ||
.It Cm utf-8 | .Pp | ||
if the first non-ASCII byte in the file introduces a valid UTF-8 sequence | then input is interpreted according to | ||
.It Cm iso-8859-1 | .Ar encoding . | ||
otherwise | .It | ||
If the first non-ASCII byte in the file introduces a valid UTF-8 | |||
sequence, input is interpreted as | |||
.Cm utf-8 . | |||
.It | |||
Otherwise, input is interpreted as | |||
.Cm iso-8859-1 . | |||
.El | .El | ||
.It Fl k | .It Fl mdoc | man | ||
A synonym for | With | ||
.Xr apropos 1 . | .Fl mdoc , | ||
This overrides any earlier | all input files are interpreted as | ||
.Fl f | .Xr mdoc 7 . | ||
and | With | ||
.Fl l | .Fl man , | ||
options. | all input files are interpreted as | ||
.It Fl l | .Xr man 7 . | ||
A synonym for | By default, the input language is automatically detected for each file: | ||
.Fl a . | if the the first macro is | ||
Also reverts any earlier | .Ic \&Dd | ||
.Fl f | or | ||
and | .Ic \&Dt , | ||
.Fl k | the | ||
options. | .Xr mdoc 7 | ||
.It Fl m Ns Ar format | parser is used; otherwise, the | ||
Input format. | .Xr man 7 | ||
See | parser is used. | ||
.Sx Input Formats | With other arguments, | ||
for available formats. | .Fl m | ||
Defaults to | is silently ignored. | ||
.Fl m Ns Cm andoc . | .It Fl O Ar options | ||
.It Fl O Ns Ar option | |||
Comma-separated output options. | Comma-separated output options. | ||
.It Fl T Ns Ar output | .It Fl T Ar output | ||
Output format. | Output format. | ||
See | See | ||
.Sx Output Formats | .Sx Output Formats | ||
for available formats. | for available formats. | ||
Defaults to | Defaults to | ||
.Fl T Ns Cm ascii . | .Fl T Cm locale . | ||
.It Fl V | .It Fl W Ar level | ||
Print version and exit. | |||
.It Fl W Ns Ar level | |||
Specify the minimum message | Specify the minimum message | ||
.Ar level | .Ar level | ||
to be reported on the standard error output and to affect the exit status. | to be reported on the standard error output and to affect the exit status. | ||
The | The | ||
.Ar level | .Ar level | ||
can be | can be | ||
.Cm style , | |||
.Cm warning , | .Cm warning , | ||
.Cm error , | .Cm error , | ||
or | or | ||
.Cm fatal . | .Cm unsupp ; | ||
The default is | .Cm all | ||
.Fl W Ns Cm fatal ; | |||
.Fl W Ns Cm all | |||
is an alias for | is an alias for | ||
.Fl W Ns Cm warning . | .Cm style . | ||
By default, | |||
.Nm | |||
is silent. | |||
See | See | ||
.Sx EXIT STATUS | .Sx EXIT STATUS | ||
and | and | ||
|
|
||
for details. | for details. | ||
.Pp | .Pp | ||
The special option | The special option | ||
.Fl W Ns Cm stop | .Fl W Cm stop | ||
tells | tells | ||
.Nm | .Nm | ||
to exit after parsing a file that causes warnings or errors of at least | to exit after parsing a file that causes warnings or errors of at least | ||
|
|
||
and | and | ||
.Cm stop | .Cm stop | ||
are requested, they can be joined with a comma, for example | are requested, they can be joined with a comma, for example | ||
.Fl W Ns 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 input from zero or more files. | ||
If unspecified, reads from stdin. | If unspecified, reads from stdin. | ||
|
|
||
will halt with the first failed parse. | will halt with the first failed parse. | ||
.El | .El | ||
.Pp | .Pp | ||
The options | |||
.Fl fhklw | |||
are also supported and are documented in man(1). | |||
In | In | ||
.Fl f | .Fl f | ||
and | and | ||
|
|
||
mode, | mode, | ||
.Nm | .Nm | ||
also supports the options | also supports the options | ||
.Fl CMmOSsw | .Fl CMmOSs | ||
described in the | described in the | ||
.Xr apropos 1 | .Xr apropos 1 | ||
manual. | manual. | ||
.Ss Input Formats | The options | ||
The | .Fl fkl | ||
.Nm | are mutually exclusive and override each other. | ||
utility accepts | |||
.Xr mdoc 7 | |||
and | |||
.Xr man 7 | |||
input with | |||
.Fl m Ns Cm doc | |||
and | |||
.Fl m Ns Cm an , | |||
respectively. | |||
The | |||
.Xr mdoc 7 | |||
format is | |||
.Em strongly | |||
recommended; | |||
.Xr man 7 | |||
should only be used for legacy manuals. | |||
.Pp | |||
A third option, | |||
.Fl m Ns Cm andoc , | |||
which is also the default, determines encoding on-the-fly: if the first | |||
non-comment macro is | |||
.Sq \&Dd | |||
or | |||
.Sq \&Dt , | |||
the | |||
.Xr mdoc 7 | |||
parser is used; otherwise, the | |||
.Xr man 7 | |||
parser is used. | |||
.Pp | |||
If multiple | |||
files are specified with | |||
.Fl m Ns Cm andoc , | |||
each has its file-type determined this way. | |||
If multiple files are | |||
specified and | |||
.Fl m Ns Cm doc | |||
or | |||
.Fl m Ns Cm an | |||
is specified, then this format is used exclusively. | |||
.Ss Output Formats | .Ss Output Formats | ||
The | The | ||
.Nm | .Nm | ||
utility accepts the following | utility accepts the following | ||
.Fl T | .Fl T | ||
arguments, which correspond to output modes: | arguments, which correspond to output modes: | ||
.Bl -tag -width "-Tlocale" | .Bl -tag -width "-T markdown" | ||
.It Fl T Ns Cm ascii | .It Fl T Cm ascii | ||
Produce 7-bit ASCII output. | Produce 7-bit ASCII output. | ||
This is the default. | |||
See | See | ||
.Sx ASCII Output . | .Sx ASCII Output . | ||
.It Fl T Ns Cm html | .It Fl T Cm html | ||
Produce HTML5, CSS1, and MathML output. | Produce HTML5, CSS1, and MathML output. | ||
See | See | ||
.Sx HTML Output . | .Sx HTML Output . | ||
.It Fl T Ns Cm lint | .It Fl T Cm lint | ||
Parse only: produce no output. | Parse only: produce no output. | ||
Implies | Implies | ||
.Fl W Ns Cm warning . | .Fl W Cm warning . | ||
.It Fl T Ns Cm locale | .It Fl T Cm locale | ||
Encode output using the current locale. | Encode output using the current locale. | ||
This is the default. | |||
See | See | ||
.Sx Locale Output . | .Sx Locale Output . | ||
.It Fl T Ns Cm man | .It Fl T Cm man | ||
Produce | Produce | ||
.Xr man 7 | .Xr man 7 | ||
format output. | format output. | ||
See | See | ||
.Sx Man Output . | .Sx Man Output . | ||
.It Fl T Ns Cm pdf | .It Fl T Cm markdown | ||
Produce output in | |||
.Sy markdown | |||
format. | |||
See | |||
.Sx Markdown Output . | |||
.It Fl T Cm pdf | |||
Produce PDF output. | Produce PDF output. | ||
See | See | ||
.Sx PDF Output . | .Sx PDF Output . | ||
.It Fl T Ns Cm ps | .It Fl T Cm ps | ||
Produce PostScript output. | Produce PostScript output. | ||
See | See | ||
.Sx PostScript Output . | .Sx PostScript Output . | ||
.It Fl T Ns Cm tree | .It Fl T Cm tree | ||
Produce an indented parse tree. | Produce an indented parse tree. | ||
.It Fl T Ns Cm utf8 | See | ||
.Sx Syntax tree output . | |||
.It Fl T Cm utf8 | |||
Encode output in the UTF\-8 multi-byte format. | Encode output in the UTF\-8 multi-byte format. | ||
See | See | ||
.Sx UTF\-8 Output . | .Sx UTF\-8 Output . | ||
.It Fl T Ns Cm xhtml | |||
This is a synonym for | |||
.Fl T Ns Cm html . | |||
.El | .El | ||
.Pp | .Pp | ||
If multiple input files are specified, these will be processed by the | If multiple input files are specified, these will be processed by the | ||
corresponding filter in-order. | corresponding filter in-order. | ||
.Ss ASCII Output | .Ss ASCII Output | ||
Output produced by | Output produced by | ||
.Fl T Ns Cm ascii , | .Fl T Cm ascii | ||
which is the default, is rendered in standard 7-bit ASCII documented in | is rendered in standard 7-bit ASCII documented in | ||
.Xr ascii 7 . | .Xr ascii 7 . | ||
.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 | ||
|
|
||
The special characters documented in | 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. | ||
If no equivalent is found, | |||
.Sq \&? | |||
is used instead. | |||
.Pp | .Pp | ||
Output width is limited to 78 visible columns unless literal input lines | Output width is limited to 78 visible columns unless literal input lines | ||
exceed this limit. | exceed this limit. | ||
|
|
||
.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 , | ||
which will normalise to \(>=60. | which will normalise to \(>=58. | ||
.El | .El | ||
.Ss HTML Output | .Ss HTML Output | ||
Output produced by | Output produced by | ||
.Fl T Ns Cm html | .Fl T Cm html | ||
conforms to HTML5 using optional self-closing tags. | conforms to HTML5 using optional self-closing tags. | ||
Default styles use only CSS1. | Default styles use only CSS1. | ||
Equations rendered from | Equations rendered from | ||
|
|
||
blocks use MathML. | blocks use MathML. | ||
.Pp | .Pp | ||
The | The | ||
.Pa example.style.css | .Pa mandoc.css | ||
file documents style-sheet classes available for customising output. | file documents style-sheet classes available for customising output. | ||
If a style-sheet is not specified with | If a style-sheet is not specified with | ||
.Fl O Ns Ar style , | .Fl O Cm style , | ||
.Fl T Ns Cm html | .Fl T Cm html | ||
defaults to simple output (via an embedded style-sheet) | 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. | ||
|
|
||
for example, | for example, | ||
.Ar ../src/%I.html , | .Ar ../src/%I.html , | ||
is used as a template for linked header files (usually via the | is used as a template for linked header files (usually via the | ||
.Sq \&In | .Ic \&In | ||
macro). | macro). | ||
Instances of | Instances of | ||
.Sq \&%I | .Sq \&%I | ||
|
|
||
for example, | for example, | ||
.Ar ../html%S/%N.%S.html , | .Ar ../html%S/%N.%S.html , | ||
is used as a template for linked manuals (usually via the | is used as a template for linked manuals (usually via the | ||
.Sq \&Xr | .Ic \&Xr | ||
macro). | macro). | ||
Instances of | Instances of | ||
.Sq \&%N | .Sq \&%N | ||
|
|
||
.El | .El | ||
.Ss Locale Output | .Ss Locale Output | ||
Locale-depending output encoding is triggered with | Locale-depending output encoding is triggered with | ||
.Fl T Ns Cm locale . | .Fl T Cm locale . | ||
This is the default. | |||
.Pp | |||
This option is not available on all systems: systems without locale | This option is not available on all systems: systems without locale | ||
support, or those whose internal representation is not natively UCS-4, | support, or those whose internal representation is not natively UCS-4, | ||
will fall back to | will fall back to | ||
.Fl T Ns Cm ascii . | .Fl T Cm ascii . | ||
See | See | ||
.Sx ASCII Output | .Sx ASCII Output | ||
for font style specification and available command-line arguments. | for font style specification and available command-line arguments. | ||
|
|
||
.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 | ||
.Sq so | .Ic so | ||
requests. | requests. | ||
The parser is also run, and as usual, the | The parser is also run, and as usual, the | ||
.Fl W | .Fl W | ||
level controls which | 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 | |||
Translate | |||
.Xr mdoc 7 | |||
input to the | |||
.Sy markdown | |||
format conforming to | |||
.Lk http://daringfireball.net/projects/markdown/syntax.text\ | |||
"John Gruber's 2004 specification" . | |||
The output also almost conforms to the | |||
.Lk http://commonmark.org/ CommonMark | |||
specification. | |||
.Pp | |||
The character set used for the markdown output is ASCII. | |||
Non-ASCII characters are encoded as HTML entities. | |||
Since that is not possible in literal font contexts, because these | |||
are rendered as code spans and code blocks in the markdown output, | |||
non-ASCII characters are transliterated to ASCII approximations in | |||
these contexts. | |||
.Pp | |||
Markdown is a very weak markup language, so all semantic markup is | |||
lost, and even part of the presentational markup may be lost. | |||
Do not use this as an intermediate step in converting to HTML; | |||
instead, use | |||
.Fl T Cm html | |||
directly. | |||
.Pp | |||
The | |||
.Xr man 7 , | |||
.Xr tbl 7 , | |||
and | |||
.Xr eqn 7 | |||
input languages are not supported by | |||
.Fl T Cm markdown | |||
output mode. | |||
.Ss PDF Output | .Ss PDF Output | ||
PDF-1.1 output may be generated by | PDF-1.1 output may be generated by | ||
.Fl T Ns Cm pdf . | .Fl T Cm pdf . | ||
See | See | ||
.Sx PostScript Output | .Sx PostScript Output | ||
for | for | ||
|
|
||
PostScript | PostScript | ||
.Qq Adobe-3.0 | .Qq Adobe-3.0 | ||
Level-2 pages may be generated by | Level-2 pages may be generated by | ||
.Fl T Ns Cm ps . | .Fl T Cm ps . | ||
Output pages default to letter sized and are rendered in the Times font | Output pages default to letter sized and are rendered in the Times font | ||
family, 11-point. | family, 11-point. | ||
Margins are calculated as 1/9 the page length and width. | Margins are calculated as 1/9 the page length and width. | ||
|
|
||
.El | .El | ||
.Ss UTF\-8 Output | .Ss UTF\-8 Output | ||
Use | Use | ||
.Fl T Ns Cm utf8 | .Fl T Cm utf8 | ||
to force a UTF\-8 locale. | to force a UTF\-8 locale. | ||
See | See | ||
.Sx Locale Output | .Sx Locale Output | ||
for details and options. | for details and options. | ||
.Ss Syntax tree output | |||
Use | |||
.Fl T Cm 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. | |||
.Pp | |||
The first paragraph shows meta data found in the | |||
.Xr mdoc 7 | |||
prologue, on the | |||
.Xr man 7 | |||
.Ic \&TH | |||
line, or the fallbacks used. | |||
.Pp | |||
In the tree dump, each output line shows one syntax tree node. | |||
Child nodes are indented with respect to their parent node. | |||
The columns are: | |||
.Pp | |||
.Bl -enum -compact | |||
.It | |||
For macro nodes, the macro name; for text and | |||
.Xr tbl 7 | |||
nodes, the content. | |||
There is a special format for | |||
.Xr eqn 7 | |||
nodes. | |||
.It | |||
Node type (text, elem, block, head, body, body-end, tail, tbl, eqn). | |||
.It | |||
Flags: | |||
.Bl -dash -compact | |||
.It | |||
An opening parenthesis if the node is an opening delimiter. | |||
.It | |||
An asterisk if the node starts a new input line. | |||
.It | |||
The input line number (starting at one). | |||
.It | |||
A colon. | |||
.It | |||
The input column number (starting at one). | |||
.It | |||
A closing parenthesis if the node is a closing delimiter. | |||
.It | |||
A full stop if the node ends a sentence. | |||
.It | |||
BROKEN if the node is a block broken by another block. | |||
.It | |||
NOSRC if the node is not in the input file, | |||
but automatically generated from macros. | |||
.It | |||
NOPRT if the node is not supposed to generate output | |||
for any output format. | |||
.El | |||
.El | |||
.Pp | |||
The following | |||
.Fl O | |||
argument is accepted: | |||
.Bl -tag -width Ds | |||
.It Cm 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. | |||
.El | |||
.Sh ENVIRONMENT | .Sh ENVIRONMENT | ||
.Bl -tag -width MANPAGER | .Bl -tag -width MANPAGER | ||
.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 | ||
will be used instead of the standard pagination program, | is used instead of the standard pagination program, | ||
.Xr more 1 . | .Xr more 1 ; | ||
see | |||
.Xr man 1 | |||
for details. | |||
Only used if | |||
.Fl a | |||
or | |||
.Fl l | |||
is specified. | |||
.It Ev PAGER | .It Ev PAGER | ||
Specifies the pagination program to use when | Specifies the pagination program to use when | ||
.Ev MANPAGER | .Ev MANPAGER | ||
is not defined. | is not defined. | ||
If neither PAGER nor MANPAGER is defined, | If neither PAGER nor MANPAGER is defined, | ||
.Pa /usr/bin/more Fl s | .Xr more 1 | ||
will be used. | .Fl s | ||
is used. | |||
Only used if | |||
.Fl a | |||
or | |||
.Fl l | |||
is specified. | |||
.El | .El | ||
.Sh EXIT STATUS | .Sh EXIT STATUS | ||
The | The | ||
|
|
||
.Pp | .Pp | ||
.Bl -tag -width Ds -compact | .Bl -tag -width Ds -compact | ||
.It 0 | .It 0 | ||
No warnings or errors occurred, or those that did were ignored because | No style suggestions, warnings or errors occurred, or those that | ||
they were lower than the requested | did were ignored because they were lower than the requested | ||
.Ar level . | .Ar level . | ||
.It 1 | |||
At least one style suggestion occurred, but no warning or error, and | |||
.Fl W Cm style | |||
was specified. | |||
.It 2 | .It 2 | ||
At least one warning occurred, but no error, and | At least one warning occurred, but no error, and | ||
.Fl W Ns Cm warning | .Fl W Cm warning | ||
was specified. | |||
.It 3 | |||
At least one parsing error occurred, but no fatal error, and | |||
.Fl W Ns Cm error | |||
or | or | ||
.Fl W Ns Cm warning | .Fl W Cm style | ||
was specified. | was specified. | ||
.It 3 | |||
At least one parsing error occurred, | |||
but no unsupported feature was encountered, and | |||
.Fl W Cm error | |||
or a lower | |||
.Ar level | |||
was requested. | |||
.It 4 | .It 4 | ||
A fatal parsing error occurred. | At least one unsupported feature was encountered, and | ||
.Fl W Cm unsupp | |||
or a lower | |||
.Ar level | |||
was requested. | |||
.It 5 | .It 5 | ||
Invalid command line arguments were specified. | Invalid command line arguments were specified. | ||
No input files have been read. | No input files have been read. | ||
.It 6 | .It 6 | ||
An operating system error occurred, for example memory exhaustion or an | An operating system error occurred, for example exhaustion | ||
error accessing input files. | of memory, file descriptors, or process table entries. | ||
Such errors cause | Such errors cause | ||
.Nm | .Nm | ||
to exit at once, possibly in the middle of parsing or formatting a file. | to exit at once, possibly in the middle of parsing or formatting a file. | ||
.El | .El | ||
.Pp | .Pp | ||
Note that selecting | Note that selecting | ||
.Fl T Ns Cm lint | .Fl T Cm lint | ||
output mode implies | output mode implies | ||
.Fl W Ns Cm warning . | .Fl W Cm warning . | ||
.Sh EXAMPLES | .Sh EXAMPLES | ||
To page manuals to the terminal: | To page manuals to the terminal: | ||
.Pp | .Pp | ||
.Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less | .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 | ||
.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less | |||
.Pp | .Pp | ||
To produce HTML manuals with | To produce HTML manuals with | ||
.Ar style.css | .Pa mandoc.css | ||
as the style-sheet: | as the style-sheet: | ||
.Pp | .Pp | ||
.Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html | .Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html | ||
.Pp | .Pp | ||
To check over a large set of manuals: | To check over a large set of manuals: | ||
.Pp | .Pp | ||
.Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]` | .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga | ||
.Pp | .Pp | ||
To produce a series of PostScript manuals for A4 paper: | To produce a series of PostScript manuals for A4 paper: | ||
.Pp | .Pp | ||
.Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps | .Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps | ||
.Pp | .Pp | ||
Convert a modern | Convert a modern | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
|
|
||
.Xr mdoc 7 | .Xr mdoc 7 | ||
parser: | parser: | ||
.Pp | .Pp | ||
.Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man | .Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man | ||
.Sh DIAGNOSTICS | .Sh DIAGNOSTICS | ||
Messages displayed by | Messages displayed by | ||
.Nm | .Nm | ||
|
|
||
.Pp | .Pp | ||
Message levels have the following meanings: | Message levels have the following meanings: | ||
.Bl -tag -width "warning" | .Bl -tag -width "warning" | ||
.It Cm syserr | .It Cm unsupp | ||
Opening or reading an input file failed, so the parser cannot | An input file uses unsupported low-level | ||
even be started and no output is produced from that input file. | .Xr roff 7 | ||
.It Cm fatal | features. | ||
The parser is unable to parse a given input file at all. | The output may be incomplete and/or misformatted, | ||
No formatted output is produced from that input file. | so using GNU troff instead of | ||
.It Cm error | |||
An input file contains syntax that cannot be safely interpreted, | |||
either because it is invalid or because | |||
.Nm | .Nm | ||
does not implement it yet. | to process the file may be preferable. | ||
.It Cm error | |||
An input file contains invalid syntax that cannot be safely interpreted. | |||
By discarding part of the input or inserting missing tokens, | By discarding part of the input or inserting missing tokens, | ||
the parser is able to continue, and the error does not prevent | the parser is able to continue, and the error does not prevent | ||
generation of formatted output, but typically, preparing that | generation of formatted output, but typically, preparing that | ||
output involves information loss, broken document structure | output involves information loss, broken document structure | ||
or unintended formatting. | or unintended formatting, no matter whether | ||
.Nm | |||
or GNU troff is used. | |||
In many cases, the output of | |||
.Nm | |||
and GNU troff is identical, but in some, | |||
.Nm | |||
is more resilient than GNU troff with respect to malformed input. | |||
.Pp | |||
Non-existent or unreadable input files are also reported on the | |||
.Cm error | |||
level. | |||
In that case, the parser cannot even be started and no output | |||
is produced from those input files. | |||
.It Cm warning | .It Cm warning | ||
An input file uses obsolete, discouraged or non-portable syntax. | An input file uses obsolete, discouraged or non-portable syntax. | ||
All the same, the meaning of the input is unambiguous and a correct | All the same, the meaning of the input is unambiguous and a correct | ||
|
|
||
Documents causing warnings may render poorly when using other | Documents causing warnings may render poorly when using other | ||
formatting tools instead of | formatting tools instead of | ||
.Nm . | .Nm . | ||
.It Cm style | |||
An input file uses dubious or discouraged style. | |||
This is not a complaint about the syntax, and probably neither | |||
formatting nor portability are in danger. | |||
While great care is taken to avoid false positives on the higher | |||
message levels, the | |||
.Cm style | |||
level 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 | |||
.Cm style | |||
suggestion really justifies a change to the input file. | |||
.El | .El | ||
.Pp | .Pp | ||
Messages of the | Messages of the | ||
.Cm warning | .Cm style , | ||
.Cm warning , | |||
.Cm error , | |||
and | and | ||
.Cm error | .Cm unsupp | ||
levels are hidden unless their level, or a lower level, is requested using a | levels except those about non-existent or unreadable input files | ||
are hidden unless their level, or a lower level, is requested using a | |||
.Fl W | .Fl W | ||
option or | option or | ||
.Fl T Ns Cm lint | .Fl T Cm lint | ||
output mode. | output mode. | ||
.Ss Warnings related to the document prologue | .Ss Warnings related to the document prologue | ||
.Bl -ohang | .Bl -ohang | ||
|
|
||
.Pq mdoc | .Pq mdoc | ||
The | The | ||
.Ic \&Dt | .Ic \&Dt | ||
macro can only occur before the first non-prologue macro | macro appears after the first non-prologue macro. | ||
because traditional formatters write the page header | Traditional formatters cannot handle this because | ||
before parsing the document body. | they write the page header before parsing the document body. | ||
Even though this technical restriction does not apply to | Even though this technical restriction does not apply to | ||
.Nm , | .Nm , | ||
traditional semantics is preserved. | traditional semantics is preserved. | ||
|
|
||
.Xr makewhatis 8 | .Xr makewhatis 8 | ||
and | and | ||
.Xr apropos 1 . | .Xr apropos 1 . | ||
.It Sy "bad NAME section contents" | .It Sy "NAME section without Nm before Nd" | ||
.Pq mdoc | .Pq mdoc | ||
The last node in the NAME section is not an | The NAME section does not contain any | ||
.Ic \&Nm | |||
child macro before the first | |||
.Ic \&Nd | .Ic \&Nd | ||
macro, or any preceding macro is not | macro. | ||
.Ic \&Nm , | .It Sy "NAME section without description" | ||
or the NAME section is completely empty. | .Pq mdoc | ||
This may confuse | The NAME section lacks the mandatory | ||
.Xr makewhatis 8 | .Ic \&Nd | ||
child macro. | |||
.It Sy "description not at the end of NAME" | |||
.Pq mdoc | |||
The NAME section does contain an | |||
.Ic \&Nd | |||
child macro, but other content follows it. | |||
.It Sy "bad NAME section content" | |||
.Pq mdoc | |||
The NAME section contains plain text or macros other than | |||
.Ic \&Nm | |||
and | and | ||
.Xr apropos 1 . | .Ic \&Nd . | ||
.It Sy "missing comma before name" | |||
.Pq mdoc | |||
The NAME section contains an | |||
.Ic \&Nm | |||
macro that is neither the first one nor preceded by a comma. | |||
.It Sy "missing description line, using \(dq\(dq" | |||
.Pq mdoc | |||
The | |||
.Ic \&Nd | |||
macro lacks the required argument. | |||
The title line of the manual will end after the dash. | |||
.It Sy "description line outside NAME section" | |||
.Pq mdoc | |||
An | |||
.Ic \&Nd | |||
macro appears outside the NAME section. | |||
The arguments are printed anyway and the following text is used for | |||
.Xr apropos 1 , | |||
but none of that behaviour is portable. | |||
.It Sy "sections out of conventional order" | .It Sy "sections out of conventional order" | ||
.Pq mdoc | .Pq mdoc | ||
A standard section occurs after another section it usually precedes. | A standard section occurs after another section it usually precedes. | ||
|
|
||
macro with a lower section number follows one with a higher number, | macro with a lower section number follows one with a higher number, | ||
or two | or two | ||
.Ic \&Xr | .Ic \&Xr | ||
macros refering to the same section are out of alphabetical order. | macros referring to the same section are out of alphabetical order. | ||
.It Sy "unusual Xr punctuation" | .It Sy "unusual Xr punctuation" | ||
.Pq mdoc | .Pq mdoc | ||
In the SEE ALSO section, punctuation between two | In the SEE ALSO section, punctuation between two | ||
|
|
||
See the | See the | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
manual for replacements. | manual for replacements. | ||
.It Sy "macro neither callable nor escaped" | |||
.Pq mdoc | |||
The name of a macro that is not callable appears on a macro line. | |||
It is printed verbatim. | |||
If the intention is to call it, move it to its own input line; | |||
otherwise, escape it by prepending | |||
.Sq \e& . | |||
.It Sy "skipping paragraph macro" | .It Sy "skipping paragraph macro" | ||
In | In | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
|
|
||
.Ic \&It | .Ic \&It | ||
macro. | macro. | ||
The offending children are moved before the beginning of the list. | The offending children are moved before the beginning of the list. | ||
.It Sy ".Vt block has child macro" | |||
.Pq mdoc | |||
The | |||
.Ic \&Vt | |||
macro supports plain text arguments only. | |||
Formatting may be ugly and semantic searching | |||
for the affected content might not work. | |||
.It Sy "fill mode already enabled, skipping" | .It Sy "fill mode already enabled, skipping" | ||
.Pq man | .Pq man | ||
A | A | ||
|
|
||
.It Sy "skipping empty macro" | .It Sy "skipping empty macro" | ||
.Pq mdoc | .Pq mdoc | ||
The indicated macro has no arguments and hence no effect. | The indicated macro has no arguments and hence no effect. | ||
.It Sy "empty block" | |||
.Pq mdoc , man | |||
A | |||
.Ic \&Bd , | |||
.Ic \&Bk , | |||
.Ic \&Bl , | |||
.Ic \&D1 , | |||
.Ic \&Dl , | |||
.Ic \&RS , | |||
or | |||
.Ic \&UR | |||
block contains nothing in its body and will produce no output. | |||
.It Sy "empty argument, using 0n" | .It Sy "empty argument, using 0n" | ||
.Pq mdoc | .Pq mdoc | ||
The required width is missing after | The required width is missing after | ||
|
|
||
.Ic \&Bl | .Ic \&Bl | ||
.Fl offset | .Fl offset | ||
or | or | ||
.Fl width. | .Fl width . | ||
.It Sy "argument count wrong" | |||
.Pq mdoc , man | |||
The indicated macro has too few or too many arguments. | |||
The syntax tree will contain the wrong number of arguments as given. | |||
Formatting behaviour depends on the specific macro in question. | |||
Note that the same message may also occur as an ERROR, see below. | |||
.It Sy "missing display type, using -ragged" | .It Sy "missing display type, using -ragged" | ||
.Pq mdoc | .Pq mdoc | ||
The | The | ||
|
|
||
macro is called without an argument before | macro is called without an argument before | ||
.Ic \&Nm | .Ic \&Nm | ||
has first been called with an argument. | has first been called with an argument. | ||
.It Sy "missing function name, using \(dq\(dq" | |||
.Pq mdoc | |||
The | |||
.Ic \&Fo | |||
macro is called without an argument. | |||
No function name is printed. | |||
.It Sy "empty head in list item" | .It Sy "empty head in list item" | ||
.Pq mdoc | .Pq mdoc | ||
In a | In a | ||
|
|
||
.Ic \&It | .Ic \&It | ||
block is empty. | block is empty. | ||
An empty list item is shown. | An empty list item is shown. | ||
.It Sy "missing font type" | .It Sy "missing font type, using \efR" | ||
.Pq mdoc | .Pq mdoc | ||
A | A | ||
.Ic \&Bf | .Ic \&Bf | ||
macro has no argument. | macro has no argument. | ||
It switches to the default font, | It switches to the default font. | ||
.Cm \efR . | .It Sy "unknown font type, using \efR" | ||
.It Sy "unknown font type" | |||
.Pq mdoc | .Pq mdoc | ||
The | The | ||
.Ic \&Bf | .Ic \&Bf | ||
argument is invalid. | argument is invalid. | ||
The default font | The default font is used instead. | ||
.Cm \efR | .It Sy "nothing follows prefix" | ||
is used instead. | .Pq mdoc | ||
A | |||
.Ic \&Pf | |||
macro has no argument, or only one argument and no macro follows | |||
on the same input line. | |||
This defeats its purpose; in particular, spacing is not suppressed | |||
before the text or macros following on the next input line. | |||
.It Sy "empty reference block" | |||
.Pq mdoc | |||
An | |||
.Ic \&Rs | |||
macro is immediately followed by an | |||
.Ic \&Re | |||
macro on the next input line. | |||
Such an empty block does not produce any output. | |||
.It Sy "missing section argument" | |||
.Pq mdoc | |||
An | |||
.Ic \&Xr | |||
macro lacks its second, section number argument. | |||
The first argument, i.e. the name, is printed, but without subsequent | |||
parentheses. | |||
.It Sy "missing -std argument, adding it" | .It Sy "missing -std argument, adding it" | ||
.Pq mdoc | .Pq mdoc | ||
An | An | ||
|
|
||
utility assumes | utility assumes | ||
.Fl std | .Fl std | ||
even when it is not specified, but other implementations may not. | even when it is not specified, but other implementations may not. | ||
.It Sy "missing option string, using \(dq\(dq" | |||
.Pq man | |||
The | |||
.Ic \&OP | |||
macro is invoked without any argument. | |||
An empty pair of square brackets is shown. | |||
.It Sy "missing resource identifier, using \(dq\(dq" | |||
.Pq man | |||
The | |||
.Ic \&UR | |||
macro is invoked without any argument. | |||
An empty pair of angle brackets is shown. | |||
.It Sy "missing eqn box, using \(dq\(dq" | .It Sy "missing eqn box, using \(dq\(dq" | ||
.Pq eqn | .Pq eqn | ||
A diacritic mark or a binary operator is found, | A diacritic mark or a binary operator is found, | ||
|
|
||
.Fl width | .Fl width | ||
argument. | argument. | ||
That has no effect. | That has no effect. | ||
.It Sy "wrong number of cells" | |||
In a line of a | |||
.Ic \&Bl Fl column | |||
list, the number of tabs or | |||
.Ic \&Ta | |||
macros is less than the number expected from the list header line | |||
or exceeds the expected number by more than one. | |||
Missing cells remain empty, and all cells exceeding the number of | |||
columns are joined into one single cell. | |||
.It Sy "unknown AT&T UNIX version" | .It Sy "unknown AT&T UNIX version" | ||
.Pq mdoc | .Pq mdoc | ||
An | An | ||
|
|
||
layout modifier has an unknown | layout modifier has an unknown | ||
.Ar font | .Ar font | ||
argument. | argument. | ||
.It Sy "odd number of characters in request" | |||
.Pq roff | |||
A | |||
.Ic \&tr | |||
request contains an odd number of characters. | |||
The last character is mapped to the blank character. | |||
.El | .El | ||
.Ss "Warnings related to plain text" | .Ss "Warnings related to plain text" | ||
.Bl -ohang | .Bl -ohang | ||
|
|
||
Whitespace at the end of input lines is almost never semantically | Whitespace at the end of input lines is almost never semantically | ||
significant \(em but in the odd case where it might be, it is | significant \(em but in the odd case where it might be, it is | ||
extremely confusing when reviewing and maintaining documents. | extremely confusing when reviewing and maintaining documents. | ||
.It Sy "new sentence, new line" | |||
.Pq mdoc | |||
A new sentence starts in the middle of a text line. | |||
Start it on a new input line to help formatters produce correct spacing. | |||
.It Sy "bad comment style" | .It Sy "bad comment style" | ||
.Pq roff | .Pq roff | ||
Comment lines start with a dot, a backslash, and a double-quote character. | Comment lines start with a dot, a backslash, and a double-quote character. | ||
|
|
||
However, defining strings explicitly before use | However, defining strings explicitly before use | ||
keeps the code more readable. | keeps the code more readable. | ||
.El | .El | ||
.Ss "Errors related to equations" | .Ss "Warnings related to tables" | ||
.Bl -inset -compact | .Bl -ohang | ||
.It "unexpected equation scope closure" | .It Sy "tbl line starts with span" | ||
.It "equation scope open on exit" | .Pq tbl | ||
.It "overlapping equation scopes" | The first cell in a table layout line is a horizontal span | ||
.It "unexpected end of equation" | .Pq Sq Cm s . | ||
Data provided for this cell is ignored, and nothing is printed in the cell. | |||
.It Sy "tbl column starts with span" | |||
.Pq tbl | |||
The first line of a table layout specification | |||
requests a vertical span | |||
.Pq Sq Cm ^ . | |||
Data provided for this cell is ignored, and nothing is printed in the cell. | |||
.It Sy "skipping vertical bar in tbl layout" | |||
.Pq tbl | |||
A table layout specification contains more than two consecutive vertical bars. | |||
A double bar is printed, all additional bars are discarded. | |||
.El | .El | ||
.Ss "Errors related to tables" | .Ss "Errors related to tables" | ||
.Bl -inset -compact | .Bl -ohang | ||
.It "bad table syntax" | .It Sy "non-alphabetic character in tbl options" | ||
.It "bad table option" | .Pq tbl | ||
.It "bad table layout" | The table options line contains a character other than a letter, | ||
.It "no table layout cells specified" | blank, or comma where the beginning of an option name is expected. | ||
.It "no table data cells specified" | The character is ignored. | ||
.It "ignore data in cell" | .It Sy "skipping unknown tbl option" | ||
.It "data block still open" | .Pq tbl | ||
.It "ignoring extra data cells" | The table options line contains a string of letters that does not | ||
match any known option name. | |||
The word is ignored. | |||
.It Sy "missing tbl option argument" | |||
.Pq tbl | |||
A table option that requires an argument is not followed by an | |||
opening parenthesis, or the opening parenthesis is immediately | |||
followed by a closing parenthesis. | |||
The option is ignored. | |||
.It Sy "wrong tbl option argument size" | |||
.Pq tbl | |||
A table option argument contains an invalid number of characters. | |||
Both the option and the argument are ignored. | |||
.It Sy "empty tbl layout" | |||
.Pq tbl | |||
A table layout specification is completely empty, | |||
specifying zero lines and zero columns. | |||
As a fallback, a single left-justified column is used. | |||
.It Sy "invalid character in tbl layout" | |||
.Pq tbl | |||
A table layout specification contains a character that can neither | |||
be interpreted as a layout key character nor as a layout modifier, | |||
or a modifier precedes the first key. | |||
The invalid character is discarded. | |||
.It Sy "unmatched parenthesis in tbl layout" | |||
.Pq tbl | |||
A table layout specification contains an opening parenthesis, | |||
but no matching closing parenthesis. | |||
The rest of the input line, starting from the parenthesis, has no effect. | |||
.It Sy "tbl without any data cells" | |||
.Pq tbl | |||
A table does not contain any data cells. | |||
It will probably produce no output. | |||
.It Sy "ignoring data in spanned tbl cell" | |||
.Pq tbl | |||
A table cell is marked as a horizontal span | |||
.Pq Sq Cm s | |||
or vertical span | |||
.Pq Sq Cm ^ | |||
in the table layout, but it contains data. | |||
The data is ignored. | |||
.It Sy "ignoring extra tbl data cells" | |||
.Pq tbl | |||
A data line contains more cells than the corresponding layout line. | |||
The data in the extra cells is ignored. | |||
.It Sy "data block open at end of tbl" | |||
.Pq tbl | |||
A data block is opened with | |||
.Cm T{ , | |||
but never closed with a matching | |||
.Cm T} . | |||
The remaining data lines of the table are all put into one cell, | |||
and any remaining cells stay empty. | |||
.El | .El | ||
.Ss "Errors related to roff, mdoc, and man code" | .Ss "Errors related to roff, mdoc, and man code" | ||
.Bl -ohang | .Bl -ohang | ||
|
|
||
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 insecure request" | |||
.Pq roff | |||
An input file attempted to run a shell command | |||
or to read or write an external file. | |||
Such attempts are denied for security reasons. | |||
.It Sy "skipping item outside list" | .It Sy "skipping item outside list" | ||
.Pq mdoc , eqn | .Pq mdoc , eqn | ||
An | An | ||
|
|
||
.Xr roff 7 | .Xr roff 7 | ||
conditional request is encountered but no matching block is open. | conditional request is encountered but no matching block is open. | ||
The offending request or macro is discarded. | The offending request or macro is discarded. | ||
.It Sy "fewer RS blocks open, skipping" | |||
.Pq man | |||
The | |||
.Ic \&RE | |||
macro is invoked with an argument, but less than the specified number of | |||
.Ic \&RS | |||
blocks is open. | |||
The | |||
.Ic \&RE | |||
macro is discarded. | |||
.It Sy "inserting missing end of block" | .It Sy "inserting missing end of block" | ||
.Pq mdoc , tbl | .Pq mdoc , tbl | ||
Various | Various | ||
|
|
||
A block that doesn't support bad nesting | A block that doesn't support bad nesting | ||
ends before all of its children are properly closed. | ends before all of its children are properly closed. | ||
The open child nodes are closed implicitly. | The open child nodes are closed implicitly. | ||
.It Sy "scope open on exit" | .It Sy "appending missing end of block" | ||
.Pq mdoc , man , eqn , tbl , roff | .Pq mdoc , man , eqn , tbl , roff | ||
At the end of the document, an explicit | At the end of the document, an explicit | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
|
|
||
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 "argument count wrong" | |||
.Pq mdoc , man , roff | |||
The indicated request or macro has too few or too many arguments. | |||
The syntax tree will contain the wrong number of arguments as given. | |||
Formatting behaviour depends on the specific request or macro in question. | |||
Note that the same message may also occur as a WARNING, see above. | |||
.It Sy "NOT IMPLEMENTED: Bd -file" | .It Sy "NOT IMPLEMENTED: Bd -file" | ||
.Pq mdoc | .Pq mdoc | ||
For security reasons, the | For security reasons, the | ||
|
|
||
might otherwise trick a privileged user into inadvertently displaying | might otherwise trick a privileged user into inadvertently displaying | ||
the file on the screen, revealing the file content to bystanders. | the file on the screen, revealing the file content to bystanders. | ||
The argument is ignored including the file name following it. | The argument is ignored including the file name following it. | ||
.It Sy "skipping display without arguments" | |||
.Pq mdoc | |||
A | |||
.Ic \&Bd | |||
block macro does not have any arguments. | |||
The block is discarded, and the block content is displayed in | |||
whatever mode was active before the block. | |||
.It Sy "missing list type, using -item" | .It Sy "missing list type, using -item" | ||
.Pq mdoc | .Pq mdoc | ||
A | A | ||
|
|
||
.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 \&Nm | .Ic \&Nm , | ||
lacks the required argument. | or any call in the NAME section, lacks the required argument. | ||
.It Sy "uname(3) system call failed, using UNKNOWN" | .It Sy "uname(3) system call failed, using UNKNOWN" | ||
.Pq mdoc | .Pq mdoc | ||
The | The | ||
|
|
||
.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 "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" | |||
.Pq roff | |||
For security reasons, | |||
.Nm | |||
allows | |||
.Ic \&so | |||
file inclusion requests only with relative paths | |||
and only without ascending to any parent directory. | |||
By requesting the inclusion of a sensitive file, a malicious document | |||
might otherwise trick a privileged user into inadvertently displaying | |||
the file on the screen, revealing the file content to bystanders. | |||
.Nm | |||
only shows the path as it appears behind | |||
.Ic \&so . | |||
.It Sy ".so request failed" | |||
.Pq roff | |||
Servicing a | |||
.Ic \&so | |||
request requires reading an external file, but the file could not be | |||
opened. | |||
.Nm | |||
only shows the path as it appears behind | |||
.Ic \&so . | |||
.It Sy "skipping all arguments" | .It Sy "skipping all arguments" | ||
.Pq mdoc , man , eqn , roff | .Pq mdoc , man , eqn , roff | ||
An | An | ||
|
|
||
.Ic \&Ef , | .Ic \&Ef , | ||
.Ic \&Ek , | .Ic \&Ek , | ||
.Ic \&El , | .Ic \&El , | ||
.Ic \&Lp , | |||
.Ic \&Pp , | |||
.Ic \&Re , | .Ic \&Re , | ||
.Ic \&Rs , | |||
or | or | ||
.Ic \&Ud | .Ic \&Ud | ||
macro, an | macro, an | ||
|
|
||
.Ic \&EN | .Ic \&EN | ||
macro, or a | macro, or a | ||
.Xr roff 7 | .Xr roff 7 | ||
.Ic \&br , | |||
.Ic \&fi , | |||
or | |||
.Ic \&nf | |||
request or | |||
.Sq \&.. | .Sq \&.. | ||
block closing request is invoked with at least one argument. | block closing request is invoked with at least one argument. | ||
All arguments are ignored. | All arguments are ignored. | ||
.It Sy "skipping excess arguments" | .It Sy "skipping excess arguments" | ||
.Pq mdoc , roff | .Pq mdoc , man , roff | ||
The | A macro or request is invoked with too many arguments: | ||
.Ic \&Bf | .Bl -dash -offset 2n -width 2n -compact | ||
macro is invoked with more than one argument, or a request of the | .It | ||
.Ic \&Fo , | |||
.Ic \&PD , | |||
.Ic \&RS , | |||
.Ic \&UR , | |||
.Ic \&ft , | |||
or | |||
.Ic \&sp | |||
with more than one argument | |||
.It | |||
.Ic \&An | |||
with another argument after | |||
.Fl split | |||
or | |||
.Fl nosplit | |||
.It | |||
.Ic \&RE | |||
with more than one argument or with a non-integer argument | |||
.It | |||
.Ic \&OP | |||
or a request of the | |||
.Ic \&de | .Ic \&de | ||
family is invoked with more than two arguments. | family with more than two arguments | ||
.It | |||
.Ic \&Dt | |||
with more than three arguments | |||
.It | |||
.Ic \&TH | |||
with more than five arguments | |||
.It | |||
.Ic \&Bd , | |||
.Ic \&Bk , | |||
or | |||
.Ic \&Bl | |||
with invalid arguments | |||
.El | |||
The excess arguments are ignored. | The excess arguments are ignored. | ||
.El | .El | ||
.Ss FATAL errors | .Ss Unsupported features | ||
.Bl -ohang | .Bl -ohang | ||
.It Sy "input too large" | .It Sy "input too large" | ||
.Pq mdoc , man | .Pq mdoc , man | ||
|
|
||
of 2^31 bytes (2 Gigabytes). | of 2^31 bytes (2 Gigabytes). | ||
Since useful manuals are always small, this is not a problem in practice. | Since useful manuals are always small, this is not a problem in practice. | ||
Parsing is aborted as soon as the condition is detected. | Parsing is aborted as soon as the condition is detected. | ||
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" | .It Sy "unsupported control character" | ||
.Pq roff | .Pq roff | ||
For security reasons, | An ASCII control character supported by other | ||
.Xr roff 7 | |||
implementations but not by | |||
.Nm | .Nm | ||
allows | was found in an input file. | ||
.Ic \&so | It is replaced by a question mark. | ||
file inclusion requests only with relative paths | .It Sy "unsupported roff request" | ||
and only without ascending to any parent directory. | |||
By requesting the inclusion of a sensitive file, a malicious document | |||
might otherwise trick a privileged user into inadvertently displaying | |||
the file on the screen, revealing the file content to bystanders. | |||
The parser exits immediately. | |||
.It Sy ".so request failed" | |||
.Pq roff | .Pq roff | ||
Servicing a | An input file contains a | ||
.Ic \&so | .Xr roff 7 | ||
request requires reading an external file. | request supported by GNU troff or Heirloom troff but not by | ||
While trying to do so, an | .Nm , | ||
.Xr open 2 , | and it is likely that this will cause information loss | ||
.Xr stat 2 , | or considerable misformatting. | ||
or | .It Sy "eqn delim option in tbl" | ||
.Xr read 2 | .Pq eqn , tbl | ||
system call failed. | The options line of a table defines equation delimiters. | ||
The parser exits immediately. | Any equation source code contained in the table will be printed unformatted. | ||
Before showing this message, | .It Sy "unsupported table layout modifier" | ||
.Nm | .Pq tbl | ||
always shows another message explaining why the system call failed. | A table layout specification contains an | ||
.El | .Sq Cm m | ||
.Sh COMPATIBILITY | modifier. | ||
This section summarises | The modifier is discarded. | ||
.Nm | .It Sy "ignoring macro in table" | ||
compatibility with GNU troff. | .Pq tbl , mdoc , man | ||
Each input and output format is separately noted. | A table contains an invocation of an | ||
.Ss ASCII Compatibility | |||
.Bl -bullet -compact | |||
.It | |||
Unrenderable unicode codepoints specified with | |||
.Sq \e[uNNNN] | |||
escapes are printed as | |||
.Sq \&? | |||
in mandoc. | |||
In GNU troff, these raise an error. | |||
.It | |||
The | |||
.Sq \&Bd \-literal | |||
and | |||
.Sq \&Bd \-unfilled | |||
macros of | |||
.Xr mdoc 7 | .Xr mdoc 7 | ||
in | or | ||
.Fl T Ns Cm ascii | |||
are synonyms, as are \-filled and \-ragged. | |||
.It | |||
In historic GNU troff, the | |||
.Sq \&Pa | |||
.Xr mdoc 7 | |||
macro does not underline when scoped under an | |||
.Sq \&It | |||
in the FILES section. | |||
This behaves correctly in | |||
.Nm . | |||
.It | |||
A list or display following the | |||
.Sq \&Ss | |||
.Xr mdoc 7 | |||
macro in | |||
.Fl T Ns Cm ascii | |||
does not assert a prior vertical break, just as it doesn't with | |||
.Sq \&Sh . | |||
.It | |||
The | |||
.Sq \&na | |||
.Xr man 7 | .Xr man 7 | ||
macro in | macro or of an undefined macro. | ||
.Fl T Ns Cm ascii | The macro is ignored, and its arguments are handled | ||
has no effect. | as if they were a text line. | ||
.It | |||
Words aren't hyphenated. | |||
.El | .El | ||
.Ss HTML Compatibility | |||
.Bl -bullet -compact | |||
.It | |||
The | |||
.Sq \efP | |||
escape will revert the font to the previous | |||
.Sq \ef | |||
escape, not to the last rendered decoration, which is now dictated by | |||
CSS instead of hard-coded. | |||
It also will not span past the current scope, | |||
for the same reason. | |||
Note that in | |||
.Sx ASCII Output | |||
mode, this will work fine. | |||
.It | |||
The | |||
.Xr mdoc 7 | |||
.Sq \&Bl \-hang | |||
and | |||
.Sq \&Bl \-tag | |||
list types render similarly (no break following overreached left-hand | |||
side) due to the expressive constraints of HTML. | |||
.It | |||
The | |||
.Xr man 7 | |||
.Sq IP | |||
and | |||
.Sq TP | |||
lists render similarly. | |||
.El | |||
.Sh SEE ALSO | .Sh SEE ALSO | ||
.Xr apropos 1 , | |||
.Xr man 1 , | |||
.Xr eqn 7 , | .Xr eqn 7 , | ||
.Xr man 7 , | .Xr man 7 , | ||
.Xr mandoc_char 7 , | .Xr mandoc_char 7 , | ||
.Xr mdoc 7 , | .Xr mdoc 7 , | ||
.Xr roff 7 , | .Xr roff 7 , | ||
.Xr tbl 7 | .Xr tbl 7 | ||
.Sh AUTHORS | .Sh HISTORY | ||
The | The | ||
.Nm | .Nm | ||
utility was written by | utility first appeared in | ||
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . | .Ox 4.8 . | ||
.Sh CAVEATS | The option | ||
In | .Fl I | ||
.Fl T Ns Cm html | appeared in | ||
.Ox 5.2 , | |||
and | and | ||
.Fl T Ns Cm xhtml , | .Fl aCcfhKklMSsw | ||
the maximum size of an element attribute is determined by | in | ||
.Dv BUFSIZ , | .Ox 5.7 . | ||
which is usually 1024 bytes. | .Sh AUTHORS | ||
Be aware of this when setting long link | .An -nosplit | ||
formats such as | |||
.Fl O Ns Cm style Ns = Ns Ar really/long/link . | |||
.Pp | |||
Nesting elements within next-line element scopes of | |||
.Fl m Ns Cm an , | |||
such as | |||
.Sq br | |||
within an empty | |||
.Sq B , | |||
will confuse | |||
.Fl T Ns Cm html | |||
and | |||
.Fl T Ns Cm xhtml | |||
and cause them to forget the formatting of the prior next-line scope. | |||
.Pp | |||
The | The | ||
.Sq \(aq | .Nm | ||
control character is an alias for the standard macro control character | utility was written by | ||
and does not emit a line-break as stipulated in GNU troff. | .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv | ||
and is maintained by | |||
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |