===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.255
retrieving revision 1.267
diff -u -p -r1.255 -r1.267
--- mandoc/mandoc.1	2022/02/08 18:30:22	1.255
+++ mandoc/mandoc.1	2023/11/13 19:13:01	1.267
@@ -1,6 +1,6 @@
-.\" $OpenBSD: mandoc.1,v 1.255 2022/02/08 18:30:22 schwarze Exp $
+.\" $Id: mandoc.1,v 1.267 2023/11/13 19:13:01 schwarze Exp $
 .\"
-.\" Copyright (c) 2012, 2014-2021 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2012, 2014-2023 Ingo Schwarze <schwarze@openbsd.org>
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
@@ -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: February 8 2022 $
+.Dd $Mdocdate: November 13 2023 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -287,10 +287,7 @@ arguments are accepted:
 .It Cm indent Ns = Ns Ar indent
 The left margin for normal text is set to
 .Ar indent
-blank characters instead of the default of five for
-.Xr mdoc 7
-and seven for
-.Xr man 7 .
+blank characters instead of the default of five.
 Increasing this is not recommended; it may result in degraded formatting,
 for example overfull lines or ugly line breaks.
 When output is to a pager on a terminal that is less than 66 columns
@@ -302,8 +299,7 @@ input files in
 .Xr mdoc 7
 output style.
 This prints the operating system name rather than the page title
-on the right side of the footer line, and it implies
-.Fl O Cm indent Ns =5 .
+on the right side of the footer line.
 One useful application is for checking that
 .Fl T Cm man
 output formats in the same way as the
@@ -342,21 +338,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 +391,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 .
@@ -487,10 +511,10 @@ Use
 to translate
 .Xr mdoc 7
 input to the markdown format conforming to
-.Lk http://daringfireball.net/projects/markdown/syntax.text\
+.Lk https://daringfireball.net/projects/markdown/syntax.text\
  "John Gruber's 2004 specification" .
 The output also almost conforms to the
-.Lk http://commonmark.org/ CommonMark
+.Lk https://commonmark.org/ CommonMark
 specification.
 .Pp
 The character set used for the markdown output is ASCII.
@@ -739,7 +763,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 +790,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 +810,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
@@ -1269,9 +1291,11 @@ The same standard section title occurs more than once.
 A standard section header occurs in a section of the manual
 where it normally isn't useful.
 .It Sy "cross reference to self"
-.Pq mdoc
+.Pq mdoc , man
 An
 .Ic \&Xr
+or
+.Ic \&MR
 macro refers to a name and section matching the section of the present
 manual page and a name mentioned in an
 .Ic \&Nm
@@ -1474,10 +1498,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
@@ -1592,12 +1614,16 @@ macro is immediately followed by an
 macro on the next input line.
 Such an empty block does not produce any output.
 .It Sy "missing section argument"
-.Pq mdoc
+.Pq mdoc , man
 An
 .Ic \&Xr
+or
+.Ic \&MR
 macro lacks its second, section number argument.
-The first argument, i.e. the name, is printed, but without subsequent
-parentheses.
+The first argument, i.e. the name, is printed, but without a section number.
+In the case of
+.Ic \&Xr ,
+the parentheses are also omitted.
 .It Sy "missing -std argument, adding it"
 .Pq mdoc
 An
@@ -1754,6 +1780,15 @@ request or a
 layout modifier has an unknown
 .Ar font
 argument.
+.It Sy "ignoring distance argument"
+.Pq roff
+In addition to the margin character, an
+.Ic \&mc
+request has a second argument supposed to represent a distance, but the
+.Nm
+implementation of
+.Ic \&mc
+always ignores the second argument.
 .It Sy "odd number of characters in request"
 .Pq roff
 A
@@ -1788,23 +1823,10 @@ it is hard to predict which tab stop position the tab 
 .Pq mdoc
 A new sentence starts in the middle of a text line.
 Start it on a new input line to help formatters produce correct spacing.
