version 1.262, 2022/07/03 14:36:00 |
version 1.266, 2023/10/24 20:53:12 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2012, 2014-2022 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 345 conforms to HTML5 using optional self-closing tags. |
|
Line 345 conforms to HTML5 using optional self-closing tags. |
|
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 406 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 738 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 765 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 1268 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 1591 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 |
Line 2127 request is neither a single ASCII character |
|
Line 2158 request is neither a single ASCII character |
|
nor a single character escape sequence. |
nor a single character escape sequence. |
All arguments are ignored and printing of a margin character is disabled. |
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 2258 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 |