===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.229
retrieving revision 1.234
diff -u -p -r1.229 -r1.234
--- mandoc/mandoc.1	2018/10/02 12:33:37	1.229
+++ mandoc/mandoc.1	2018/12/24 23:37:22	1.234
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.229 2018/10/02 12:33:37 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.234 2018/12/24 23:37:22 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014-2018 Ingo Schwarze <schwarze@openbsd.org>
@@ -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: October 2 2018 $
+.Dd $Mdocdate: December 24 2018 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -290,6 +290,18 @@ One useful application is for checking that
 output formats in the same way as the
 .Xr mdoc 7
 source it was generated from.
+.It Cm tag Ns Op = Ns Ar term
+If the formatted manual page is opened in a pager,
+go to the definition of the
+.Ar term
+rather than showing the manual page from the beginning.
+If no
+.Ar term
+is specified, reuse the first command line argument that is not a
+.Ar section
+number.
+This is useful when it is the name of a manual page,
+in particular the name of a library function.
 .It Cm width Ns = Ns Ar width
 The output width is set to
 .Ar width
@@ -308,9 +320,9 @@ Equations rendered from
 .Xr eqn 7
 blocks use MathML.
 .Pp
-The
-.Pa mandoc.css
-file documents style-sheet classes available for customising output.
+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
@@ -371,6 +383,9 @@ The file
 is used for an external style-sheet.
 This must be a valid absolute or
 relative URI.
+.It Cm toc
+If an input file contains at least two non-standard sections,
+print a table of contents near the beginning of the output.
 .El
 .Ss Locale Output
 By default,
@@ -671,10 +686,10 @@ To page manuals to the terminal:
 .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
 .Pp
 To produce HTML manuals with
-.Pa mandoc.css
+.Pa /usr/share/misc/mandoc.css
 as the style-sheet:
 .Pp
-.Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html
+.Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html
 .Pp
 To check over a large set of manuals:
 .Pp
@@ -682,7 +697,7 @@ To check over a large set of manuals:
 .Pp
 To produce a series of PostScript manuals for A4 paper:
 .Pp
-.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps
+.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 > manuals.ps
 .Pp
 Convert a modern
 .Xr mdoc 7
@@ -692,20 +707,36 @@ format, for use on systems lacking an
 .Xr mdoc 7
 parser:
 .Pp
-.Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
+.Dl $ mandoc \-T man foo.mdoc > foo.man
 .Sh DIAGNOSTICS
 Messages displayed by
 .Nm
 follow this format:
 .Bd -ragged -offset indent
 .Nm :
-.Ar file : Ns Ar line : Ns Ar column : level : message : macro args
+.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments
 .Pq Ar os
 .Ed
 .Pp
-Line and column numbers start at 1.
+The first three fields identify the
+.Ar file
+name,
+.Ar line
+number, and
+.Ar column
+number of the input file where the message was triggered.
+The line and column numbers start at 1.
 Both are omitted for messages referring to an input file as a whole.
-Macro names and arguments are omitted where meaningless.
+All
+.Ar level
+and
+.Ar message
+strings are explained below.
+The name of the
+.Ar macro
+triggering the message and its
+.Ar arguments
+are omitted where meaningless.
 The
 .Ar os
 operating system specifier is omitted for messages that are relevant
@@ -1661,7 +1692,8 @@ Start it on a new input line to help formatters produc
 .It Sy "invalid escape sequence"
 .Pq roff
 An escape sequence has an invalid opening argument delimiter, lacks the
-closing argument delimiter, or the argument has too few characters.
+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
@@ -1674,6 +1706,12 @@ and
 .Ic \ew
 to the length of the incomplete argument.
 All other invalid escape sequences are ignored.
+.It Sy "undefined escape, printing literally"
+.Pq roff
+In an escape sequence, the first character
+right after the leading backslash is invalid.
+That character is printed literally,
+which is equivalent to ignoring the backslash.
 .It Sy "undefined string, using \(dq\(dq"
 .Pq roff
 If a string is used without being defined before,
@@ -2139,6 +2177,13 @@ implementations but not by
 .Nm
 was found in an input file.
 It is replaced by a question mark.
+.It Sy "unsupported escape sequence"
+.Pq roff
+An input file contains an escape sequence supported by GNU troff
+or Heirloom troff but not by
+.Nm ,
+and it is likely that this will cause information loss
+or considerable misformatting.
 .It Sy "unsupported roff request"
 .Pq roff
 An input file contains a