summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--mandoc.155
1 files changed, 42 insertions, 13 deletions
diff --git a/mandoc.1 b/mandoc.1
index 26b3028d..106db4b9 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -345,17 +345,6 @@ conforms to HTML5 using optional self-closing tags.
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
@@ -406,9 +395,49 @@ 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 .
@@ -738,7 +767,7 @@ To page manuals to the terminal:
.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