From: Ingo Schwarze <schwarze@usta.de>
To: Alejandro Colomar <alx@kernel.org>
Cc: tech@mandoc.bsd.lv
Subject: Re: mandoc -man -Thtml: unwanted line break after bullet (.IP)
Date: Wed, 18 Oct 2023 16:48:16 +0200 [thread overview]
Message-ID: <ZS/wMPTjK/zUJkUA@asta-kit.de> (raw)
In-Reply-To: <ZS8hHsrCp9Bn2/tt@asta-kit.de>
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 <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 tech+unsubscribe@mandoc.bsd.lv
next prev parent reply other threads:[~2023-10-18 14:48 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-10-16 13:17 Alejandro Colomar
2023-10-16 14:52 ` Ingo Schwarze
2023-10-16 15:20 ` Jan Stary
2023-10-16 15:43 ` Ingo Schwarze
2023-10-16 16:03 ` Ingo Schwarze
2023-10-16 17:10 ` Alejandro Colomar
2023-10-16 17:16 ` Alejandro Colomar
2023-10-16 17:28 ` Alejandro Colomar
2023-10-17 19:02 ` Ingo Schwarze
2023-10-17 21:39 ` Alejandro Colomar
2023-10-18 0:04 ` Ingo Schwarze
2023-10-18 11:32 ` Alejandro Colomar
2023-10-18 14:48 ` Ingo Schwarze [this message]
2023-10-18 14:56 ` Alejandro Colomar
2023-10-18 16:20 ` Ingo Schwarze
2023-10-18 18:52 ` Alejandro Colomar
2023-10-19 11:59 ` Ingo Schwarze
2023-10-19 12:48 ` Alejandro Colomar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ZS/wMPTjK/zUJkUA@asta-kit.de \
--to=schwarze@usta.de \
--cc=alx@kernel.org \
--cc=tech@mandoc.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).