X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=tools.dbk;h=a9b4b816da0f35085f559c3529edcfbd3dfcda43;hb=1c245b536e741df8beeceb7c109ccf884cd90276;hp=01ee79c942336a5ab34dc0e688615b89512c4215;hpb=0f9085ad6385ebf75fc04dd9203be4c2a5ebaa14;p=developers-reference.git

diff --git a/tools.dbk b/tools.dbk
index 01ee79c..a9b4b81 100644
--- a/tools.dbk
+++ b/tools.dbk
@@ -95,10 +95,10 @@ errors.
 </para>
 <para>
 You should periodically get the newest <systemitem
-role="package">lintian</systemitem> from `unstable' and check over all your
-packages.  Notice that the <literal>-i</literal> option provides detailed
-explanations of what each error or warning means, what its basis in Policy is,
-and commonly how you can fix the problem.
+role="package">lintian</systemitem> from <literal>unstable</literal> and check
+over all your packages.  Notice that the <literal>-i</literal> option provides
+detailed explanations of what each error or warning means, what its basis in
+Policy is, and commonly how you can fix the problem.
 </para>
 <para>
 Refer to <xref linkend="sanitycheck"/> for more information on how and when to
@@ -108,7 +108,7 @@ use Lintian.
 You can also see a summary of all problems reported by Lintian on your packages
 at <ulink url="&url-lintian;"></ulink>.  These reports contain the
 latest <command>lintian</command> output for the whole development distribution
-(unstable).
+(<literal>unstable</literal>).
 </para>
 </section>
 
@@ -262,8 +262,8 @@ upstream changes into the repository.
 <para>
 These utilities provide an infrastructure to facilitate the use of CVS by
 Debian maintainers.  This allows one to keep separate CVS branches of a package
-for <emphasis>stable</emphasis>, <emphasis>unstable</emphasis> and possibly
-<emphasis>experimental</emphasis> distributions, along with the other benefits
+for <literal>stable</literal>, <literal>unstable</literal> and possibly
+<literal>experimental</literal> distributions, along with the other benefits
 of a version control system.
 </para>
 </section>
@@ -306,8 +306,8 @@ environment.
 It can use chrooted environments as well.  It can be used stand-alone, or as
 part of a networked, distributed build environment.  As the latter, it is part
 of the system used by porters to build binary packages for all the available
-architectures.  See <xref linkend="buildd"/> for more information, and <ulink
-url="&url-buildd;"></ulink> to see the system in action.
+architectures.  See <xref linkend="wanna-build"/> for more information, and 
+<ulink url="&url-buildd;"></ulink> to see the system in action.
 </para>
 </section>
 
@@ -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>