* docbook2mdoc: update content in many respects
@ 2019-04-09 16:57 schwarze
0 siblings, 0 replies; only message in thread
From: schwarze @ 2019-04-09 16:57 UTC (permalink / raw)
To: source
Log Message:
-----------
update content in many respects
Modified Files:
--------------
docbook2mdoc:
docbook2mdoc.1
Revision Data
-------------
Index: docbook2mdoc.1
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/docbook2mdoc.1,v
retrieving revision 1.10
retrieving revision 1.11
diff -Ldocbook2mdoc.1 -Ldocbook2mdoc.1 -u -p -r1.10 -r1.11
--- docbook2mdoc.1
+++ docbook2mdoc.1
@@ -1,6 +1,7 @@
-.\" $Id$
+.\" $Id$
.\"
.\" 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
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 t
.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
--
To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2019-04-09 16:57 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-04-09 16:57 docbook2mdoc: update content in many respects schwarze
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).