Wording changes to dh recommendation

Mostly from Sean Whitton.  Also revert some unrelated informative
changes, leaving only clarity and formatting fixes.  Drop the
sample minimal debian/rules file, leaving only a reference to the
dh documentation.  Don't stress a new packaging helper to make it
more obvious that cdbs is one of the expected exceptions to this
advice.

1 files changed, 23 insertions, 34 deletions

diff --git a/policy/ch-source.rst b/policy/ch-source.rst
index 9ea2f5c..93beb4a 100644
--- a/policy/ch-source.rst
+++ b/policy/ch-source.rst
@@ -263,45 +263,34 @@ 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
+``debian/rules`` 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.
+
+The recommended way to implement the build process of a Debian package, in
+the absence of a good reason to use a different approach, is the ``dh``
+tool.  This includes the contents of the ``debian/rules`` building script.
+``dh`` is the most common packaging helper tool in Debian.  Using it will
+usually save effort in complying with the rules in this document, because
+``dh`` will automatically implement many of them without requiring
+explicit instructions.
+
+There are sometimes good reasons to use a different approach.  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.
+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; and a packager working on a different packaging
+helper might want to use their tool.  The recommendation to use ``dh``
+does not always apply, and use of ``dh`` is not required.
 
-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.
+For more information about how to use ``dh``, see the documentation in the
+debhelper package, most notably the dh(1) manual page.
 
 The following targets are required and must be implemented by
 ``debian/rules``: ``clean``, ``binary``, ``binary-arch``,
-``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``.
+``binary-indep``, ``build``, ``build-arch`` and ``build-indep``. 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