r506: * Introduced the debian/compat file. This is the new, preferred way to say

     what debhelper compatability level your package uses. It has the big
     advantage of being available to debhelper when you run it at the command
     line, as well as in debian/rules.
   * A new v4 feature: dh_installinit, in v4 mode, will use invoke-rc.d.
     This is in v4 for testing, but I may well roll it back into v3 (and
     earlier) once woody is released and I don't have to worry about breaking
     things (and, presumably, once invoke-rc.d enters policy).
   * Some debhelper commands will now build up a new substvars variable,
     ${misc:Depends}, based on things they know your package needs to depend
     on. For example, dh_installinit in v4 mode adds sysvinit (>= 2.80-1) to
     that dep list, and dh_installxfonts adds a dep on xutils. This variable
     should make it easier to keep track of what your package needs to depends
     on, supplimenting the ${shlibs:Depends} and ${perl:Depends} substvars.
     Hmm, this appears to be based loosely on an idea by Masato Taruishi
     <taru@debian.org>, filtered through a long period of mulling it over.
     Closes: #76352
   * Use the addsubstvar function I wrote for the above in dh_perl too.

1 files changed, 41 insertions, 10 deletions

diff --git a/debhelper.pod b/debhelper.pod
index 535d4772..df822163 100644
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -182,6 +182,24 @@ the set command):
   system ($temp) / 256 == 0
   	or die "Problem with debhelper scripts: $!";
 
+=head2 Automatic generation of miscellaneous dependencies.
+
+Some debhelper commands may make the generated package need to depend on
+some other packages. For example, if you use L<dh_installdebconf(1)>, you'r
+package will generally need to depend on debconf. Or if you use
+L<dh_installxfonts(1)>, your package will generally need to depend on a
+particular version of xutils. Keeping track of these miscellaneous
+dependencies can be annoying, so debhelper offers a way to automate it.
+All commands of this type, besides documenting what dependencies may be
+needed on their man pages, will automatically generate a substvar called
+${misc:Depends}. If you put that token into your debian/control file, it
+will be expanded to the dependencies debhelper figures you need. 
+
+This is entirely independent of the standard ${shlibs:Depends} generated by
+L<dh_makeshlibs(1)>, and the ${perl:Depends} generated by L<dh_perl(1)>.
+You can choose not to use any of these, if debhelper's guesses don't match
+reality.
+
 =head2 Package build directories
 
 By default, all debhelper programs assume that the temporary directory used
@@ -200,29 +218,36 @@ act on.
 From time to time, major non-backwards-compatible changes need to be made
 to debhelper, to keep it clean and well-designed as needs change and its
 author gains more experience. To prevent such major changes from breaking
-existing packages, the DH_COMPAT environment variable was introduced.
-DH_COMPAT may be set to a number, to determine which major revision of
-debhelper should be used. There are currently 3:
+existing packages, the concept of debhelper compatability levels was 
+introduced. You tell debhelper which compatability level it should use, and
+it modifies its behavior in various ways.
+
+You tell debhelper what compatability level to use by writing a number to
+debian/compat. For example, to turn on V3 mode:
+
+  % echo 3 > debian/compat
+
+These are the available compatablity levels:
 
 =over 4
 
 =item V1
 
-Setting DH_COMPAT=1 (or leaving it unset) causes debhelper to act in
-compatibility mode. It will use debian/tmp as the package tree
+This is the original debhelper compatability level, and so it is the default
+one. In this mode, debhelper will use debian/tmp as the package tree
 directory for the first binary package listed in the control file, while using
 debian/<package> for all other packages listed in the control file.
 This mode is deprecated.
 
 =item V2
 
-Setting DH_COMPAT=2 causes debhelper to consistently use debian/<package>
+In this mode, debhelper will consistently use debian/<package>
 as the package tree directory for every package that is built.
 
 =item V3
 
-This is the reccommended mode of operation.
-Setting DH_COMPAT=3 does everything V2 does, plus:
+This is the reccommended mode of operation. It does everything V2 does,
+plus:
 
 =over 8
 
@@ -244,7 +269,7 @@ Every file in etc/ is automatically flagged as a conffile by dh_installdeb.
 =item V4
 
 This mode is still under development, and its behavior may change at any
-time. Currently, setting DH_COMPAT=4 does everything V4 does, plus:
+time. Currently, it does everything V3 does, plus:
 
 =over 8
 
@@ -253,6 +278,11 @@ time. Currently, setting DH_COMPAT=4 does everything V4 does, plus:
 dh_makeshlibs -V will not include the debian part of the version number in
 the generated dependancy line in the shlibs file.
 
+=item -
+
+dh_installinit uses the new invoke-rc.d program in its generated maintainer
+scripts. (This may later be rolled back into V3).
+
 =back
 
 =back
@@ -297,7 +327,8 @@ that modifies files on the build system.
 
 =item DH_COMPAT
 
-Specifies what compatibility level debhelper should run at. See above.
+Temporarily specifies what compatibility level debhelper should run at,
+overriding any value in debian/compat.
 
 =item DH_NO_ACT