Typo. Closes: #653339

[debhelper.git] / debhelper.pod

diff --git a/debhelper.pod b/debhelper.pod
index 15f7ec258f9f79c4f1afcd656314e2159217ecf1..1d1d907d3297626a9f9b0045e1b6a35f4a40cd17 100644 (file)
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -69,9 +69,9 @@ Generally, these files will list files to act on, one file per line. Some
 programs in debhelper use pairs of files and destinations or slightly more
 complicated formats.
 
-Note that if a package is the first (or only) binary package listed in
-F<debian/control>, debhelper will use F<debian/foo> if no F<debian/package.foo>
-file can be found.
+Note for the first (or only) binary package listed in
+F<debian/control>, debhelper will use F<debian/foo> when there's no
+F<debian/package.foo> file.
 
 In some rare cases, you may want to have different versions of these files
 for different architectures or OSes. If files named debian/I<package>.foo.I<ARCH>
@@ -80,14 +80,19 @@ output of "B<dpkg-architecture -qDEB_HOST_ARCH>" /
 "B<dpkg-architecture -qDEB_HOST_ARCH_OS>",
 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
+Mostly, these config files are used to specify lists of various types of
 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 (B<?> and B<*> and B<[>I<..>B<]> character classes) in the files.
-
 You can also put comments in these files; lines beginning with B<#> are
 ignored.
 
+The syntax of these files is intentionally kept very simple to make then
+easy to read, understand, and modify. If you prefer power and complexity,
+you can make the file executable, and write a program that outputs
+whatever content is appropriate for a given situation. When you do so,
+the output is not further processed to expand wildcards or strip comments.
+
 =head1 SHARED DEBHELPER OPTIONS
 
 The following command line options are supported by all debhelper programs.
@@ -195,6 +200,8 @@ The following command line options are supported by all of the B<dh_auto_>I<*>
 debhelper programs. These programs support a variety of build systems,
 and normally heuristically determine which to use, and how to use them.
 You can use these command line options to override the default behavior.
+Typically these are passed to L<dh(1)>, which then passes them to all the 
+B<dh_auto_>I<*> programs.
 
 =over 4
 
@@ -479,6 +486,11 @@ explicit binary target with explicit dependencies on the other targets.
 
 =item -
 
+B<dh_strip> compresses debugging symbol files to reduce the installed
+size of -dbg packages.
+
+=item -
+
 B<dh_auto_configure> does not include the source package name
 in --libexecdir when using autoconf.
 
@@ -492,6 +504,21 @@ All of the B<dh_auto_>I<*> debhelper programs and B<dh> set
 environment variables listed by B<dpkg-buildflags>, unless
 they are already set. They support DEB_BUILD_OPTIONS=noopt too.
 
+=item -
+
+B<dh_auto_configure> passes CFLAGS to perl F<Makefile.PL> and
+F<Build.PL>
+
+=item -
+
+B<dh_strip> puts separated debug symbols in a location based on their
+build-id.
+
+=item -
+
+Executable debhelper config files are run and their output used as the
+configuration.
+
 =back
 
 =back
@@ -613,13 +640,10 @@ Set to B<1> to enable no-act mode.
 =item B<DH_OPTIONS>
 
 Anything in this variable will be prepended to the command line arguments
-of all debhelper commands. Command-specific options will be ignored by 
-commands that do not support them. 
+of all debhelper commands.
 
-This is useful in some situations, for example, if you need to pass B<-p> to
-all debhelper commands that will be run. One good way to set B<DH_OPTIONS> is
-by using "Target-specific Variable Values" in your F<debian/rules> file. See
-the make documentation for details on doing this.
+When using L<dh(1)>, it can be passed options that will be passed on to each
+debhelper command, which is generally better than using DH_OPTIONS.
 
 =item B<DH_ALWAYS_EXCLUDE>