-.It Sy "invalid escape sequence"
+.It Sy "invalid escape sequence argument"
 .Pq roff
-An escape sequence has an invalid opening argument delimiter, lacks the
-closing argument delimiter, the argument is of an invalid form, or it is
-a character escape sequence with an invalid name.
-If the argument is incomplete,
-.Ic \e*
-and
-.Ic \en
-expand to an empty string,
-.Ic \eB
-to the digit
-.Sq 0 ,
-and
-.Ic \ew
-to the length of the incomplete argument.
-All other invalid escape sequences are ignored.
+The argument of an escape sequence is of an invalid form.
+Invalid escape sequences are ignored.
 .It Sy "undefined escape, printing literally"
 .Pq roff
 In an escape sequence, the first character
@@ -2082,6 +2104,13 @@ and expands to the empty string.
 .Pq roff
 The argument of the escape sequence \e$ is not a digit;
 the escape sequence expands to the empty string.
+.It Sy "negative argument, using 0"
+.Pq roff
+A
+.Ic \&shift
+request has a negative argument
+or an argument that is negative due to integer overflow.
+Macro argument numbering remains unchanged.
 .It Sy "NOT IMPLEMENTED: Bd -file"
 .Pq mdoc
 For security reasons, the
@@ -2117,11 +2146,20 @@ The first argument of a
 request is neither a single ASCII character
 nor a single character escape sequence.
 The request is ignored including all its arguments.
+.It Sy "skipping unusable escape sequence"
+.Pq roff
+The first argument of an
+.Ic mc
+request is neither a single ASCII character
+nor a single character escape sequence.
+All arguments are ignored and printing of a margin character is disabled.
 .It Sy "missing manual name, using \(dq\(dq"
-.Pq mdoc
+.Pq mdoc , man
 The first call to
 .Ic \&Nm ,
-or any call in the NAME section, lacks the required argument.
+or any call in the NAME section, lacks the required argument, or
+.Ic \&MR
+is called without any argument.
 .It Sy "uname(3) system call failed, using UNKNOWN"
 .Pq mdoc
 The
@@ -2249,6 +2287,8 @@ or a request of the
 family with more than two arguments
 .It
 .Ic \&Dt
+or
+.Ic \&MR
 with more than three arguments
 .It
 .Ic \&TH
@@ -2261,6 +2301,60 @@ or
 with invalid arguments
 .El
 The excess arguments are ignored.
+.El
+.Ss "Errors related to escape sequences"
+.Bl -ohang
+.It Sy "incomplete escape sequence"
+.Pq roff
+The end of the input line is encountered
+while parsing the argument of an escape sequence.
+In this case,
+.Ic \e*
+and
+.Ic \en
+expand to an empty string,
+.Ic \eB
+to the digit
+.Sq 0 ,
+and
+.Ic \ew
+to the length of the incomplete argument.
+All other incomplete escape sequences are ignored.
+.It Sy "invalid special character"
+.Pq roff
+A special character escape sequence is invalid,
+for example a Unicode sequence pointing to a surrogate
+or beyond the Unicode range, a \e[char...] escape sequence
+representing a control character or pointing beyond the
+.Vt unsigned char
+range, or an invalid variable-length form
+of a single-byte character escape sequence, for example writing
+.Qq \e[e]
+or
+.Qq \e[~]
+instead of
+.Qq \ee
+or
+.Qq \e~ ,
+respectively.
+The escape sequence is ignored.
+.It Sy "unknown special character"
+.Pq roff
+The name given in a special character escape sequence is not known to
+.Nm .
+The escape sequence is ignored.
+.It Sy "invalid escape argument delimiter"
+.Pq roff
+An escape sequence that expects a numerical argument
+attempts to employ one of the characters
+.Qq " %&()*+-./0123456789:<=>"
+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 characters can be used as argument delimiters,
+using the apostrophe-quote character
+.Pq Sq \(aq
+is recommended for readability and robustness.
 .El
 .Ss Unsupported features
 .Bl -ohang