===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.262
retrieving revision 1.265
diff -u -p -r1.262 -r1.265
--- mandoc/mandoc.1	2022/07/03 14:36:00	1.262
+++ mandoc/mandoc.1	2023/10/18 14:34:29	1.265
@@ -1,4 +1,4 @@
-.\" $Id: mandoc.1,v 1.262 2022/07/03 14:36:00 schwarze Exp $
+.\" $Id: mandoc.1,v 1.265 2023/10/18 14:34:29 schwarze Exp $
 .\"
 .\" Copyright (c) 2012, 2014-2022 Ingo Schwarze <schwarze@openbsd.org>
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
@@ -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: July 3 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
@@ -765,7 +794,7 @@ Messages displayed by
 follow this format:
 .Bd -ragged -offset indent
 .Nm :
-.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments
+.Ar file : Ns Ar line : Ns Ar column : level : message : macro argument ...
 .Pq Ar os
 .Ed
 .Pp
@@ -785,9 +814,7 @@ and
 strings are explained below.
 The name of the
 .Ar macro
-triggering the message and its
-.Ar arguments
-are omitted where meaningless.
+triggering the message and its arguments are omitted where meaningless.
 The
 .Ar os
 operating system specifier is omitted for messages that are relevant
@@ -1473,10 +1500,8 @@ A
 .Ic \&Bl ,
 .Ic \&D1 ,
 .Ic \&Dl ,
-.Ic \&MT ,
-.Ic \&RS ,
 or
-.Ic \&UR
+.Ic \&RS
 block contains nothing in its body and will produce no output.
 .It Sy "empty argument, using 0n"
 .Pq mdoc