r1980: * prerm and postrm scripts are now generated in a reverse order than

[debhelper.git] / debhelper.pod

diff --git a/debhelper.pod b/debhelper.pod
index 1aeec099b2014ebe18b5453ee2f3cf30931f3ba1..123f72675d3434305eec5ccb08557ea41d9d8535 100644 (file)
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -64,7 +64,8 @@ file can be found.
 
 In some rare cases, you may want to have different versions of these files
 for different architectures. If files named debian/package.foo.arch
-exist, where "arch" is the same as the output of "dpkg --print-architecture",
+exist, where "arch" is the same as the output of 
+"dpkg-architecture -qDEB_HOST_ARCH",
 then they will be used in preference to other, more general files.
 
 In many cases, these config files are used to specify various types of
@@ -72,6 +73,9 @@ files. Documentation or example files to install, files to move, and so on.
 When appropriate, in cases like these, you can use standard shell wildcard
 characters ('?' and '*' and '[..]' character classes) in the files.
 
+You can also put comments in these files; lines beginning with "#" are
+ignored.
+
 =head1 SHARED DEBHELPER OPTIONS
 
 The following command line options are supported by all debhelper programs.
@@ -242,9 +246,16 @@ introduced. You tell debhelper which compatibility level it should use, and
 it modifies its behavior in various ways.
 
 Tell debhelper what compatibility level to use by writing a number to
-debian/compat. For example, to turn on V4 mode:
+debian/compat. For example, to turn on V5 mode:
+
+  % echo 5 > debian/compat
 
-  % echo 4 > debian/compat
+Unless otherwise indicated, all debhelper documentation assumes that you
+are using the most recent compatibility level, and in most cases does not
+indicate if the behavior is different in an earlier compatibility level, so
+if you are not using the most recent compatibility level, you're advised to
+read below for notes about what is different in earlier compatibility
+levels.
 
 These are the available compatibility levels:
 
@@ -256,6 +267,7 @@ This is the original debhelper compatibility 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
@@ -263,6 +275,8 @@ This mode is deprecated.
 In this mode, debhelper will consistently use debian/<package>
 as the package tree directory for every package that is built.
 
+This mode is deprecated.
+
 =item V3
 
 This mode works like V2, with the following additions:
@@ -284,10 +298,11 @@ Every file in etc/ is automatically flagged as a conffile by dh_installdeb.
 
 =back
 
+This mode is deprecated.
+
 =item V4
 
-This is the recommended mode of operation. It does everything V3 does,
-plus:
+Changes from V3 are:
 
 =over 8
 
@@ -312,6 +327,54 @@ dh_link will correct existing links to conform with policy.
 
 =back
 
+=item V5
+
+This is the recommended mode of operation. It does everything V4 does,
+plus:
+
+=over 8
+
+=item -
+
+Comments are ignored in debhelper config files.
+
+=item -
+
+dh_strip --dbg-package now specifies the name of a package to put debugging
+symbols in, not the packages to take the symbols from.
+
+=item -
+
+dh_installdocs skips installing empty files.
+
+=item -
+
+dh_install errors out if wildcards expand to nothing.
+
+=back
+
+=item V6
+
+This mode is still under development. Currently it has these differences
+compared to V5:
+
+=over 8
+
+=item -
+
+dh_installwm will install a slave manpage link for x-window-manager.1.gz.
+
+=item -
+
+dh_builddeb did not previously delete everything matching
+DH_ALWAYS_EXCLUDE, if it was set to a list of things to exclude, such as
+"CVS:.svn". Now it does.
+
+=item -
+
+dh_installman allows overwriting existing man pages in the package build
+directory. In previous compatability levels it silently refuses to do this.
+
 =back
 
 =head2 Doc directory symlinks
@@ -340,15 +403,15 @@ In general, if any debhelper program needs a directory to exist under
 debian/, it will create it. I haven't bothered to document this in all the
 man pages, but for example, dh_installdeb knows to make debian/<package>/DEBIAN/
 before trying to put files there, dh_installmenu knows you need a
-debian/<package>/usr/lib/menu/ before installing the menu files, etc.
+debian/<package>/usr/share/menu/ before installing the menu files, etc.
 
 Once your package uses debhelper to build, be sure to add
 debhelper to your Build-Depends line in debian/control. You should
 build-depend on a version of debhelper equal to (or greater than) the
 debhelper compatibility level your package uses. So if your package used
-compatibility level 4:
+compatibility level 5:
 
-  Build-Depends: debhelper (>= 4)
+  Build-Depends: debhelper (>= 5)
 
 =head1 ENVIRONMENT