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=0.0 required=5.0 tests=none autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 7414 invoked from network); 18 Oct 2023 14:48:20 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 18 Oct 2023 14:48:20 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id d4d0e603 for ; Wed, 18 Oct 2023 14:48:19 +0000 (UTC) Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id f00b80c1 for ; Wed, 18 Oct 2023 14:48:19 +0000 (UTC) Received: from hekate.asta.kit.edu ([2a00:1398:5:f401::77]) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.3:ECDHE_SECP256R1__RSA_PSS_RSAE_SHA256__AES_256_GCM:256) (envelope-from ) id 1qt7qL-00CRmI-1V; Wed, 18 Oct 2023 16:48:18 +0200 Received: from login-1.asta.kit.edu ([2a00:1398:5:f400::72]) by hekate.asta.kit.edu with esmtp (Exim 4.94.2) (envelope-from ) id 1qt7qL-000FqM-CO; Wed, 18 Oct 2023 16:48:16 +0200 Received: from schwarze by login-1.asta.kit.edu with local (Exim 4.94.2) (envelope-from ) id 1qt7qK-000h59-MF; Wed, 18 Oct 2023 16:48:16 +0200 Date: Wed, 18 Oct 2023 16:48:16 +0200 From: Ingo Schwarze To: Alejandro Colomar Cc: tech@mandoc.bsd.lv Subject: Re: mandoc -man -Thtml: unwanted line break after bullet (.IP) Message-ID: References: X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: Hi Alejandro, Ingo Schwarze wrote on Wed, Oct 18, 2023 at 02:04:46AM +0200: > 2. better document what mandoc.css is needed for, > what the embedded default CSS does and does not provide, > and that using a custom CSS file requires a high level of > proficiency in both the CSS and the mdoc(7) languages That part is now done, see the commit below. For easier access, i have also installed the updated file here: https://man.openbsd.org/mandoc.1#HTML_Output Yours, Ingo 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 tech+unsubscribe@mandoc.bsd.lv