===================================================================
RCS file: /cvs/docbook2mdoc/docbook2mdoc.1,v
retrieving revision 1.10
retrieving revision 1.13
diff -u -p -r1.10 -r1.13
--- docbook2mdoc/docbook2mdoc.1	2019/04/09 15:23:51	1.10
+++ docbook2mdoc/docbook2mdoc.1	2019/04/23 15:47:23	1.13
@@ -1,6 +1,7 @@
-.\"	$Id: docbook2mdoc.1,v 1.10 2019/04/09 15:23:51 schwarze Exp $
+.\" $Id: docbook2mdoc.1,v 1.13 2019/04/23 15:47:23 schwarze Exp $
 .\"
 .\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2019 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
@@ -14,49 +15,112 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: April 9 2019 $
+.Dd $Mdocdate: April 23 2019 $
 .Dt DOCBOOK2MDOC 1
 .Os
 .Sh NAME
 .Nm docbook2mdoc
-.Nd Convert DocBook refentry to mdoc
+.Nd convert DocBook to mdoc
 .Sh SYNOPSIS
 .Nm docbook2mdoc
 .Op Fl W
+.Op Fl T Cm mdoc | tree | lint
 .Op Ar file
 .Sh DESCRIPTION
 The
 .Nm
-utility reads
+utility reads DocBook input from a
 .Ar file
-and generates
+and translates it to
 .Xr mdoc 7
 and
-.Xr eqn 7
-from the <refentry> section of DocBook source, ignoring other sections.
-If unspecified or
-.Sq Cm \- ,
+.Xr eqn 7 .
+If
 .Ar file
-is taken to be standard input.
+is
+.Sq Cm \-
+or omitted, standard input is used.
 .Pp
-The arguments are as follows:
-.Bl -tag -width Ds
+The options are as follows:
+.Bl -tag -width 2n
+.It Fl T
+Select the output mode.
+The following arguments are supported:
+.Bl -tag -width 4n
+.It Cm mdoc
+Translate the input to
+.Xr mdoc 7 .
+This is the default.
+.It Cm tree
+Dump a human-readable representation of the parse tree.
+Each output line shows one tree node.
+Child nodes are indented with respect to their parent node.
+The columns are:
+.Bl -enum -width 2n
+.It
+A hyphen if the node follows the previous node
+without intervening whitespace.
+.It
+The node type.
+.It
+For text nodes, the text contents.
+For other nodes, the attributes, if any.
+.El
+.It Cm lint
+Do not produce any output, only error messages.
+Can be combined with
+.Fl W .
+.El
 .It Fl W
 Report warnings on standard error output, and if any occur, raise the
 .Sx EXIT STATUS
 to at least 2.
 .El
 .Pp
-.Nm
-supports only well-formed XML DocBook V4.x until V5.1.
-Some earlier DocBook constructs are accepted as well.
-SGML DocBook documents may be parsed unless they contain SGML-specific
-constructs, such as empty end tags
-.Li </> .
-The only non-DocBook constructs recognised are <xi:include\ />
-.Pq which is discarded
-and <mml:*>, which is accepted and converted to
+A subset of DocBook 5.1 elements are recognized,
+as well as some elements from earlier versions.
+The parser is optimized for robustness even on invalid input,
+always producing some output on a best-effort basis.
+Input is not required to be well-formed, nor to adhere to DocBook
+syntactic or semantic requirements.
+.Pp
+Unknown elements are ignored in the sense that they do not affect
+formatting and only their content is rendered.
+Unknown attributes are silently discarded.
+.Pp
+In addition to DocBook elements, the following constructs are handled:
+.Bl -tag -width Ds
+.It Eo <!
+.Ic DOCTYPE No ...
+.Eo "[ <!" Ic ENTITY Ar name Qo Ar definition Qc Ec "> ]"
+.Ec >
+Internal subset declaration to define an XML entity.
+.It Eo <!
+.Ic DOCTYPE No ...
+.Eo "[ <!" Ic ENTITY Ar name Cm SYSTEM Qo Ar file Qc Ec "> ]"
+.Ec >
+Internal subset declaration to define an XML entity using an external
+.Ar file .
+.It Eo <!
+.Ic DOCTYPE No ...
+.Bo
+.Eo " <!" Ic ENTITY No % Ar name Cm SYSTEM Qo Ar file Qc Ec >
+.Pf % Ar name No \&
+.Bc
+.Ec >
+Internal subset declaration to include an external
+.Ar file
+that is supposed to contain entity declarations.
+.It Eo < Ic mml : Ns ... Ec >
+Elements from the MathML namespace.
+These are translated to
 .Xr eqn 7 .
+.It Eo <
+.Ic xi : Ns Ic include No ...
+.Cm href Ns = Ns Qq Ar file
+.Ec >
+Include an external DocBook file into the current document.
+.El
 .Sh EXIT STATUS
 The
 .Nm
@@ -123,12 +187,14 @@ For example, mismatched or missing end tags are classi
 .Sh AUTHORS
 .Nm
 was written by
-.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
+and
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
 .Sh CAVEATS
 The
 .Nm
 utility is experimental.
-As such, only a modest subset of the <refentry> domain is accepted.
+Many elements are not recognized yet.
 .Pp
 The output
 .Xr mdoc 7