From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: * X-Spam-Status: No, score=1.0 required=5.0 tests=PDS_BRAND_SUBJ_NAKED_TO, UNPARSEABLE_RELAY autolearn=no autolearn_force=no version=3.4.4 Received: (qmail 6850 invoked from network); 18 Oct 2023 14:35:01 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 18 Oct 2023 14:35:01 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 318a83cc for ; Wed, 18 Oct 2023 14:34:59 +0000 (UTC) Received: from localhost (mandoc.bsd.lv [local]) by mandoc.bsd.lv (OpenSMTPD) with ESMTPA id 3186ee0c for ; Wed, 18 Oct 2023 14:34:59 +0000 (UTC) Date: Wed, 18 Oct 2023 14:34:59 +0000 (UTC) X-Mailinglist: mandoc-source Reply-To: source@mandoc.bsd.lv MIME-Version: 1.0 From: schwarze@mandoc.bsd.lv To: source@mandoc.bsd.lv Subject: mandoc: Better document the purpose and features of the file mandoc.css X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 Message-ID: <94815cd1ab6eeb6a@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 . 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