===================================================================
RCS file: /cvs/docbook2mdoc/docbook2mdoc.1,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -p -r1.9 -r1.10
--- docbook2mdoc/docbook2mdoc.1	2019/03/17 13:53:42	1.9
+++ docbook2mdoc/docbook2mdoc.1	2019/04/09 15:23:51	1.10
@@ -1,4 +1,4 @@
-.\"	$Id: docbook2mdoc.1,v 1.9 2019/03/17 13:53:42 schwarze Exp $
+.\"	$Id: docbook2mdoc.1,v 1.10 2019/04/09 15:23:51 schwarze Exp $
 .\"
 .\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,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: March 17 2019 $
+.Dd $Mdocdate: April 9 2019 $
 .Dt DOCBOOK2MDOC 1
 .Os
 .Sh NAME
@@ -42,7 +42,9 @@ is taken to be standard input.
 The arguments are as follows:
 .Bl -tag -width Ds
 .It Fl W
-Output non-fatal warning messages.
+Report warnings on standard error output, and if any occur, raise the
+.Sx EXIT STATUS
+to at least 2.
 .El
 .Pp
 .Nm
@@ -56,7 +58,27 @@ The only non-DocBook constructs recognised are <xi:inc
 and <mml:*>, which is accepted and converted to
 .Xr eqn 7 .
 .Sh EXIT STATUS
-.Ex -std
+The
+.Nm
+utility exits with one of the following values:
+.Bl -tag -width 2n
+.It 0
+No error occurred, and if
+.Fl W
+was specified, no warning occurred either.
+.It 2
+At least one warning occurred, but no error, and
+.Fl W
+was specified.
+.It 3
+At least one parsing error occurred.
+.It 5
+Invalid command line arguments were specified.
+No input files have been read.
+.It 6
+Memory was exhausted.
+Parsing was aborted immediately.
+.El
 .Sh EXAMPLES
 To pipe a DocBook document
 .Pa foo.xml
@@ -65,6 +87,35 @@ through
 and a pager:
 .Pp
 .Dl $ docbook2mdoc foo.xml | mandoc -l
+.Sh DIAGNOSTICS
+Messages displayed by
+.Nm
+follow this format:
+.Pp
+.D1 Nm : Ar file : Ns Ar line : Ns Ar column : level : message
+.Pp
+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.
+.Pp
+Message levels have the following meanings:
+.Bl -tag -width warning
+.It Sy fatal
+An operating system error occurred, typically memory exhaustion,
+and parsing was aborted immediately.
+.It Sy error
+Indicates a risk of information loss or severe misformatting,
+for example caused by unknown elements or missing include files.
+.It Sy warning
+Indicates a risk that the information shown or its formatting
+may mismatch the author's intent in minor ways.
+For example, mismatched or missing end tags are classified as warnings.
+.El
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr eqn 7 ,