===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.260
retrieving revision 1.265
diff -u -p -r1.260 -r1.265
--- mandoc/mandoc.1	2022/06/07 09:54:40	1.260
+++ mandoc/mandoc.1	2023/10/18 14:34:29	1.265
@@ -1,4 +1,4 @@
-.\" $Id: mandoc.1,v 1.260 2022/06/07 09:54:40 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: June 7 2022 $
+.Dd $Mdocdate: October 18 2023 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -342,21 +342,9 @@ and may exceed the output width.
 Output produced by
 .Fl T Cm html
 conforms to HTML5 using optional self-closing tags.
-Default styles use only CSS1.
 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
@@ -407,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 .
@@ -739,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
@@ -766,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
@@ -786,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
@@ -1474,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
@@ -2321,7 +2345,7 @@ attempts to employ one of the characters
 as an argument delimiter.
 The escape sequence is ignored including the invalid opening delimiter
 and the rest of the argument may appear as output text.
-While various charcters can be used as argument delimiters,
+While various characters can be used as argument delimiters,
 using the apostrophe-quote character
 .Pq Sq \(aq
 is recommended for readability and robustness.