r380: * dh_builddeb: added a --filename option to specify the output filename.

[debhelper.git] / doc / PROGRAMMING

diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index 98b4cd2951a3abc6728e6cd1c9739c50df4b4b4b..1f89e10fdf44c86198f20109f27b3c16af59d05a 100644 (file)
--- a/doc/PROGRAMMING
+++ b/doc/PROGRAMMING
@@ -11,14 +11,14 @@ pollute the name space too much.
 
 Debhelper programs should never output anything to standard output except
 error messages, important warnings, and the actual commands they run that
-modify files under debian/ and debian/tmp, etc (this last only if they are
-passed -v, and if you output the commands, you should indent them with 1 tab). 
-This is so we don't have a lot of noise output when all the debhelper commands
-in a debian/rules are run, so the important stuff is clearly visible.
+modify files under debian/ (this last only if they are passed -v, and if you
+output the commands, you should indent them with 1 tab). This is so we don't
+have a lot of noise output when all the debhelper commands in a debian/rules
+are run, so the important stuff is clearly visible.
 
-Debhelper programs should accept the options, -v, -i, -a, -p, --no-act, and
--P, and any long forms of these options, like --verbose . If necessary, the
-options may be ignored.
+Debhelper programs should accept all options listed in the "SHARED
+DEBHELPER OPTIONS" section of debhelper(1), including and any long forms of
+these options, like --verbose . If necessary, the options may be ignored.
 
 If debhelper commands need config files, they should use
 debian/package.filename as the name of the config file (replace filename
@@ -34,14 +34,16 @@ The autoscript() function (see below) is one easy way to do this.
 dh_installdeb is an exception, it will run after the other commands and
 merge these modifications into the actual postinst scripts.
 
+Debhelper programs should default to doing exactly what policy says to do.
+
 There are always exceptions. Just ask me.
 
 Introducing Dh_Lib.pm:
 ---------------------
 
-Dh_lib.pm is the library used by all debhelper programs to parse their
+Dh_Lib.pm is the library used by all debhelper programs to parse their
 arguments and set some useful variables. It's not mandatory that your
-program use Dh_lib.pm, but it will make it a lot easier to keep it in sync
+program use Dh_Lib.pm, but it will make it a lot easier to keep it in sync
 with the rest of debhelper if it does, so this is highly encouraged.
 
 (There used to be a version of Dh_lib.pm that was a library of functions for
@@ -49,17 +51,16 @@ shell scripts. If you want to write a debhelper command that is a shell
 script, I can dig up that old library for you. Only the perl one is
 supported now, though.)
 
-Use Dh_lib.pm like this:
+Use Dh_Lib.pm like this:
 
-BEGIN { push @INC, "debian", "/usr/share/debhelper" }
-use Dh_Lib;
+use Debian::Debhelper::Dh_Lib
 init();
 
 The BEGIN block is there to make perl look for the module in all the right
 places.
 
-The init() function in the perl version. This causes Dh_lib to
-parse the command line and do some other initialization tasks.
+The init() function causes Dh_lib to parse the command line and do some other
+initialization tasks.
 
 Argument processing:
 -------------------
@@ -122,9 +123,11 @@ switch             variable        description
                                dh_movefiles will ever use this)
 --destdir      DESTDIR         will be set to a string (probably only
                                dh_builddeb will ever use this)
+--filename     FILENAME        will be set to a string
 --flavor       FLAVOR          will be set to a string (probably only
                                dh_installemacsen will ever use this)
---number       NUMBER          will be set to a number
+--number       PRIORITY        will be set to a number (deprecated)
+--priority     PRIORITY        will be set to a number
 
 Any additional command line parameters that do not start with "-" will be 
 ignored, and you can access them later just as you normally would.
@@ -169,8 +172,7 @@ warning()
 tmpdir()
        Pass this command the name of a binary package, it will return the
        name of the tmp directory that will be used as this package's
-       package build directory. Typically, this will be "debian/tmp" or
-       "debian/package".
+       package build directory. Typically, this will be "debian/package".
 compat()
        Pass this command a number, and if the current compatability level
        equals that number, it will return true. Looks at DH_COMPAT to get
@@ -203,4 +205,5 @@ autoscript()
        This command automatically adds shell script snippets to a debian
        maintainer script (like the postinst or prerm).
 
--- Joey Hess <joeyh@master.debian.org>
+-- Joey Hess <joeyh@debian.org>
+