===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.127
retrieving revision 1.132
diff -u -p -r1.127 -r1.132
--- mandoc/mandoc.1	2014/11/30 05:29:00	1.127
+++ mandoc/mandoc.1	2015/01/15 04:26:40	1.132
@@ -1,7 +1,7 @@
-.\"	$Id: mandoc.1,v 1.127 2014/11/30 05:29:00 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.132 2015/01/15 04:26:40 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -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: November 30 2014 $
+.Dd $Mdocdate: January 15 2015 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -49,7 +49,7 @@ or
 text from stdin, implying
 .Fl m Ns Cm andoc ,
 and produces
-.Fl T Ns Cm ascii
+.Fl T Ns Cm locale
 output.
 .Pp
 The options are as follows:
@@ -85,6 +85,9 @@ Override the default operating system
 for the
 .Xr mdoc 7
 .Sq \&Os
+and for the
+.Xr man 7
+.Sq \&TH
 macro.
 .It Fl h
 Display only the SYNOPSIS lines.
@@ -146,7 +149,7 @@ See
 .Sx Output Formats
 for available formats.
 Defaults to
-.Fl T Ns Cm ascii .
+.Fl T Ns Cm locale .
 .It Fl V
 Print version and exit.
 .It Fl W Ns Ar level
@@ -156,15 +159,15 @@ to be reported on the standard error output and to aff
 The
 .Ar level
 can be
-.Cm warning ,
-.Cm error ,
+.Cm warning
 or
-.Cm fatal .
-The default is
-.Fl W Ns Cm fatal ;
-.Fl W Ns Cm all
+.Cm error ;
+.Cm all
 is an alias for
-.Fl W Ns Cm warning .
+.Cm warning .
+By default,
+.Nm
+is silent.
 See
 .Sx EXIT STATUS
 and
@@ -255,7 +258,6 @@ arguments, which correspond to output modes:
 .Bl -tag -width "-Tlocale"
 .It Fl T Ns Cm ascii
 Produce 7-bit ASCII output.
-This is the default.
 See
 .Sx ASCII Output .
 .It Fl T Ns Cm html
@@ -268,6 +270,7 @@ Implies
 .Fl W Ns Cm warning .
 .It Fl T Ns Cm locale
 Encode output using the current locale.
+This is the default.
 See
 .Sx Locale Output .
 .It Fl T Ns Cm man
@@ -299,8 +302,8 @@ If multiple input files are specified, these will be p
 corresponding filter in-order.
 .Ss ASCII Output
 Output produced by
-.Fl T Ns Cm ascii ,
-which is the default, is rendered in standard 7-bit ASCII documented in
+.Fl T Ns Cm ascii
+is rendered in standard 7-bit ASCII documented in
 .Xr ascii 7 .
 .Pp
 Font styles are applied by using back-spaced encoding such that an
@@ -413,6 +416,8 @@ relative URI.
 .Ss Locale Output
 Locale-depending output encoding is triggered with
 .Fl T Ns Cm locale .
+This is the default.
+.Pp
 This option is not available on all systems: systems without locale
 support, or those whose internal representation is not natively UCS-4,
 will fall back to
@@ -527,19 +532,17 @@ At least one warning occurred, but no error, and
 .Fl W Ns Cm warning
 was specified.
 .It 3
-At least one parsing error occurred, but no fatal error, and
+At least one parsing error occurred, and
 .Fl W Ns Cm error
 or
 .Fl W Ns Cm warning
 was specified.
-.It 4
-A fatal parsing error occurred.
 .It 5
 Invalid command line arguments were specified.
 No input files have been read.
 .It 6
-An operating system error occurred, for example memory exhaustion or an
-error accessing input files.
+An operating system error occurred, for example exhaustion
+of memory, file descriptors, or process table entries.
 Such errors cause
 .Nm
 to exit at once, possibly in the middle of parsing or formatting a file.
@@ -598,12 +601,6 @@ fields.
 .Pp
 Message levels have the following meanings:
 .Bl -tag -width "warning"
