version 1.123, 2014/11/25 20:18:15 |
version 1.131, 2015/01/14 22:02:49 |
|
|
.\" $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, 2015 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 |
|
|
text from stdin, implying |
text from stdin, implying |
.Fl m Ns Cm andoc , |
.Fl m Ns Cm andoc , |
and produces |
and produces |
.Fl T Ns Cm ascii |
.Fl T Ns Cm locale |
output. |
output. |
.Pp |
.Pp |
The options are as follows: |
The options are as follows: |
Line 85 Override the default operating system |
|
Line 85 Override the default operating system |
|
for the |
for the |
.Xr mdoc 7 |
.Xr mdoc 7 |
.Sq \&Os |
.Sq \&Os |
|
and for the |
|
.Xr man 7 |
|
.Sq \&TH |
macro. |
macro. |
.It Fl h |
.It Fl h |
Display only the SYNOPSIS lines. |
Display only the SYNOPSIS lines. |
|
|
.Sx Output Formats |
.Sx Output Formats |
for available formats. |
for available formats. |
Defaults to |
Defaults to |
.Fl T Ns Cm ascii . |
.Fl T Ns Cm locale . |
.It Fl V |
.It Fl V |
Print version and exit. |
Print version and exit. |
.It Fl W Ns Ar level |
.It Fl W Ns Ar level |
Line 255 arguments, which correspond to output modes: |
|
Line 258 arguments, which correspond to output modes: |
|
.Bl -tag -width "-Tlocale" |
.Bl -tag -width "-Tlocale" |
.It Fl T Ns Cm ascii |
.It Fl T Ns 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 Ns Cm html |
|
|
.Fl W Ns Cm warning . |
.Fl W Ns Cm warning . |
.It Fl T Ns Cm locale |
.It Fl T Ns 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 Ns Cm man |
Line 299 If multiple input files are specified, these will be p |
|
Line 302 If multiple input files are specified, these will be p |
|
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 Ns 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 |
|
|
.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 Ns 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 |
Line 538 A fatal parsing error occurred. |
|
Line 543 A fatal parsing error occurred. |
|
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. |
|
|
.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 |
|
Opening or reading an input file failed, so the parser cannot |
|
even be started and no output is produced from that input file. |
|
.It Cm fatal |
.It Cm fatal |
The parser is unable to parse a given input file at all. |
The parser is unable to parse a given input file at all. |
No formatted output is produced from that input file. |
No formatted output is produced from that input file. |
Line 614 the parser is able to continue, and the error does not |
|
Line 616 the parser is able to continue, and the error does not |
|
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. |
|
.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 |
|
|
.Cm warning |
.Cm warning |
and |
and |
.Cm error |
.Cm error |
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 Ns Cm lint |
Line 665 macro lacks the mandatory section argument. |
|
Line 674 macro lacks the mandatory section argument. |
|
The section number in a |
The section number in a |
.Ic \&Dt |
.Ic \&Dt |
line is invalid, but still used. |
line is invalid, but still used. |
.It Sy "unknown manual volume or arch" |
|
.Pq mdoc |
|
The volume name in a |
|
.Ic \&Dt |
|
line is invalid, but still used. |
|
The manual is assumed to be architecture-independent. |
|
.It Sy "missing date, using today's date" |
.It Sy "missing date, using today's date" |
.Pq mdoc, man |
.Pq mdoc, man |
The document was parsed as |
The document was parsed as |
Line 809 Probably, there are author names lacking markup. |
|
Line 812 Probably, there are author names lacking markup. |
|
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 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 |
Line 1053 argument is invalid. |
|
Line 1063 argument is invalid. |
|
The default font |
The default font |
.Cm \efR |
.Cm \efR |
is used instead. |
is used instead. |
|
.It Sy "nothing follows prefix" |
|
.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 "missing -std argument, adding it" |
.It Sy "missing -std argument, adding it" |
.Pq mdoc |
.Pq mdoc |
An |
An |
Line 1255 keeps the code more readable. |
|
Line 1273 keeps the code more readable. |
|
.It "ignore data in cell" |
.It "ignore data in cell" |
.It "data block still open" |
.It "data block still open" |
.It "ignoring extra data cells" |
.It "ignoring extra data cells" |
|
.It "ignoring macro in table" |
.El |
.El |
.Ss "Errors related to roff, mdoc, and man code" |
.Ss "Errors related to roff, mdoc, and man code" |
.Bl -ohang |
.Bl -ohang |
Line 1396 The indicated request or macro has too few or too many |
|
Line 1415 The indicated request or macro has too few or too many |
|
The syntax tree will contain the wrong number of arguments as given. |
The syntax tree will contain the wrong number of arguments as given. |
Formatting behaviour depends on the specific request or macro in question. |
Formatting behaviour depends on the specific request or macro in question. |
Note that the same message may also occur as a WARNING, see above. |
Note that the same message may also occur as a WARNING, see above. |
|
.It Sy "NOT IMPLEMENTED: Bd -file" |
|
.Pq mdoc |
|
For security reasons, the |
|
.Ic \&Bd |
|
macro does not support the |
|
.Fl file |
|
argument. |
|
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 argument is ignored including the file name following it. |
.It Sy "missing list type, using -item" |
.It Sy "missing list type, using -item" |
.Pq mdoc |
.Pq mdoc |
A |
A |
Line 1484 cannot handle input files larger than its arbitrary si |
|
Line 1514 cannot handle input files larger than its arbitrary si |
|
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: Bd -file" |
|
.Pq mdoc |
|
For security reasons, the |
|
.Ic \&Bd |
|
macro does not support the |
|
.Fl file |
|
argument. |
|
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 "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, |