mandoc: Better document the purpose and features of the file mandoc.css

[schwarze@mandoc.bsd.lv]

Log Message:
-----------
Better document the purpose and features of the file mandoc.css
and the purpose and limitations of the embedded stylesheet.

Triggered by a conversation with Alejandro Colomar <alx at kernel dot org>.

Modified Files:
--------------
    mandoc:
        mandoc.1

Revision Data
-------------
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.1,v
retrieving revision 1.264
retrieving revision 1.265
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.264 -r1.265
--- mandoc.1
+++ mandoc.1
@@ -345,17 +345,6 @@ conforms to HTML5 using optional self-cl
 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
--
 To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv