version 1.251, 2021/06/28 19:50:15 |
version 1.259, 2022/06/05 13:54:09 |
|
|
.\" $OpenBSD$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2012, 2014-2021 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 |
|
|
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 735 output mode implies |
|
Line 735 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 835 message levels, the |
|
Line 835 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 |
|
|
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 1790 A new sentence starts in the middle of a text line. |
|
Line 1799 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" |
.Pq roff |
.Pq roff |
An escape sequence has an invalid opening argument delimiter, lacks the |
An escape sequence has an invalid opening argument delimiter |
closing argument delimiter, the argument is of an invalid form, or it is |
or the argument is of an invalid form. |
a character escape sequence with an invalid name. |
Invalid escape sequences are ignored. |
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 2082 and expands to the empty string. |
|
Line 2079 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 2117 The first argument of a |
|
Line 2121 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 2262 with invalid arguments |
|
Line 2273 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. |
|
.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 , |