version 1.260, 2022/06/07 09:54:40 |
version 1.265, 2023/10/18 14:34:29 |
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 |
|
|
.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 2321 attempts to employ one of the characters |
|
Line 2345 attempts to employ one of the characters |
|
as an argument delimiter. |
as an argument delimiter. |
The escape sequence is ignored including the invalid opening delimiter |
The escape sequence is ignored including the invalid opening delimiter |
and the rest of the argument may appear as output text. |
and the rest of the argument may appear as output text. |
While various charcters can be used as argument delimiters, |
While various characters can be used as argument delimiters, |
using the apostrophe-quote character |
using the apostrophe-quote character |
.Pq Sq \(aq |
.Pq Sq \(aq |
is recommended for readability and robustness. |
is recommended for readability and robustness. |