r289: * Added note to man pages of commands that use autoscript to note they are

     not idempotent.

12 files changed, 129 insertions, 83 deletions

diff --git a/debian/changelog b/debian/changelog
index 2d5cb310..2dd8d7fd 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,10 @@
+debhelper (2.0.57) unstable; urgency=low
+
+  * Added note to man pages of commands that use autoscript to note they are
+    not idempotent.
+
+ -- Joey Hess <joeyh@master.debian.org>  Fri,  1 Oct 1999 13:18:20 -0700
+
 debhelper (2.0.56) unstable; urgency=low
 
   * Fiddlesticks. The neat make trick I was using in rules.multi2 failed if
diff --git a/dh_installdebconf.1 b/dh_installdebconf.1
index 3249502a..2c448c20 100644
--- a/dh_installdebconf.1
+++ b/dh_installdebconf.1
@@ -33,6 +33,10 @@ Do not modify postrm script.
 See
 .BR debhelper (1)
 for a list of environment variables that affect all debhelper commands.
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .SH "SEE ALSO"
 .TP
 .BR debhelper (1)
diff --git a/dh_installdocs.1 b/dh_installdocs.1
index 01e4feb8..37d184f4 100644
--- a/dh_installdocs.1
+++ b/dh_installdocs.1
@@ -77,6 +77,11 @@ for a list of environment variables that affect all debhelper commands.
 .BR debhelper (1)
 .TP
 .BR install-docs (8)
+.SH NOTES
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .SH BUGS
 It's impossible to specify filenames with spaces or other whitespace in them
 in debian/docs file. This is more a historical design flaw than a bug.
diff --git a/dh_installemacsen.1 b/dh_installemacsen.1
index 15ec575a..e2e23e30 100644
--- a/dh_installemacsen.1
+++ b/dh_installemacsen.1
@@ -3,7 +3,7 @@
 dh_installemacsen \- register an emacs add on package
 .SH SYNOPSIS
 .B dh_installemacsen
-.I "[debhelper options] [-n]"
+.I "[debhelper options] [-n] [--number=n] [--flavor=foo]"
 .SH "DESCRIPTION"
 dh_installemacsen is a debhelper program that is responsible for installing
 files used by the debian emacsen-common package into package build directories. 
@@ -16,10 +16,12 @@ for an explanation of how this works.
 If a file named debian/package.emacsen-install exists, then it is installed into
 usr/lib/emacsen-common/packages/install/package in the package build
 directory. Similarly, debian/package.emacsen-remove is installed into
-usr/lib/emacsen-common/packages/remove/package
+usr/lib/emacsen-common/packages/remove/package . And similarly,
+debian/package.emacsen-startup is installed into
+etc/emacs/site-start.d/50<package>.el (by default).
 .P
 For the first first binary package listed in the control file, you may use
-debian/emacsen-install and debian/emacsen-remove instead.
+debian/emacsen-install, debian/emacsen-remove, and debian/emacsen-startup instead.
 .SH OPTIONS
 .TP
 .B debhelper options
@@ -29,10 +31,21 @@ for a list of options common to all debhelper commands.
 .TP
 .B \-n, \--noscripts
 Do not modify postinst/prerm scripts.
+.TP
+.B \--number=n
+Sets the priority number of a site-start.d file. Default is 50.
+.TP
+.B \--flavor=foo
+Sets the flavor a site-start.d file will be installed in. Default is
+"emacs", alternatives include "xemacs" and "emacs20".
 .SH ENVIRONMENT
 See
 .BR debhelper (1)
 for a list of environment variables that affect all debhelper commands.
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .SH "SEE ALSO"
 .TP
 .BR debhelper (1)
diff --git a/dh_installinfo.1 b/dh_installinfo.1
index d413a2da..bac47fed 100644
--- a/dh_installinfo.1
+++ b/dh_installinfo.1
@@ -45,6 +45,10 @@ for a list of environment variables that affect all debhelper commands.
 .BR debhelper (1)
 .TP
 .BR install-info (8)
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .SH BUGS
 It's impossible to specify filenames with spaces or other whitespace in them
 in debian/info file. This is more a historical design flaw than a bug.
diff --git a/dh_installinit.1 b/dh_installinit.1
index 4eb4ee07..6a0e4758 100644
--- a/dh_installinit.1
+++ b/dh_installinit.1
@@ -1,70 +1,66 @@
-.TH DH_INSTALLINIT 1
+.TH DH_INSTALLINIT 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_installinit \- install init scripts into package build directories
 .SH SYNOPSIS
 .B dh_installinit
