mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.251 and 1.260

version 1.251, 2021/06/28 19:50:15

version 1.260, 2022/06/07 09:54:40

Line 1

.\" $OpenBSD$

.\" $Id$

.\"

.\" Permission to use, copy, modify, and distribute this software for any

Line 487 Use

to translate

.Xr mdoc 7

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" .

The output also almost conforms to the

.Lk http://commonmark.org/ CommonMark

.Lk https://commonmark.org/ CommonMark

specification.

.Pp

The character set used for the markdown output is ASCII.

Line 735 output mode implies

.Sh EXAMPLES

To page manuals to the terminal:

.Pp

.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8

.Dl $ mandoc -a mandoc.1 man.1 apropos.1 makewhatis.8

.Pp

To produce HTML manuals with

.Pa /usr/share/misc/mandoc.css

Line 835 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

Use your judgement to decide whether any particular

.Cm style

suggestion really justifies a change to the input file.

.It Cm base

Line 1754 request or a

layout modifier has an unknown

.Ar font

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"

.Pq roff

Line 1788 it is hard to predict which tab stop position the tab

Line 1797 it is hard to predict which tab stop position the tab

.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 "invalid escape sequence"

.It Sy "invalid escape sequence argument"

.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"

.Pq roff

In an escape sequence, the first character

Line 2082 and expands to the empty string.

Line 2078 and expands to the empty string.

.Pq roff

The argument of the escape sequence \e$ is not a digit;

the escape sequence expands to the empty string.

.It Sy "negative argument, using 0"

.Pq roff

.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"

.Pq mdoc

For security reasons, the

Line 2117 The first argument of a

Line 2120 The first argument of a

request is neither a single ASCII character

nor a single character escape sequence.

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"

.Pq mdoc

The first call to

Line 2262 with invalid arguments

Line 2272 with invalid arguments

.El

The excess arguments are ignored.

.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]

.Qq \e[~]

instead of

.Qq \ee

.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 charcters can be used as argument delimiters,

using the apostrophe-quote character

.Pq Sq \(aq

is recommended for readability and robustness.

.El

.Ss Unsupported features

.Bl -ohang

.It Sy "input too large"

Line 2314 or

Line 2378 or

macro or of an undefined macro.

The macro is ignored, and its arguments are handled

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

.Ss Bad command line arguments

.Bl -ohang

Line 2351 The

Line 2435 The

.Fl O Cm tag

option was specified but the tag was not found in any of the displayed

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

.Sh SEE ALSO

.Xr apropos 1 ,

CVSweb