mandoc/mandoc.1 - diff

Return to mandoc.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.254 and 1.265

version 1.254, 2022/02/08 18:27:45

version 1.265, 2023/10/18 14:34:29

Line 1

.\" $OpenBSD$

.\" $Id$

.\"

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

Line 342 and may exceed the output width.

Output produced by

.Fl T Cm html

conforms to HTML5 using optional self-closing tags.

Default styles use only CSS1.

Equations rendered from

.Xr eqn 7

blocks use MathML.

.Pp

The file

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

documents style-sheet classes available for customising output.

If a style-sheet is not specified with

.Fl O Cm style ,

.Fl T Cm html

defaults to simple output (via an embedded style-sheet)

readable in any graphical or text-based web

browser.

.Pp

Non-ASCII characters are rendered

as hexadecimal Unicode character references.

.Pp

Line 407 otherwise, the second format is used.

Line 395 otherwise, the second format is used.

.It Cm style Ns = Ns Ar style.css

The file

.Ar style.css

is used for an external style-sheet.

is used as an external stylesheet.

This must be a valid absolute or

relative URI.

.Pp

Using the file

.Pa mandoc.css

that is distributed with

.Nm

is recommended.

It provides an appearance similar to terminal output with some additional

features specific to

.Nm

HTML output, in particular making anchor locations that support

deep linking stand out visually by putting a dotted line under them,

providing tooltips showing the semantic function of elements (macro

names), providing some simple aspects of responsive web design, and

providing simple support for users who prefer a dark color scheme.

.Pp

Using a custom CSS file is possible, but writing it requires

proficiency in all of the languages HTML 5, CSS 4, and

.Xr mdoc 7

and familiarity with the

.Nm Ns -specific

classes used in

.Pa mandoc.css .

Besides, while the file

.Pa mandoc.css

is always adapted to the HTML output generated by the

.Nm

version it is distributed with, maintaining a custom CSS file usually

requires adaptations each time

.Nm

is upgraded to a new version.

.Pp

If a stylesheet is not specified with

.Fl O Cm style ,

.Fl T Cm html

embeds a minimal stylesheet into the HTML output, mostly to select

adequate font-style and font-weight attributes for various macros.

The result is readable in any graphical or text-based web browser,

but does not aim for looking similar to terminal output.

Instead, formatting is mostly left to browser defaults

and to user settings in the browser configuration.

.It Cm tag Ns Op = Ns Ar term

Same syntax and semantics as for

.Sx ASCII Output .

Line 487 Use

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

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

as the style-sheet:

as the stylesheet:

.Pp

.Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html

.Pp

Line 766 Messages displayed by

Line 794 Messages displayed by

follow this format:

.Bd -ragged -offset indent

.Nm :

.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments

.Ar file : Ns Ar line : Ns Ar column : level : message : macro argument ...

.Pq Ar os

.Ed

.Pp

Line 786 and

Line 814 and

strings are explained below.

The name of the

.Ar macro

triggering the message and its

triggering the message and its arguments are omitted where meaningless.

.Ar arguments

are omitted where meaningless.

The

.Ar os

operating system specifier is omitted for messages that are relevant

Line 1474 A

Line 1500 A

.Ic \&Bl ,

.Ic \&D1 ,

.Ic \&Dl ,

.Ic \&MT ,

.Ic \&RS ,

.Ic \&UR

.Ic \&RS

block contains nothing in its body and will produce no output.

.It Sy "empty argument, using 0n"

.Pq mdoc

Line 1754 request or a

Line 1778 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 1821 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 2102 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 2144 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 2261 or

Line 2295 or

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

.Bl -ohang

CVSweb