r493: * dh_installman: documented translated man page support, and made it work

[debhelper.git] / doc / PROGRAMMING

diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index 98b4cd2951a3abc6728e6cd1c9739c50df4b4b4b..69302d34268df98368b629daf37a674b636025f7 100644 (file)
--- a/doc/PROGRAMMING
+++ b/doc/PROGRAMMING
@@ -1,4 +1,6 @@
 This file documents things you should know to write a new debhelper program.
+Any program with a name that debins with dh_ should conform to these
+guidelines (with the historical exception of dh_make).
 
 Standardization:
 ---------------
@@ -11,14 +13,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 +36,20 @@ 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.
 
+In general, files named debian/*.debhelper are internal to debhelper, and
+their expstence or use should not be relied on by external programs such as
+the build process of a package.
+
+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 +57,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 +129,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,12 +178,11 @@ 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
+       Pass this command a number, and if the current compatibility level
        equals that number, it will return true. Looks at DH_COMPAT to get
-       the compatability level.
+       the compatibility level.
 pkgfile()
        Pass this command the name of a binary package, and the base name of a
        file, and it will return the actual filename to use. This is used
@@ -203,4 +211,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>
+