Recommend use of dh

Document dh as the recommended default approach to implementing
debian/rules and provide some basic information about it.  Include
the basic dh debian/rules template and mention that it implements
the default targets via a wildcard rule.

Minorly clean up the language in the first two paragraphs of the
debian/rules section.

1 files changed, 40 insertions, 9 deletions

diff --git a/policy/ch-source.rst b/policy/ch-source.rst
index ee9270d..9ea2f5c 100644
--- a/policy/ch-source.rst
+++ b/policy/ch-source.rst
@@ -259,18 +259,49 @@ files, sockets or setuid or setgid files.. [#]_
 Main building script: ``debian/rules``
 --------------------------------------
 
-This file must be an executable makefile, and contains the
-package-specific recipes for compiling the package and building binary
-package(s) from the source.
-
-It must start with the line ``#!/usr/bin/make -f``, so that it can be
-invoked by saying its name rather than invoking ``make`` explicitly.
-That is, invoking either of ``make -f debian/rules args...`` or ``./debian/rules args...`` must result in identical behavior.
+This file must be an executable makefile.  It contains the
+package-specific recipes for compiling the source (if required) and
+constructing one or more binary packages.
+
+``debian/rules`` must start with the line ``#!/usr/bin/make -f`` so that
+it can be executed by running ``./debian/rules`` from the top of the
+source package.  Invoking either of ``make -f debian/rules <arg> ...`` or
+``./debian/rules <arg> ...`` must result in identical behavior.
+
+In the absence of a reason to use a different approach, the recommended
+way to implement the build process of a Debian package, including the
+contents of the ``debian/rules`` building script, is the ``dh`` tool,
+which is provided by the debhelper package.  This is the most common
+packaging helper tool in Debian.  Using it will save effort in complying
+with the rules in this document, since it will automatically implement
+many of them without requiring explicit instructions.
+
+There are various situations in which ``dh`` is not the best choice.  For
+example, the standard tools for packaging software written in some
+languages may use another tool, some rarer packaging patterns (such as
+multiple builds of the same software with different options) are easier to
+express with other tools, or the packager may be working on a new
+packaging helper and may therefore want to use that tool.  Using ``dh`` is
+therefore not required.  But it is a wise default choice in most
+situations.
+
+If the package uses ``dh``, the default content of ``debian/rules`` will
+be::
+
+    #!/usr/bin/make -f
+    %:
+            dh $@
+
+(the start of the ``dh`` line must be a literal tab), and any special
+rules for this package will be expressed as overrides.  ``dh`` will then
+take care most of the requirements below (and many others).  See the
+documentation in the debhelper package for more information.
 
 The following targets are required and must be implemented by
 ``debian/rules``: ``clean``, ``binary``, ``binary-arch``,
-``binary-indep``, ``build``, ``build-arch`` and ``build-indep``. These
-are the targets called by ``dpkg-buildpackage``.
+``binary-indep``, ``build``, ``build-arch`` and ``build-indep``.  (When
+using ``dh``, these are implemented using the wildcard pattern shown
+above.)  These are the targets called by ``dpkg-buildpackage``.
 
 Since an interactive ``debian/rules`` script makes it impossible to
 auto-compile that package and also makes it hard for other people to