===================================================================
RCS file: /cvs/docbook2mdoc/docbook2mdoc.1,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -p -r1.10 -r1.11
--- docbook2mdoc/docbook2mdoc.1	2019/04/09 15:23:51	1.10
+++ docbook2mdoc/docbook2mdoc.1	2019/04/09 16:57:29	1.11
@@ -1,6 +1,7 @@
-.\"	$Id: docbook2mdoc.1,v 1.10 2019/04/09 15:23:51 schwarze Exp $
+.\" $Id: docbook2mdoc.1,v 1.11 2019/04/09 16:57:29 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
@@ -19,7 +20,7 @@
 .Os
 .Sh NAME
 .Nm docbook2mdoc
-.Nd Convert DocBook refentry to mdoc
+.Nd convert DocBook to mdoc
 .Sh SYNOPSIS
 .Nm docbook2mdoc
 .Op Fl W
@@ -27,17 +28,17 @@
 .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
@@ -47,16 +48,40 @@ Report warnings on standard error output, and if any o
 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 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 +148,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