-.It Cm syserr
-Opening or reading an input file failed, so the parser cannot
-even be started and no output is produced from that input file.
-.It Cm fatal
-The parser is unable to parse a given input file at all.
-No formatted output is produced from that input file.
 .It Cm error
 An input file contains syntax that cannot be safely interpreted,
 either because it is invalid or because
@@ -614,6 +611,12 @@ the parser is able to continue, and the error does not
 generation of formatted output, but typically, preparing that
 output involves information loss, broken document structure
 or unintended formatting.
+.Pp
+Non-existent or unreadable input files are also reported on the
+.Cm error
+level.
+In that case, the parser cannot even be started and no output
+is produced from those input files.
 .It Cm warning
 An input file uses obsolete, discouraged or non-portable syntax.
 All the same, the meaning of the input is unambiguous and a correct
@@ -627,7 +630,8 @@ Messages of the
 .Cm warning
 and
 .Cm error
-levels are hidden unless their level, or a lower level, is requested using a
+levels except those about non-existent or unreadable input files
+are hidden unless their level, or a lower level, is requested using a
 .Fl W
 option or
 .Fl T Ns Cm lint
@@ -1264,9 +1268,18 @@ keeps the code more readable.
 .It "ignore data in cell"
 .It "data block still open"
 .It "ignoring extra data cells"
+.It "ignoring macro in table"
 .El
 .Ss "Errors related to roff, mdoc, and man code"
 .Bl -ohang
+.It Sy "input too large"
+.Pq mdoc , man
+Currently,
+.Nm
+cannot handle input files larger than its arbitrary size limit
+of 2^31 bytes (2 Gigabytes).
+Since useful manuals are always small, this is not a problem in practice.
+Parsing is aborted as soon as the condition is detected.
 .It Sy "input stack limit exceeded, infinite loop?"
 .Pq roff
 Explicit recursion limits are implemented for the following features,
@@ -1455,6 +1468,29 @@ or
 .Ic \&gsize
 statement has a non-numeric or negative argument or no argument at all.
 The invalid request or statement is ignored.
+.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
+.Pq roff
+For security reasons,
+.Nm
+allows
+.Ic \&so
+file inclusion requests only with relative paths
+and only without ascending to any parent directory.
+By requesting the inclusion of a sensitive file, a malicious document
+might otherwise trick a privileged user into inadvertently displaying
+the file on the screen, revealing the file content to bystanders.
+.Nm
+only shows the path as it appears behind
+.Ic \&so .
+.It Sy ".so request failed"
+.Pq roff
+Servicing a
+.Ic \&so
+request requires reading an external file, but the file could not be
+opened.
+.Nm
+only shows the path as it appears behind
+.Ic \&so .
 .It Sy "skipping all arguments"
 .Pq mdoc , man , eqn , roff
 An
@@ -1493,44 +1529,6 @@ macro is invoked with more than one argument, or a req
 .Ic \&de
 family is invoked with more than two arguments.
 The excess arguments are ignored.
-.El
-.Ss FATAL errors
-.Bl -ohang
-.It Sy "input too large"
-.Pq mdoc , man
-Currently,
-.Nm
-cannot handle input files larger than its arbitrary size limit
-of 2^31 bytes (2 Gigabytes).
-Since useful manuals are always small, this is not a problem in practice.
-Parsing is aborted as soon as the condition is detected.
-.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
-.Pq roff
-For security reasons,
-.Nm
-allows
-.Ic \&so
-file inclusion requests only with relative paths
-and only without ascending to any parent directory.
-By requesting the inclusion of a sensitive file, a malicious document
-might otherwise trick a privileged user into inadvertently displaying
-the file on the screen, revealing the file content to bystanders.
-The parser exits immediately.
-.It Sy ".so request failed"
-.Pq roff
-Servicing a
-.Ic \&so
-request requires reading an external file.
-While trying to do so, an
-.Xr open 2 ,
-.Xr stat 2 ,
-or
-.Xr read 2
-system call failed.
-The parser exits immediately.
-Before showing this message,
-.Nm
-always shows another message explaining why the system call failed.
 .El
 .Sh COMPATIBILITY
 This section summarises