From: schwarze@mandoc.bsd.lv
To: source@mandoc.bsd.lv
Subject: docbook2mdoc: update content in many respects
Date: Tue, 9 Apr 2019 11:57:59 -0500 (EST) [thread overview]
Message-ID: <e3fd8aec8dd58a1c@fantadrom.bsd.lv> (raw)
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
reply other threads:[~2019-04-09 16:57 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=e3fd8aec8dd58a1c@fantadrom.bsd.lv \
--to=schwarze@mandoc.bsd.lv \
--cc=source@mandoc.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).