version 1.246, 2020/08/27 14:28:11 |
version 1.262, 2022/07/03 14:36:00 |
|
|
.\" $OpenBSD$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2012, 2014-2020 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2012, 2014-2022 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
|
|
input files in |
input files in |
.Xr mdoc 7 |
.Xr mdoc 7 |
output style. |
output style. |
Specifically, this suppresses the two additional blank lines near the |
This prints the operating system name rather than the page title |
top and the bottom of each page, and it implies |
on the right side of the footer line, and it implies |
.Fl O Cm indent Ns =5 . |
.Fl O Cm indent Ns =5 . |
One useful application is for checking that |
One useful application is for checking that |
.Fl T Cm man |
.Fl T Cm man |
Line 342 and may exceed the output width. |
|
Line 342 and may exceed the output width. |
|
Output produced by |
Output produced by |
.Fl T 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. |
|
Equations rendered from |
Equations rendered from |
.Xr eqn 7 |
.Xr eqn 7 |
blocks use MathML. |
blocks use MathML. |
Line 475 code is not supported. |
|
Line 474 code is not supported. |
|
.Pp |
.Pp |
If the input format of a file is |
If the input format of a file is |
.Xr man 7 , |
.Xr man 7 , |
the input is copied to the output, expanding any |
the input is copied to the output. |
.Xr roff 7 |
|
.Ic so |
|
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 |
|
|
to translate |
to translate |
.Xr mdoc 7 |
.Xr mdoc 7 |
input to the markdown format conforming to |
input to the markdown format conforming to |
.Lk http://daringfireball.net/projects/markdown/syntax.text\ |
.Lk https://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 |
.Lk http://commonmark.org/ CommonMark |
.Lk https://commonmark.org/ CommonMark |
specification. |
specification. |
.Pp |
.Pp |
The character set used for the markdown output is ASCII. |
The character set used for the markdown output is ASCII. |
Line 738 output mode implies |
|
Line 734 output mode implies |
|
.Sh EXAMPLES |
.Sh EXAMPLES |
To page manuals to the terminal: |
To page manuals to the terminal: |
.Pp |
.Pp |
.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 |
.Dl $ mandoc -a mandoc.1 man.1 apropos.1 makewhatis.8 |
.Pp |
.Pp |
To produce HTML manuals with |
To produce HTML manuals with |
.Pa /usr/share/misc/mandoc.css |
.Pa /usr/share/misc/mandoc.css |
Line 838 message levels, the |
|
Line 834 message levels, the |
|
.Cm style |
.Cm style |
level tries to reduce the probability that issues go unnoticed, |
level tries to reduce the probability that issues go unnoticed, |
so it may occasionally issue bogus suggestions. |
so it may occasionally issue bogus suggestions. |
Please use your good judgement to decide whether any particular |
Use your judgement to decide whether any particular |
.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 |
Line 925 generated by CVS |
|
Line 921 generated by CVS |
|
or |
or |
.Ic NetBSD |
.Ic NetBSD |
keyword substitution as conventionally used in these operating systems. |
keyword substitution as conventionally used in these operating systems. |
.It Sy "referenced manual not found" |
|
.Pq mdoc |
|
An |
|
.Ic \&Xr |
|
macro references a manual page that is not found in the base system. |
|
The path to look for base system manuals is configurable at compile |
|
time and defaults to |
|
.Pa /usr/share/man : /usr/X11R6/man . |
|
.El |
.El |
.Ss Style suggestions |
.Ss Style suggestions |
.Bl -ohang |
.Bl -ohang |
Line 1019 list contains two consecutive |
|
Line 1007 list contains two consecutive |
|
entries describing the same |
entries describing the same |
.Ic \&Er |
.Ic \&Er |
number. |
number. |
|
.It Sy "referenced manual not found" |
|
.Pq mdoc |
|
An |
|
.Ic \&Xr |
|
macro references a manual page that was not found. |
|
When running with |
|
.Fl W Cm base , |
|
the search is restricted to the base system, by default to |
|
.Pa /usr/share/man : Ns Pa /usr/X11R6/man . |
|
This path can be configured at compile time using the |
|
.Dv MANPATH_BASE |
|
preprocessor macro. |
|
When running with |
|
.Fl W Cm style , |
|
the search is done along the full search path as described in the |
|
.Xr man 1 |
|
manual page, respecting the |
|
.Fl m |
|
and |
|
.Fl M |
|
command line options, the |
|
.Ev MANPATH |
|
environment variable, the |
|
.Xr man.conf 5 |
|
file and falling back to the default of |
|
.Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man , |
|
also configurable at compile time using the |
|
.Dv MANPATH_DEFAULT |
|
preprocessor macro. |
.It Sy "trailing delimiter" |
.It Sy "trailing delimiter" |
.Pq mdoc |
.Pq mdoc |
The last argument of an |
The last argument of an |
|
|
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 "input text line longer than 80 bytes" |
|
Consider breaking the input text line |
|
at one of the blank characters before column 80. |
.It Sy "verbatim \(dq--\(dq, maybe consider using \e(em" |
.It Sy "verbatim \(dq--\(dq, maybe consider using \e(em" |
.Pq mdoc |
.Pq mdoc |
Even though the ASCII output device renders an em-dash as |
Even though the ASCII output device renders an em-dash as |
|
|
layout modifier has an unknown |
layout modifier has an unknown |
.Ar font |
.Ar font |
argument. |
argument. |
|
.It Sy "ignoring distance argument" |
|
.Pq roff |
|
In addition to the margin character, an |
|
.Ic \&mc |
|
request has a second argument supposed to represent a distance, but the |
|
.Nm |
|
implementation of |
|
.Ic \&mc |
|
always ignores the second argument. |
.It Sy "odd number of characters in request" |
.It Sy "odd number of characters in request" |
.Pq roff |
.Pq roff |
A |
A |
Line 1767 it is hard to predict which tab stop position the tab |
|
Line 1796 it is hard to predict which tab stop position the tab |
|
.Pq mdoc |
.Pq mdoc |
A new sentence starts in the middle of a text line. |
A new sentence starts in the middle of a text line. |
Start it on a new input line to help formatters produce correct spacing. |
Start it on a new input line to help formatters produce correct spacing. |
.It Sy "invalid escape sequence" |
.It Sy "invalid escape sequence argument" |
.Pq roff |
.Pq roff |
An escape sequence has an invalid opening argument delimiter, lacks the |
The argument of an escape sequence is of an invalid form. |
closing argument delimiter, the argument is of an invalid form, or it is |
Invalid escape sequences are ignored. |
a character escape sequence with an invalid name. |
|
If the argument is incomplete, |
|
.Ic \e* |
|
and |
|
.Ic \en |
|
expand to an empty string, |
|
.Ic \eB |
|
to the digit |
|
.Sq 0 , |
|
and |
|
.Ic \ew |
|
to the length of the incomplete argument. |
|
All other invalid escape sequences are ignored. |
|
.It Sy "undefined escape, printing literally" |
.It Sy "undefined escape, printing literally" |
.Pq roff |
.Pq roff |
In an escape sequence, the first character |
In an escape sequence, the first character |
Line 1853 The invalid character is discarded. |
|
Line 1869 The invalid character is discarded. |
|
A table layout specification contains an opening parenthesis, |
A table layout specification contains an opening parenthesis, |
but no matching closing parenthesis. |
but no matching closing parenthesis. |
The rest of the input line, starting from the parenthesis, has no effect. |
The rest of the input line, starting from the parenthesis, has no effect. |
|
.It Sy "ignoring excessive spacing in tbl layout" |
|
.Pq tbl |
|
A spacing modifier in a table layout is unreasonably large. |
|
The default spacing of 3n is used instead. |
.It Sy "tbl without any data cells" |
.It Sy "tbl without any data cells" |
.Pq tbl |
.Pq tbl |
A table does not contain any data cells. |
A table does not contain any data cells. |
Line 2057 and expands to the empty string. |
|
Line 2077 and expands to the empty string. |
|
.Pq roff |
.Pq roff |
The argument of the escape sequence \e$ is not a digit; |
The argument of the escape sequence \e$ is not a digit; |
the escape sequence expands to the empty string. |
the escape sequence expands to the empty string. |
|
.It Sy "negative argument, using 0" |
|
.Pq roff |
|
A |
|
.Ic \&shift |
|
request has a negative argument |
|
or an argument that is negative due to integer overflow. |
|
Macro argument numbering remains unchanged. |
.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 2092 The first argument of a |
|
Line 2119 The first argument of a |
|
request is neither a single ASCII character |
request is neither a single ASCII character |
nor a single character escape sequence. |
nor a single character escape sequence. |
The request is ignored including all its arguments. |
The request is ignored including all its arguments. |
|
.It Sy "skipping unusable escape sequence" |
|
.Pq roff |
|
The first argument of an |
|
.Ic mc |
|
request is neither a single ASCII character |
|
nor a single character escape sequence. |
|
All arguments are ignored and printing of a margin character is disabled. |
.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 |
Line 2237 with invalid arguments |
|
Line 2271 with invalid arguments |
|
.El |
.El |
The excess arguments are ignored. |
The excess arguments are ignored. |
.El |
.El |
|
.Ss "Errors related to escape sequences" |
|
.Bl -ohang |
|
.It Sy "incomplete escape sequence" |
|
.Pq roff |
|
The end of the input line is encountered |
|
while parsing the argument of an escape sequence. |
|
In this case, |
|
.Ic \e* |
|
and |
|
.Ic \en |
|
expand to an empty string, |
|
.Ic \eB |
|
to the digit |
|
.Sq 0 , |
|
and |
|
.Ic \ew |
|
to the length of the incomplete argument. |
|
All other incomplete escape sequences are ignored. |
|
.It Sy "invalid special character" |
|
.Pq roff |
|
A special character escape sequence is invalid, |
|
for example a Unicode sequence pointing to a surrogate |
|
or beyond the Unicode range, a \e[char...] escape sequence |
|
representing a control character or pointing beyond the |
|
.Vt unsigned char |
|
range, or an invalid variable-length form |
|
of a single-byte character escape sequence, for example writing |
|
.Qq \e[e] |
|
or |
|
.Qq \e[~] |
|
instead of |
|
.Qq \ee |
|
or |
|
.Qq \e~ , |
|
respectively. |
|
The escape sequence is ignored. |
|
.It Sy "unknown special character" |
|
.Pq roff |
|
The name given in a special character escape sequence is not known to |
|
.Nm . |
|
The escape sequence is ignored. |
|
.It Sy "invalid escape argument delimiter" |
|
.Pq roff |
|
An escape sequence that expects a numerical argument |
|
attempts to employ one of the characters |
|
.Qq " %&()*+-./0123456789:<=>" |
|
as an argument delimiter. |
|
The escape sequence is ignored including the invalid opening delimiter |
|
and the rest of the argument may appear as output text. |
|
While various characters can be used as argument delimiters, |
|
using the apostrophe-quote character |
|
.Pq Sq \(aq |
|
is recommended for readability and robustness. |
|
.El |
.Ss Unsupported features |
.Ss Unsupported features |
.Bl -ohang |
.Bl -ohang |
.It Sy "input too large" |
.It Sy "input too large" |
|
|
macro or of an undefined macro. |
macro or of an undefined macro. |
The macro is ignored, and its arguments are handled |
The macro is ignored, and its arguments are handled |
as if they were a text line. |
as if they were a text line. |
|
.It Sy "skipping tbl in -Tman mode" |
|
.Pq mdoc , tbl |
|
An input file contains the |
|
.Ic \&TS |
|
macro. |
|
This message is only generated in |
|
.Fl T Cm man |
|
output mode, where |
|
.Xr tbl 7 |
|
input is not supported. |
|
.It Sy "skipping eqn in -Tman mode" |
|
.Pq mdoc , eqn |
|
An input file contains the |
|
.Ic \&EQ |
|
macro. |
|
This message is only generated in |
|
.Fl T Cm man |
|
output mode, where |
|
.Xr eqn 7 |
|
input is not supported. |
.El |
.El |
.Ss Bad command line arguments |
.Ss Bad command line arguments |
.Bl -ohang |
.Bl -ohang |
|
|
.Fl O Cm tag |
.Fl O Cm tag |
option was specified but the tag was not found in any of the displayed |
option was specified but the tag was not found in any of the displayed |
manual pages. |
manual pages. |
|
.It Sy "\-Tmarkdown unsupported for man(7) input" |
|
.Pq man |
|
The |
|
.Fl T Cm markdown |
|
option was specified but an input file uses the |
|
.Xr man 7 |
|
language. |
|
No output is produced for that input file. |
.El |
.El |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr apropos 1 , |
.Xr apropos 1 , |