-.I "[-v] [-a] [-i] [-ppackage] [-Ptmpdir] [-n] [-r] [-d] [-u params]"
+.I "[debhelper options] [--init-script=scriptname] [-n] [-r] [-d] [-uparams]"
 .SH "DESCRIPTION"
-dh_installmenu is a debhelper program that is responsible for installing
+dh_installinit is a debhelper program that is responsible for installing
 init scripts into package build directories. 
 .P
 It also automatically generates the postinst and postrm and prerm commands 
 needed to set up the symlinks in /etc/rc*.d/ and to start and stop the init
 scripts.
 .P
-If a file named debian/init exists, then it is installed into
-etc/init.d/package in the package build directory (with "package" replaced
-by the package name, unless the -d flag is specified, see below)
-.P
-For packages other than the first binary package listed in
-the control file, use debian/package.init instead (replace "package" with 
-the name of the package.)
+If a file named debian/package.init (or debian/package.init.d for backwards
+compatibility with debstd) exists, then it is installed into
+etc/init.d/package in the package build directory, with "package" replaced
+by the packagename. (You may use debian/init for the first binary package
+listed in the control file.)
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
-.TP
-.B \-a
-Install init scripts into all architecture dependent packages.
-.TP
-.B \-i
-Install init scripts into all architecture independent packages.
-.TP
-.B \-ppackage
-Install init scripts into the package named "package".
-.TP
-.B \-Ptmpdir
-Use "tmpdir" for package build directory. 
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-n
+.B \-n, \--noscripts
 Do not modify postinst/postrm/prerm scripts.
 .TP
-.B \-r
+.B \-r, \--no-restart-on-upgrade
 Do not restart daemon on upgrade.
 .TP
-.B \-d
+.B \-d, \--remove-d
 Remove trailing "d" from the name of the package, and use the result for the
 filename the init script is installed as in etc/init.d/ . This may be useful
-for daemons with named ending in "d".
+for daemons with names ending in "d". (Note: this takes precedence over
+the --init-script parameter described below.)
 .TP
-.B \-u params
+.B \-uparams, \--update-rcd-params=params
 Pass "params" to 
 .BR update-rc.d (8)
-If not specified, "default" will be passed to
+If not specified, "defaults" will be passed to
 .BR update-rc.d (8)
-.SH NOTES
-The
-.B \-a
-.B \-i
-and
-.B \-p
-arguments are cumulative. If none are specified, then all packages listed in
-the control file will be effected.
-.SH ENVIRONMENT
 .TP
-.I DH_VERBOSE
-Enables verbose mode
+.B \--init-script=scriptname
+Use "scriptname" as for the filename the init script is installed as in
+etc/init.d/ . This is useful if you need to have an init script with a name
+different from the package's name. Note that if you use this parameter,
+dh_installinit will look to see if a file in the debian/ directory exists
+that looks like "scriptname" or "package.scriptname" and if so will install
+it as the inist script in preference to the files it normally installs. This
+feature is really only useful if you need a single package to install more
+than one init script.
+.SH ENVIRONMENT
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1),
+.BR update_rc.d (8)
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installmenu.1 b/dh_installmenu.1
index c7fa1bf3..1afb5e5f 100644
--- a/dh_installmenu.1
+++ b/dh_installmenu.1
@@ -1,52 +1,49 @@
-.TH DH_INSTALLDOCS 1
+.TH DH_INSTALLMENU 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_installmenu \- install debian menu files into package build directories
 .SH SYNOPSIS
 .B dh_installmenu
-.I "[-v] [-a] [-i] [-ppackage]"
+.I "[debhelper options] [-n]"
 .SH "DESCRIPTION"
 dh_installmenu is a debhelper program that is responsible for installing
-fils used by the debian menu package into package build directories.
+files used by the debian menu package into package build directories. 
 .P
-If a file named debian/menu exists, then it is installed into
+It also automatically generates the postinst and postrm commands needed to 
+interface with the debian menu package. See 
+.BR dh_installdeb (1)
+for an explanation of how this works.
+.P
+If a file named debian/package.menu exists, then it is installed into
 usr/lib/menu/package in the package build directory. This is a debian menu
 file.
 .P
-If a file named debian/menu-method exits, then it is installed into
+If a file named debian/package.menu-method exits, then it is installed into
 etc/menu-methods/package in the package build directory. This is a debian
 menu method file.
 .P
