diff options
| -rw-r--r-- | mandoc.1 | 55 |
1 files changed, 42 insertions, 13 deletions
@@ -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 |