updated sect1 multiple-patches to have a better title/introduction and to mention...

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2032 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 918ada47a6dd70d9ca253d722a7660a071fa0d6e..9c4f76eb80a81a515cdf03198d765f35183937dc 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.158 $">
+  <!entity cvs-rev "$Revision: 1.159 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -2984,7 +2984,7 @@ available at <url id="&url-rules-files;">.
 
 
        <sect1 id="multiple-patches">
-          <heading>Patching source versus patching at build time</heading>
+          <heading>Separating your patches into multiple files</heading>
           <p>
 Big, complex packages may have many bugs that you need to deal with.
 If you correct a number of bug directly in the source, if you're not
@@ -2995,15 +2995,22 @@ all).  You can't take the total set of diffs (e.g., from
 <file>.diff.gz</file>) and work out which patch sets to back out as a
 unit as bugs are fixed upstream.
        <p>
-One good solution is to keep separate patches under the
-<file>debian</file> directory and apply the patches at build time. The
-<package>dbs</package> package provides an convenient means for
-applying patches at build time (and unapplying them at clean time).
-<package>dbs</package> also provides facilities for creating the
-patches and keeping track of what they are for.  As always when using
-maintainer tools, you'll have to read the accompanying documentation.
-The package <package>hello-dbs</package> is a simple example that
-demonstrates how to use <package>dbs</package>.
+Unfortunately, the packaging system as such currently doesn't provide for
+separating the patches into several files. Nevertheless, there are ways to
+separate patches: the patch files are shipped within the Debian patch file
+(<file>.diff.gz</file>), usually within the <file>debian/</file> directory.
+The only difference is that they aren't applied immediately by dpkg-source,
+but by the <tt>build</tt> rule of <file>debian/rules</file>. Conversely,
+they are reverted in the <tt>clean</tt> rule.
+       <p>
+<prgn>dbs</prgn> is one of the more popular approaches to this. It does all
+of the above, and provides a facility for creating new and updating old
+patches. See the package <package>dbs</package> for more information and
+<package>hello-dbs</package> for an example.
+       <p>
+<prgn>dpatch</prgn> also provides these facilities, but it's intented to be
+even easier to use. See the package <package>dbs</package> for documentation
+and examples (in <file>/usr/share/doc/dpatch</file>).
 
 
        <sect1 id="multiple-binary">Multiple binary packages