-For packages other than the first binary package listed in
-the control file, use debian/package.menu and debian/package.menu-method 
-instead (replace "package" with the name of the package.)
+For the first first binary package listed in the control file, you may use
+debian/menu and debian/menu-method instead.
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
-.TP
-.B \-a
-Install menu files into all architecture dependent packages.
-.TP
-.B \-i
-Install menu files into all architecture independent packages.
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-ppackage
-Install menu files into the package named "package".
-.SH NOTES
-The
-.B \-a
-.B \-i
-and
-.B \-p
-arguments are cumulative. If none are specified, then all packages listed in
-the control file will be effected.
+.B \-n, \--noscripts
+Do not modify postinst/postrm scripts.
 .SH ENVIRONMENT
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
+x.SH "SEE ALSO"
+.TP
+.BR debhelper (1)
 .TP
-.I DH_VERBOSE
-Enables verbose mode
-.SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
-,
-.BR menufile (1)
+.BR menufile (5)
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installmime.1 b/dh_installmime.1
index 4ace9985..d52fd8ea 100644
--- a/dh_installmime.1
+++ b/dh_installmime.1
@@ -29,6 +29,10 @@ for a list of options common to all debhelper commands.
 Do not modify postinst/postrm scripts.
 .SH ENVIRONMENT
 See
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .BR debhelper (1)
 for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
diff --git a/dh_installmodules.1 b/dh_installmodules.1
index 3cf4c007..2564f57b 100644
--- a/dh_installmodules.1
+++ b/dh_installmodules.1
@@ -29,6 +29,10 @@ Do not modify postinst/postrm scripts.
 See
 .BR debhelper (1)
 for a list of environment variables that affect all debhelper commands.
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .SH "SEE ALSO"
 .BR debhelper (1)
 .SH AUTHOR
diff --git a/dh_installpam.1 b/dh_installpam.1
index bb34a45c..10cb4a14 100644
--- a/dh_installpam.1
+++ b/dh_installpam.1
@@ -23,6 +23,10 @@ for a list of options common to all debhelper commands.
 See
 .BR debhelper (1)
 for a list of environment variables that affect all debhelper commands.
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .SH "SEE ALSO"
 .TP
 .BR debhelper (1)
diff --git a/dh_installwm.1 b/dh_installwm.1
index bc6ea446..290b8ada 100644
--- a/dh_installwm.1
+++ b/dh_installwm.1
@@ -2,13 +2,13 @@
 .SH NAME
 dh_installwm \- register a window manager
 .SH SYNOPSIS
-.B dh_installmenu
+.B dh_installwm
 .I "[debhelper options] [-n] wmfilename"
 .SH "DESCRIPTION"
 dh_installwm is a debhelper program that is responsible for
 generating the postinst and postrm commands needed to
 interface with the the
-.BR register-window-manager (1)
+.BR register-window-manager (8)
 command. This results in a window manager being registered when it is
 installed.
 .SH OPTIONS
@@ -33,10 +33,14 @@ for example, the -p switch.
 See
 .BR debhelper (1)
 for a list of environment variables that affect all debhelper commands.
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .SH "SEE ALSO"
 .TP
 .BR debhelper (1)
 .TP
-.BR register-window-manager (1)
+.BR register-window-manager (8)
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installxaw.1 b/dh_installxaw.1
index 19f47423..bb41eb7c 100644
--- a/dh_installxaw.1
+++ b/dh_installxaw.1
@@ -8,13 +8,13 @@ dh_installxaw \- install xaw wrappers config files into package build directorie
 dh_installxaw is a debhelper program that is responsible for installing
 xaw wrappers config files into package build directories. 
 .P
-It also automatically generates the postinst and postrm commands needed to 
+It also automatically generates the postinst, prerm, and postrm commands needed to 
 interface with the debian xaw-wrappers package. See 
 .BR dh_installdeb (1)
 for an explanation of how this works.
 .P
 If a file named debian/package.xaw exists, then it is installed into
-usr/lib/xaw-wrappers/conf/package in the package build directory.
+usr/lib/xaw-wrappers/config/package in the package build directory.
 .P
 For the first first binary package listed in the control file, you may use
 debian/xaw instead.
@@ -26,11 +26,15 @@ See
 for a list of options common to all debhelper commands.
 .TP
 .B \-n, \--noscripts
-Do not modify postinst/postrm scripts.
+Do not modify postinst/prerm/postrm scripts.
 .SH ENVIRONMENT
 See
 .BR debhelper (1)
 for a list of environment variables that affect all debhelper commands.
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
 .SH "SEE ALSO"
 .TP
 .BR debhelper (1)