version 1.256, 2022/04/14 10:10:22 |
version 1.266, 2023/10/24 20:53:12 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2012, 2014-2021 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2012, 2014-2023 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 |
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. |
.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 |
Non-ASCII characters are rendered |
as hexadecimal Unicode character references. |
as hexadecimal Unicode character references. |
.Pp |
.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 |
.It Cm style Ns = Ns Ar style.css |
The file |
The file |
.Ar style.css |
.Ar style.css |
is used for an external style-sheet. |
is used as an external stylesheet. |
This must be a valid absolute or |
This must be a valid absolute or |
relative URI. |
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 |
.It Cm tag Ns Op = Ns Ar term |
Same syntax and semantics as for |
Same syntax and semantics as for |
.Sx ASCII Output . |
.Sx ASCII Output . |
Line 739 To page manuals to the terminal: |
|
Line 767 To page manuals to the terminal: |
|
.Pp |
.Pp |
To produce HTML manuals with |
To produce HTML manuals with |
.Pa /usr/share/misc/mandoc.css |
.Pa /usr/share/misc/mandoc.css |
as the style-sheet: |
as the stylesheet: |
.Pp |
.Pp |
.Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html |
.Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html |
.Pp |
.Pp |
Line 766 Messages displayed by |
|
Line 794 Messages displayed by |
|
follow this format: |
follow this format: |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Nm : |
.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 |
.Pq Ar os |
.Ed |
.Ed |
.Pp |
.Pp |
|
|
strings are explained below. |
strings are explained below. |
The name of the |
The name of the |
.Ar macro |
.Ar macro |
triggering the message and its |
triggering the message and its arguments are omitted where meaningless. |
.Ar arguments |
|
are omitted where meaningless. |
|
The |
The |
.Ar os |
.Ar os |
operating system specifier is omitted for messages that are relevant |
operating system specifier is omitted for messages that are relevant |
Line 1269 The same standard section title occurs more than once. |
|
Line 1295 The same standard section title occurs more than once. |
|
A standard section header occurs in a section of the manual |
A standard section header occurs in a section of the manual |
where it normally isn't useful. |
where it normally isn't useful. |
.It Sy "cross reference to self" |
.It Sy "cross reference to self" |
.Pq mdoc |
.Pq mdoc , man |
An |
An |
.Ic \&Xr |
.Ic \&Xr |
|
or |
|
.Ic \&MR |
macro refers to a name and section matching the section of the present |
macro refers to a name and section matching the section of the present |
manual page and a name mentioned in an |
manual page and a name mentioned in an |
.Ic \&Nm |
.Ic \&Nm |
|
|
.Ic \&Bl , |
.Ic \&Bl , |
.Ic \&D1 , |
.Ic \&D1 , |
.Ic \&Dl , |
.Ic \&Dl , |
.Ic \&MT , |
|
.Ic \&RS , |
|
or |
or |
.Ic \&UR |
.Ic \&RS |
block contains nothing in its body and will produce no output. |
block contains nothing in its body and will produce no output. |
.It Sy "empty argument, using 0n" |
.It Sy "empty argument, using 0n" |
.Pq mdoc |
.Pq mdoc |
Line 1592 macro is immediately followed by an |
|
Line 1618 macro is immediately followed by an |
|
macro on the next input line. |
macro on the next input line. |
Such an empty block does not produce any output. |
Such an empty block does not produce any output. |
.It Sy "missing section argument" |
.It Sy "missing section argument" |
.Pq mdoc |
.Pq mdoc , man |
An |
An |
.Ic \&Xr |
.Ic \&Xr |
|
or |
|
.Ic \&MR |
macro lacks its second, section number argument. |
macro lacks its second, section number argument. |
The first argument, i.e. the name, is printed, but without subsequent |
The first argument, i.e. the name, is printed, but without a section number. |
parentheses. |
In the case of |
|
.Ic \&Xr , |
|
the parentheses are also omitted. |
.It Sy "missing -std argument, adding it" |
.It Sy "missing -std argument, adding it" |
.Pq mdoc |
.Pq mdoc |
An |
An |
|
|
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 1788 it is hard to predict which tab stop position the tab |
|
Line 1827 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 2082 and expands to the empty string. |
|
Line 2108 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 2150 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 , man |
The first call to |
The first call to |
.Ic \&Nm , |
.Ic \&Nm , |
or any call in the NAME section, lacks the required argument. |
or any call in the NAME section, lacks the required argument, or |
|
.Ic \&MR |
|
is called without any argument. |
.It Sy "uname(3) system call failed, using UNKNOWN" |
.It Sy "uname(3) system call failed, using UNKNOWN" |
.Pq mdoc |
.Pq mdoc |
The |
The |
Line 2249 or a request of the |
|
Line 2291 or a request of the |
|
family with more than two arguments |
family with more than two arguments |
.It |
.It |
.Ic \&Dt |
.Ic \&Dt |
|
or |
|
.Ic \&MR |
with more than three arguments |
with more than three arguments |
.It |
.It |
.Ic \&TH |
.Ic \&TH |
|
|
with invalid arguments |
with invalid arguments |
.El |
.El |
The excess arguments are ignored. |
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] |
|
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 |
.El |
.Ss Unsupported features |
.Ss Unsupported features |
.Bl -ohang |
.Bl -ohang |