===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.247
retrieving revision 1.263
diff -u -p -r1.247 -r1.263
--- mandoc/mandoc.1	2020/08/27 15:55:34	1.247
+++ mandoc/mandoc.1	2022/08/02 12:02:28	1.263
@@ -1,6 +1,6 @@
-.\" $OpenBSD: mandoc.1,v 1.247 2020/08/27 15:55:34 schwarze Exp $
+.\" $Id: mandoc.1,v 1.263 2022/08/02 12:02:28 schwarze Exp $
 .\"
-.\" Copyright (c) 2012, 2014-2020 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2012, 2014-2022 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: August 27 2020 $
+.Dd $Mdocdate: August 2 2022 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -301,8 +301,8 @@ Format
 input files in
 .Xr mdoc 7
 output style.
-Specifically, this suppresses the two additional blank lines near the
-top and the bottom of each page, and it implies
+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 .
 One useful application is for checking that
 .Fl T Cm man
@@ -342,7 +342,6 @@ 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.
@@ -487,10 +486,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.
@@ -735,7 +734,7 @@ output mode implies
 .Sh EXAMPLES
 To page manuals to the terminal:
 .Pp
-.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
+.Dl $ mandoc -a mandoc.1 man.1 apropos.1 makewhatis.8
 .Pp
 To produce HTML manuals with
 .Pa /usr/share/misc/mandoc.css
@@ -835,7 +834,7 @@ message levels, the
 .Cm style
 level tries to reduce the probability that issues go unnoticed,
 so it may occasionally issue bogus suggestions.
-Please use your good judgement to decide whether any particular
+Use your judgement to decide whether any particular
 .Cm style
 suggestion really justifies a change to the input file.
 .It Cm base
@@ -922,14 +921,6 @@ generated by CVS
 or
 .Ic NetBSD
 keyword substitution as conventionally used in these operating systems.
-.It Sy "referenced manual not found"
-.Pq mdoc
-An
-.Ic \&Xr
-macro references a manual page that is not found in the base system.
-The path to look for base system manuals is configurable at compile
-time and defaults to
-.Pa /usr/share/man : /usr/X11R6/man .
 .El
 .Ss Style suggestions
 .Bl -ohang
@@ -1016,6 +1007,35 @@ list contains two consecutive
 entries describing the same
 .Ic \&Er
 number.
+.It Sy "referenced manual not found"
+.Pq mdoc
+An
+.Ic \&Xr
+macro references a manual page that was not found.
+When running with
+.Fl W Cm base ,
+the search is restricted to the base system, by default to
+.Pa /usr/share/man : Ns Pa /usr/X11R6/man .
+This path can be configured at compile time using the
+.Dv MANPATH_BASE
+preprocessor macro.
+When running with
+.Fl W Cm style ,
+the search is done along the full search path as described in the
+.Xr man 1
+manual page, respecting the
+.Fl m
+and
+.Fl M
+command line options, the
+.Ev MANPATH
+environment variable, the
+.Xr man.conf 5
+file and falling back to the default of
+.Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man ,
+also configurable at compile time using the
+.Dv MANPATH_DEFAULT
+preprocessor macro.
 .It Sy "trailing delimiter"
 .Pq mdoc
 The last argument of an
@@ -1045,6 +1065,9 @@ An
 request occurs even though the document already switched to no-fill mode
 and did not switch back to fill mode yet.
 It has no effect.
+.It Sy "input text line longer than 80 bytes"
+Consider breaking the input text line
+at one of the blank characters before column 80.
 .It Sy "verbatim \(dq--\(dq, maybe consider using \e(em"
 .Pq mdoc
 Even though the ASCII output device renders an em-dash as
@@ -1450,10 +1473,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
@@ -1730,6 +1751,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
@@ -1764,23 +1794,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
@@ -1850,6 +1867,10 @@ The invalid character is discarded.
 A table layout specification contains an opening parenthesis,
 but no matching closing parenthesis.
 The rest of the input line, starting from the parenthesis, has no effect.
+.It Sy "ignoring excessive spacing in tbl layout"
+.Pq tbl
+A spacing modifier in a table layout is unreasonably large.
+The default spacing of 3n is used instead.
 .It Sy "tbl without any data cells"
 .Pq tbl
 A table does not contain any data cells.
@@ -2054,6 +2075,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
@@ -2089,6 +2117,13 @@ 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
 The first call to
@@ -2234,6 +2269,60 @@ 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
 .It Sy "input too large"
@@ -2286,6 +2375,26 @@ or
 macro or of an undefined macro.
 The macro is ignored, and its arguments are handled
 as if they were a text line.
+.It Sy "skipping tbl in -Tman mode"
+.Pq mdoc , tbl
+An input file contains the
+.Ic \&TS
+macro.
+This message is only generated in
+.Fl T Cm man
+output mode, where
+.Xr tbl 7
+input is not supported.
+.It Sy "skipping eqn in -Tman mode"
+.Pq mdoc , eqn
+An input file contains the
+.Ic \&EQ
+macro.
+This message is only generated in
+.Fl T Cm man
+output mode, where
+.Xr eqn 7
+input is not supported.
 .El
 .Ss Bad command line arguments
 .Bl -ohang
@@ -2323,6 +2432,14 @@ The
 .Fl O Cm tag
 option was specified but the tag was not found in any of the displayed
 manual pages.
+.It Sy "\-Tmarkdown unsupported for man(7) input"
+.Pq man
+The
+.Fl T Cm markdown
+option was specified but an input file uses the
+.Xr man 7
+language.
+No output is produced for that input file.
 .El
 .Sh SEE ALSO
 .Xr apropos 1 ,