From cff853d72fc9fcfdc7128189431483d9bd03f1c8 Mon Sep 17 00:00:00 2001
From: lucas <lucas@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Thu, 22 Jan 2009 22:48:23 +0000
Subject: [PATCH] mention docbook-xml, and that debiandoc-sgml is deprecated

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@5790 313b444b-1b9f-4f58-a734-7bb04f332e8d
---
 debian/changelog |  4 +++-
 tools.dbk        | 48 ++++++++++++++++++++++++++++++------------------
 2 files changed, 33 insertions(+), 19 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 6b6a8a5..b66de94 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -17,8 +17,10 @@ developers-reference (3.4.1) UNRELEASED; urgency=low
       distinction. Closes: #464230.
     + Switch to +nmu for NMU versioning. Closes: #437392.
     + Mention nmudiff. Closes: #483227.
+  * Mention docbook-xml, and that debiandoc-sgml is deprecated. Thanks to
+    W. Martin Borgert for the patch. Closes: #485689.
 
- -- Lucas Nussbaum <lucas@lucas-nussbaum.net>  Tue, 26 Aug 2008 10:56:17 +0200
+ -- Lucas Nussbaum <lucas@lucas-nussbaum.net>  Thu, 22 Jan 2009 23:43:48 +0100
 
 developers-reference (3.4.0) unstable; urgency=low
 
diff --git a/tools.dbk b/tools.dbk
index 2e5dda2..a9b4b81 100644
--- a/tools.dbk
+++ b/tools.dbk
@@ -499,12 +499,40 @@ enhanced to support cross-compiling.
 The following packages provide information for maintainers or help with
 building documentation.
 </para>
+
+<section id="docbook-xml">
+<title><systemitem role="package">docbook-xml</systemitem></title>
+<para>
+<systemitem role="package">docbook-xml</systemitem> provides the
+DocBook XML DTDs, which are commonly used for Debian documentation (as
+is the older debiandoc SGML DTD). This manual, for instance, is
+written in DocBook XML.
+</para>
+<para>
+The <systemitem role="package">docbook-xsl</systemitem> package
+provides the XSL files for building and styling the source to various
+output formats. You will need an XSLT processor, such as <systemitem
+role="package">xsltproc</systemitem>, to use the XSL stylesheets.
+Documentation for the stylesheets can be found in the various
+<systemitem role="package">docbook-xsl-doc-*</systemitem> packages.
+</para>
+<para>
+To produce PDF from FO, you need an FO processor, such as <systemitem
+role="package">xmlroff</systemitem> or <systemitem
+role="package">fop</systemitem>. Another tool to generate PDF from
+DocBook XML is <systemitem role="package">dblatex</systemitem>.
+</para>
+</section>
+
 <section id="debiandoc-sgml">
 <title><systemitem role="package">debiandoc-sgml</systemitem></title>
 <para>
 <systemitem role="package">debiandoc-sgml</systemitem> provides the DebianDoc
-SGML DTD, which is commonly used for Debian documentation.  This manual, for
-instance, is written in DebianDoc.  It also provides scripts for building and
+SGML DTD, which is commonly used for Debian documentation,
+but is now deprecated
+(<systemitem role="package">docbook-xml</systemitem>
+should be used instead).
+It also provides scripts for building and
 styling the source to various output formats.
 </para>
 <para>
@@ -512,22 +540,6 @@ Documentation for the DTD can be found in the <systemitem
 role="package">debiandoc-sgml-doc</systemitem> package.
 </para>
 </section>
-<!-- TODO: Maybe better:
-<section id="docbook-xml">
-<title><systemitem role="package">docbook-xml</systemitem></title>
-<para>
-<systemitem role="package">docbook-xml</systemitem> provides the
-DocBook XML DTDs, which are commonly used for Debian documentation (as
-is the older debiandoc SGML DTD). This manual, for instance, is written
-in DocBook XML. The <systemitem
-role="package">docbook-xsl</systemitem> package provides the XSL files
-for building and styling the source to various output formats. You
-will need an XSLT processor, such as <systemitem
-role="package">xsltproc</systemitem>, and an FO processor, such as
-<systemitem role="package">fop</systemitem>, to generate documentation.
-</para>
-</section>
--->
 
 <section id="debian-keyring">
 <title><systemitem role="package">debian-keyring</systemitem></title>
-- 
2.30.2