debiandoc-sgml: SGML-based formatting for Debian/dpkg manuals

[Ian Jackson <ian@chiark.chu.cam.ac.uk>]

(NB: This message is crossposted.  Mind your followups.)

I felt like linuxdoc-sgml was unsuitable for me because:
 * It has serious problems with metacharacter handling/escaping.
 * The DTD doesn't express what was supported by the backends, and
   is generally full of leftover gunk.
 * The formatting of certain constructs - especially cross-references
   and examples - by several of the backends is poor.
 * It doesn't have all the features I wanted.
 * It has features I don't want and don't want to bother maintaining.
 * Its backends generate their output through too many or IMO the
   wrong intermediate stages (eg, plain text via groff or PostScript
   via LaTeX).

So I wrote this.  It's small but it does what it claims to do -
translate documents in its DTD into HTML, plain text (overstruck or
not) and PostScript (via Lout).  Info is not supported at the moment.

I've marked it for placement in project/experimental on the Debian
archive because it's in the new Debian source package format which
hasn't been agreed on yet, not because it's particularly unstable.
(Non-Debian users can just untar and build it.)

You need `sp' (aka nsgmls) as that's the SGML parser it expects, and
SGMLsp (the Perl modules for SGML backends) and Perl5 of course.  It
has one dependency on linuxdoc-sgml, due to the file
/usr/lib/linuxdoc-sgml/rep/latin1/general (which is a list of
character entities).

There is no documentation for the formatter itself yet, but the DTD
contains only things that are supported by the backends and should be
fairly clear.  I'll write a manual for it when I have a free hour or
two.

The Debian change information for the package is below.  It should
appear in project/experimental on the Debian sites shortly.

I'm unlikely to be able to help with requests to add features to it,
because I'm very busy.  However, if you do something sensible to the
DTD _and_ support it in _all_ the backends I might look favourably on
a patch.  Discussing it somewhere if you plan to do this would
probably be a good idea.  On the linuxdoc-sgml list, perhaps, unless
people will mind ?

Because the DTD is so small - 87 lines - I've included that too.

Ian.

-----BEGIN PGP SIGNED MESSAGE-----

Format: 1.5
Date: Sat, 10 Aug 1996 22:01:38 +0100
Source: debiandoc-sgml
Binary: debiandoc-sgml
Architecture: source all
Version: 1.0
Distribution: experimental
Urgency: low
Maintainer: Ian Jackson <ian@chiark.chu.cam.ac.uk>
Description: 
 debiandoc-sgml - Documentation formatting for Debian manuals
Changes: 
 debiandoc-sgml (1.0) experimental; urgency=LOW
 .
   * Initial release.
Files: 
 734bc16c3554423a36972a2a3f2b5413 551 text optional debiandoc-sgml_1.0.dsc
 150663201886f8433e59f7edd537e44c 23090 text optional debiandoc-sgml_1.0.tar.gz
 19e72e5820a609a20499895b1f7943c5 12830 text optional debiandoc-sgml_1.0_all.deb

-----BEGIN PGP SIGNATURE-----
Version: 2.6.2i

iQCVAwUBMgz+TcMWjroj9a3bAQHk6wQAwySiTOJPoBCgRBha9Hwr2yeIJORIKRBJ
8BhjlZ7DaJdOL9qtZHC+36p/wfzkYb+Me+O5ra6eRXtrQBEm7NXwDrVDqZ+Eqx47
uUsnt4CjhVHNLZBJwAKS4PvoDaY4wxLBmfFq22d6hrfcxSBHyxHNG0K0CcHjDFbr
bKTubyoYyE8=
=lIe3
-----END PGP SIGNATURE-----

<!--
    debiandoc.dtd

    Copyright 1996 Ian Jackson
    This is free software.  You may distribute it under the terms of
    the GNU General Public Licence, version 2 or at your option any
    later version.

    This DTD was inspired by linuxdoc.dtd which was based on QWERTZ.
    Contributors to linuxdoc.dtd include Matt Welsh, Greg Hankins,
    Eric Raymond, Marc Baudoin, Tristan Debeaupuis and Tom Gordon.
  -->

<!element book - - (titlepag, toc?, chapt+)>
<!element debiandoc o o (book)>

<!entity % emph "em|var|prgn|tt|qref">
<!entity % xref "ref|manref|email|ftpsite|ftppath">
<!entity % list "list|enumlist|taglist">
<!entity % inline "(#pcdata|%emph|%xref|footnote)+">
<!entity % inpara "((%inline)|(%list)|example)+">
<!entity % paras "(p+)">
<!entity % sect "heading,(%paras)?">

<!element titlepag o o (title,author+,version?,abstract?,copyright?)>
<!element title - o (%inline)>
<!element author - o (name,email)>
<!element name o o (%inline) -(email)>
<!element email o o (#pcdata)>
<!element version - o (#pcdata|date)+>
<!element date - o empty>
<!element abstract - o (%inpara)>
<!element copyright - o (copyrightsummary,p*)>
<!element copyrightsummary o o (%inpara)>

<!element toc - o empty>
<!attlist toc detail (chapt|sect|sect1|sect2) "sect">
<!element heading o o (%inline) -(%xref)>
<!element chapt - o ((%sect),sect*)>
<!element sect - o ((%sect),sect1*)>
<!element sect1 - o ((%sect),sect2*)>
<!element sect2 - o ((%sect),sect3*)>
<!element sect3 - o ((%sect),sect4*)>
<!element sect4 - o (%sect)>
<!attlist chapt id cdata #implied>
<!attlist sect id cdata #implied>
<!attlist sect1 id cdata #implied>
<!attlist sect2 id cdata #implied>
<!attlist sect3 id cdata #implied>
<!attlist sect4 id cdata #implied>

<!element footnote - - (%paras)>

<!element p o o (%inpara)>

<!element em - - (%inline)     -- emphasis -->
<!element var - - (%inline)    -- metasyntactic variable or text -->
<!element prgn - - (%inline)   -- (short) name of a program, command, &c -->
<!element tt - - (%inline)     -- code and filename fragements -->
<!-- don't use tt for all `typewriter' text, some must be prgn -->
<!element qref - - (%inline)>
<!attlist qref id cdata #required>

<!element example - - (%inline) -(tt|prgn|em|%xref)>

<!element list - - (item+)>
<!element enumlist - - (item+)>
<!element taglist - - (tag+,item)+>
<!attlist list compact (compact) #implied>
<!attlist enumlist compact (compact) #implied>
<!attlist taglist compact (compact) #implied>

<!element item - o (%paras)>
<!element tag - o (%inline)>

<!element manref - o empty>
<!attlist manref name cdata #required
                 section cdata #required>

<!element ref - o empty>
<!attlist ref id cdata #required>

<!element ftpsite - - (#pcdata)>
<!element ftppath - - (#pcdata)>

<!entity % general-chars system>
%general-chars;