===================================================================
RCS file: /cvs/docbook2mdoc/docbook2mdoc.1,v
retrieving revision 1.11
retrieving revision 1.17
diff -u -p -r1.11 -r1.17
--- docbook2mdoc/docbook2mdoc.1	2019/04/09 16:57:29	1.11
+++ docbook2mdoc/docbook2mdoc.1	2019/05/02 12:40:42	1.17
@@ -1,4 +1,4 @@
-.\" $Id: docbook2mdoc.1,v 1.11 2019/04/09 16:57:29 schwarze Exp $
+.\" $Id: docbook2mdoc.1,v 1.17 2019/05/02 12:40:42 schwarze Exp $
 .\"
 .\" Copyright (c) 2014 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2019 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: April 9 2019 $
+.Dd $Mdocdate: May 2 2019 $
 .Dt DOCBOOK2MDOC 1
 .Os
 .Sh NAME
@@ -24,6 +24,8 @@
 .Sh SYNOPSIS
 .Nm docbook2mdoc
 .Op Fl W
+.Op Fl s Ar section
+.Op Fl T Cm mdoc | tree | lint
 .Op Ar file
 .Sh DESCRIPTION
 The
@@ -36,12 +38,52 @@ and
 .Xr eqn 7 .
 If
 .Ar file
-is
-.Sq Cm \-
-or omitted, standard input is used.
+is 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 s
+Specify the manual page
+.Ar section
+to be used as the second argument of the
+.Ic \&Dt
+macro.
+Defaults to the content of the first
+.Eo < Ic manvolnum Ec >
+element in the first
+.Eo < Ic refmeta Ec >
+block, if any, or to
+.Qq 1
+otherwise.
+.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
+An asterisk if the node starts a new text line,
+or 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
@@ -72,6 +114,16 @@ Internal subset declaration to define an XML entity.
 .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
@@ -151,13 +203,3 @@ was written by
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 and
 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
-.Sh CAVEATS
-The
-.Nm
-utility is experimental.
-Many elements are not recognized yet.
-.Pp
-The output
-.Xr mdoc 7
-could be much nicer: trailing spaces, superfluous space removal,
-new-line new-sentence, and other niceties are not used.