From b379b08b615643dbcb535de629fdeb7e8fac13ea Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 18 Oct 2023 14:47:22 +0000 Subject: [PATCH] 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 . --- usr.bin/mandoc/mandoc.1 | 59 ++++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/usr.bin/mandoc/mandoc.1 b/usr.bin/mandoc/mandoc.1 index e571053cd25..fd8d4d6f21d 100644 --- a/usr.bin/mandoc/mandoc.1 +++ b/usr.bin/mandoc/mandoc.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mandoc.1,v 1.190 2022/12/22 19:53:23 kn Exp $ +.\" $OpenBSD: mandoc.1,v 1.191 2023/10/18 14:47:22 schwarze Exp $ .\" .\" Copyright (c) 2012, 2014-2022 Ingo Schwarze .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: December 22 2022 $ +.Dd $Mdocdate: October 18 2023 $ .Dt MANDOC 1 .Os .Sh NAME @@ -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 -- 2.20.1