r266: * FHS complience. Patch from Johnie Ingram <johnie@netgod.net>.

     For the most part, this was a straight-forward substitution,
     dh_installmanpages needed a non-obvious change though.
   * Closes: #42489, #42587, #41732.
   * dh_installdocs: Adds code to postinst and prerm as specified in
     http://www.debian.org/Lists-Archives/debian-ctte-9908/msg00038.html,
     to make /usr/doc/<package> a compatability symlink to
     /usr/share/doc/<package>. Note that currently if something exists in
     /usr/doc/<package> when the postinst is run, it will silently not make
     the symlink. I'm considering more intellingent handing of this case.
   * Note that if you build a package with this version of debhelper, it will
     use /usr/share/man, /usr/share/doc, and /usr/share/info. You may need to
     modify other files in your package that reference the old locations.

29 files changed, 888 insertions, 776 deletions

diff --git a/debhelper.1 b/debhelper.1
index e7e03c99..82a6034b 100644
--- a/debhelper.1
+++ b/debhelper.1
@@ -85,7 +85,7 @@ debhelper programs default to acting on all packages listed in the control
 file.
 .P
 See
-.BR /usr/doc/debhelper/examples/rules.multi
+.BR /usr/share/doc/debhelper/examples/rules.multi
 for an example of how to use this.
 .RE
 .TP
@@ -127,7 +127,7 @@ which makes debhelper behave in a manner compatable with the 1.x series of
 debhelper. If set to 2, debhelper's behavior will change to use the new
 features of the 2.x series. Use this with caution, as the 2.x series makes
 major changes that will break most packages. For documentation on these
-changes, read /usr/doc/debhelper/v2
+changes, read /usr/share/doc/debhelper/v2
 .TP
 .I DH_NO_ACT
 Enables no-act mode.
@@ -142,10 +142,10 @@ good way to set DH_OPTIONS is by using "Target-specific Variable Values" in
 your debian/rules file. See the make documentation for details on doing this.
 .SH "SEE ALSO"
 .TP
-.BR /usr/doc/debhelper/README
+.BR /usr/share/doc/debhelper/README
 An introduction to debhelper.
 .TP
-.BR /usr/doc/debhelper/examples/
+.BR /usr/share/doc/debhelper/examples/
 A set of example debian/rules files that use debhelper.
 .TP
 .BR http://kitenet.net/programs/debhelper/
diff --git a/debian/changelog b/debian/changelog
index 089539d3..a4527068 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,21 @@
+debhelper (2.0.40) unstable; urgency=low
+
+  * FHS complience. Patch from Johnie Ingram <johnie@netgod.net>.
+    For the most part, this was a straight-forward substitution,
+    dh_installmanpages needed a non-obvious change though.
+  * Closes: #42489, #42587, #41732.
+  * dh_installdocs: Adds code to postinst and prerm as specified in
+    http://www.debian.org/Lists-Archives/debian-ctte-9908/msg00038.html,
+    to make /usr/doc/<package> a compatability symlink to
+    /usr/share/doc/<package>. Note that currently if something exists in
+    /usr/doc/<package> when the postinst is run, it will silently not make
+    the symlink. I'm considering more intellingent handing of this case.
+  * Note that if you build a package with this version of debhelper, it will
+    use /usr/share/man, /usr/share/doc, and /usr/share/info. You may need to
+    modify other files in your package that reference the old locations.
+
+ -- Joey Hess <joeyh@master.debian.org>  Sun,  5 Sep 1999 21:06:11 -0700
+
 debhelper (2.0.30) unstable; urgency=low
 
   * It turns out it's possible to set up make variables that are specific to
diff --git a/debian/control b/debian/control
index b934849f..b34f9003 100644
--- a/debian/control
+++ b/debian/control
@@ -2,12 +2,15 @@ Source: debhelper
 Section: devel
 Priority: optional
 Maintainer: Joey Hess <joeyh@master.debian.org>
-Standards-Version: 2.1.1.0
+Standards-Version: 3.0.1.1
 
 Package: debhelper
 Architecture: all
+Depends: perl5 | perl (>= 5.004), fileutils (>= 3.16-4), file (>= 3.23-1)
+Suggests: dh-make
 Description: helper programs for debian/rules
  A collection of programs that can be used in a debian/rules file to
- automate common tasks. Programs are included to install various files into
- your package, compress files, fix file permissions, integrate your package
- with the debian menu system, etc.
+ automate common tasks related to building binary debian packages. Programs
+ are included to install various files into your package, compress files, fix
+ file permissions, integrate your package with the debian menu system,
+ suidmanager, doc-base, etc.
diff --git a/debian/rules b/debian/rules
index aae9e6b6..ccc0a363 100755
--- a/debian/rules
+++ b/debian/rules
@@ -69,7 +69,7 @@ binary-indep: link-stamp build
 		open (OUT,">$$f"); \
 		print OUT @lines; \
 		close OUT; \
-	}' debian/debhelper/usr/man/man1/*.1
+	}' debian/debhelper/usr/share/man/man1/*.1
 	# Fix up the debhelper.1 man page, substituting in a list of all
 	# debhelper commands. eek!
 	perl -ne ' \
@@ -77,10 +77,10 @@ binary-indep: link-stamp build
 		$$collect.=".TP\n.BR $$_" if $$. eq 3 && /^dh_/; \
 		close(ARGV) if eof; \
 		END { \
-			open(I,"debian/debhelper/usr/man/man1/debhelper.1"); \
+			open(I,"debian/debhelper/usr/share/man/man1/debhelper.1"); \
 			@lines=<I>; \
 			close I; \
-			open(O,">debian/debhelper/usr/man/man1/debhelper.1"); \
+			open(O,">debian/debhelper/usr/share/man/man1/debhelper.1"); \
 			foreach (@lines) { \
 				s/#LIST#/$$collect/; \
 				print O; \
diff --git a/dh_compress.1 b/dh_compress.1
index 92f5b516..58a5a2dd 100644
--- a/dh_compress.1
+++ b/dh_compress.1
@@ -11,10 +11,10 @@ that pointed to the files before they were compressed are updated to point
 to the new files.
 .P
 By default, dh_compress compresses files that debian policy mandates should
-be compressed, namely all files in usr/info, usr/man, usr/X11R6/man, and
-all files in usr/doc that are larger than 4k in size, except
-the copyright file, .html files and .gif files, and all changelog files. It
-skips any files that appear to be already compressed (based on their
+be compressed, namely all files in usr/share/info, usr/share/man, 
+usr/X11R6/man, and all files in usr/share/doc that are larger than 4k in size,
+(except the copyright file, .html files and .gif files), and all changelog 
+files. It skips any files that appear to be already compressed (based on their
 extentions).
 .P
 If a debian/package.compress file exists (debian/compress may be used for the
diff --git a/dh_debstd b/dh_debstd
index 34ea0d46..12e99ffd 100755
--- a/dh_debstd
+++ b/dh_debstd
@@ -1,4 +1,4 @@
-#!/bin/sh -e
+#!/usr/bin/perl -w
 #
 # Script to be called from debian/rules to setup all the debian specifc
 # required files
@@ -8,211 +8,215 @@
 # (but doc files can also be listed in debian/docs)
 #
 # This has been gutted and extensively rewritten to function as a debhelper
-# command by Joey Hess.
+# command by Joey Hess. And then completly rewritten in perl.
 
-# Pre-parse command line before we load dh_lib, becuase we use a
+# Need to stay compatable with debstd, so force use of level 1.
+$ENV{DH_COMAPT}=1;
+
+# Pre-parse command line before we load Dh_lib, becuase we use a
 # different style of arguments.
-for i;do
-  case "$i" in
-  -p) PERMS=1
-    ;;
-  -u) UNDOC=1
-    ;;
-  -s) SUMS=1
-    ;;
-  -m) NOAUTOMAN=1
-    ;;
-  -c) NOCOMPRESS=1
-    ;;
-  *) collect="$collect$i "
-    ;;
-  esac
-done
-set -- $collect
-
-PATH=debian:$PATH:/usr/lib/debhelper
-. dh_lib
+@argv=();
+foreach (@ARGV) {
+	if ($_ eq '-p') {
+		$ds{PERMS}=1;
+	}
+	elsif ($_ eq '-u') {
+		$ds{UNDOC}=1;
+	}
+	elsif ($_ eq '-s') {
+		$ds{SUMS}=1;
+	}
+	elsif ($_ eq '-m') {
+		$ds{NOAUTOMAN}=1;
+	}
+	elsif ($_ eq '-c') {
+		$ds{NOCOMPRESS}=1;
+	}
+	else {
+		push @argv,$_;
+	}
+}
+@ARGV=@argv;
 
-# Tolerate old style debstd invocations
-if [ "$DH_FIRSTPACKAGE" = "$1" ]; then
-	shift
-fi
+BEGIN { push @INC, "debian", "/usr/share/debhelper" }
+use Dh_Lib;
+init();
 
-# Subroutines
+# Tolerate old style debstd invocations
+if ($ARGV[0] && $dh{FIRSTPACKAGE} eq $ARGV[0]) {
+	shift;
+}
 
 # debinit handles the installation of an init.d script
-# Parameters:
-# $1= name in /etc/init.d
-# $2 = scriptname
-# $3 = package name
-# $4 = extra params for debhelper
-debinit() {
-	PPACKAGE=$3
-	SCRIPT=$1
-
-	INITPARAMS=`grep "^FLAGS=" $2` || true
-	if [ "$INITPARAMS" != "" ]; then
-		INITPARAMS=`expr "$INITPARAMS" : 'FLAGS="\(.*\)"'` || true
-		if [ "$INITPARAMS" ]; then
-			INITPARAMS="--update-rcd-params='$INITPARAMS'"
-		fi
-	fi
-
-	if grep -q NO_RESTART_ON_UPGRADE $2; then
-		doit "dh_installinit --no-restart-on-upgrade -p$PPACKAGE $INITPARAMS --init-script=$SCRIPT $4"
-	  else
-		doit "dh_installinit -p$PPACKAGE $INITPARAMS --init-script=$SCRIPT $4"
-	fi
+sub debinit { my ($script, $filename, $package, @params)=@_;
+	@initparams=();
+	$norestart='';
+	open (IN,$filename) || warn("$filename: $!");
+	while (<IN>) {
+		if (/^FLAGS=(.*)/) {
+			push @initparams, $1;
+		}
+		if (/NO_RESTART_ON_UPGRADE/) {
+			$norestart='--no-restart-on-upgrade';
+		}
+	}
+	close IN;
+	$initparams='';
+	if (@initparams) {
+		$initparams="--update-rcd-params='".join(" ",@initparams)."'";
+	}
+
+	doit("dh_installinit",$norestart,"-p$package",$initparams,"--init-script=$script",@params);
 }
 
-# Package specific things
-#
-# The first parameter is the package name
-# The second parameter is the directory name of the temp directory
-# The third parameter is the prefix for all configuration files to be processed
-package()
-{
-	local i
-	local X Y
-	CPACKAGE=$1
-	CTEMP=$2
-
+# Do package specific things for a package.
+sub do_package { my ($package, $tmp, $prefix)=@_;
 	# Deal with scripts in etc directories
-	if [ -f $3/rc.boot ]; then
-		warning "file $3/rc.boot was ignored."
-	fi
+	if (-d "$prefix/rc.boot") {
+		warning("file $prefix/rc.boot was ignored.");
+	}
 
 	# etc files that could need some tweaking
-	for i in services inittab crontab protocols profile shells rpc shells \
-		syslog.conf conf.modules modules aliases diversions inetd.conf \
-		X11/Xresources X11/config X11/window-managers X11/xinit purge ; do
-		if [ -f $3$i ]; then
-			warning "file $3$i was ignored."
-		fi
-	done
-
-	if [ -f $3init.d ]; then
-		debinit $1 $3init.d $1 ""
-	fi
+	foreach $f ('services','inittab','crontab','protocols','profile',
+		'shells','rpc','syslog.conf','conf.modules','modules',
+		'aliases','diversions','inetd.conf','X11/Xresources',
+		'X11/config','X11/window-managers','X11/xinit','purge') {
+		if ( -f "$prefix$f") {
+			warning("file $prefix$f was ignored.");
+		}
+	}
+
+	if (-f "${prefix}init.d") {
+		debinit($package,"${prefix}init.d",$package,"");
+	}
 
 	# The case of a daemon without the final d
-	if [ -f $3init ]; then
-		X=`expr $1 : '\(.*\)d$'` || true  
-		if [ "$X" ]; then
-			debinit $X $3init $1 "--remove-d"
-		fi
-	fi
-
-	if [ -f $3info ]; then
-		warning "debhelper does not yet support info files, so $3info was ignored."
-	fi
-
-	X=`find $2 -type f -perm +111 2>/dev/null | tr "\n" " "`
-	for i in $X; do
-		BINPATH="`expr "$i" : "$2/\(.*\)/.*"`"
-		BINNAME="`expr "$i" : "$2/.*/\(.*\)"`"
-
-		# Check if manpages exist
-		case "$BINPATH" in
-			DEBIAN|etc/rc.boot|usr/lib/cgi-bin|etc/init.d|etc/cron.*|usr/lib/lib*|usr/lib/*) SECTION=""
-				;;
-			sbin|usr/sbin) SECTION="8"
-				;;
-			usr/X11R6/bin) SECTION="1x"
-				;;
-			bin|usr/bin) SECTION="1"
-				;;
-			usr/games) SECTION="6"
-				;;
-			*)  SECTION=""
-				;;
-		esac
-		if [ "$SECTION" ]; then
-			Y=`find $2/usr/man $2/usr/X11R6/man -name "$BINNAME.*" 2>/dev/null` || true
-			if [ "$Y" = "" ]; then
-				if [ "$UNDOC" ]; then
-					doit "dh_undocumented -p$CPACKAGE $BINNAME.$SECTION"
-				fi
-			fi
-		fi
-	done
+	if (-f "${prefix}init") {
+		$p=$package;
+		if ($p=~s/d$//) {
+			debinit($p,"${prefix}init",$package,"--remove-d");
+		}
+	}
+
+	if (-f "${prefix}info") {
+		warning("debhelper does not yet support info files, so ${prefix}info was ignored.");
+	}
+
+	# Set up undocumented man page symlinks.
+	if (defined($ds{UNDOC}) && $ds{UNDOC}) {
+		open (FIND,"find $tmp -type f -perm +111 2>/dev/null |") || warning("find: $!");
+		while (<FIND>) {
+			chomp;
+			($binpath, $binname)=m:$tmp/(.*)/(.*):;
+	
+			# Check if manpages exist
+			$section='';
+			if ($binpath eq 'sbin' || $binpath eq 'usr/sbin') {
+				$section=8;
+			}
+			elsif ($binpath eq 'usr/X11R6/bin') {
+				$section='1x';
+			}
+			elsif ($binpath eq 'bin' || $binpath eq 'usr/bin') {
+				$section=1;
+			}
+			elsif ($binpath eq 'usr/games') {
+				$section=6;
+			}	
+			if ($section && `find $tmp/usr/share/man $tmp/usr/X11R6/man -name "$binname.*" 2>/dev/null` eq '') {
+				doit("dh_undocumented","-p$package","$binname.$section");
+			}
+		}
+		close FIND;
+	}
 }
 
-packages() {
-	local i
-	BASE=$1
-	shift
-	for i in $*; do
-		package $i debian/$i "debian/$i."
-		if [ -x debian/$i.prebuild ]; then
-			warning "file debian/$i.prebuild ignored"
-		fi
-	done
-
-	if [ -f debian/clean ]; then
-		warning "file debian/clean ignored"
-	fi
-	package $BASE debian/tmp "debian/"
+# Special case of changelog
+$changelogfile='';
+if ($ARGV[0] && $ARGV[0]=~m/change|news|history/) {
+	$changelogfile=shift;
 }
 
-# Special case of changelog
-if [ "$1" ]; then
-	if echo "$1" | egrep -qi "change|news|history" ; then
-		changelogfile=$1
-		shift
-	fi
-fi
-
-doit "dh_installdirs" # here just to make the debian/tmp, etc directories.
-doit "dh_installdocs $*"
-doit "dh_installexamples"
-doit "dh_installchangelogs $changelogfile"
-doit "dh_installmenu"
-doit "dh_installcron"
+doit("dh_installdirs"); # here just to make the debian/tmp, etc directories.
+doit("dh_installdocs",@ARGV);
+doit("dh_installexamples");
+if ($changelogfile) {
+	doit("dh_installchangelogs",$changelogfile);
+}
+else {
+	doit("dh_installchangelogs");
+}
+doit("dh_installmenu");
+doit("dh_installcron");
 
 # Manpage scan
-if [ "$NOAUTOMAN" = "" ]; then
-	doit "dh_installmanpages -p$DH_FIRSTPACKAGE"
-fi
+if (! $ds{NOAUTOMAN}) {
+	doit("dh_installmanpages","-p$dh{FIRSTPACKAGE}");
+}
 
-packages $DH_DOPACKAGES
+# Per-package stuff:
+foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
+	if ($PACKAGE eq $dh{FIRSTPACKAGE}) {
+		if (-f "debian/clean") {
+			warning("file debian/clean ignored.");
+		}
+		do_package($PACKAGE,"debian/tmp","debian/");
+	}
+	else {
+		do_package($PACKAGE,"debian/$PACKAGE","debian/$PACKAGE.");
+		if ( -x "debian/$PACKAGE.prebuild") {
+			warning("file debian/$PACKAGE.prebuild ignored.");
+		}
+	}
+}
 
-doit "dh_movefiles"
-doit "dh_strip"
+doit("dh_movefiles");
+doit("dh_strip");
 
-if [ ! "$nocompress" ]; then
-	doit "dh_compress"
-fi
+if (! $ds{NOCOMPRESS}) {
+	doit("dh_compress");
+}
 
-doit "dh_fixperms"
-doit "dh_suidregister"
-doit "dh_shlibdeps"
-doit "dh_gencontrol"
-doit "dh_makeshlibs"
+doit("dh_fixperms");
+doit("dh_suidregister");
+doit("dh_shlibdeps");
+doit("dh_gencontrol");
+doit("dh_makeshlibs");
 
 # Check to see if the install scripts have #DEBHELPER# in them, if not,
 # warn.
-for PACKAGE in $DH_DOPACKAGES; do
-	for file in postinst postrm preinst prerm; do
-		f="`pkgfile $PACKAGE $file`"
-		if [ "$f" ]; then
-			filelist="$filelist$f "
-		fi
-	done
-done
-if [ "$filelist" ]; then
-	warning "The following scripts do not contain \"#DEBHELPER#\" in them,"
-	warning "and so debhelper will not automatically add commands to them:"
-	warning "$filelist"
-fi
-
-doit "dh_installdeb"
-
-if [ "$SUMS" = "" ]; then
-	doit "dh_md5sums"
-fi
+@filelist=();
+foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
+	foreach $file (qw{postinst postrm preinst prerm}) {
+		$f=pkgfile($PACKAGE,$file);
+		if ($f) {
+			open (IN,$f);
+			$found=undef;
+			while (<IN>) {
+				if (/#DEBHELPER#/) {
+					$found=1;
+					last;
+				}
+			}
+			if (! $found) {
+				push @filelist, $f;
+			}
+		}
+	}
+}
+if (@filelist) {
+	warning("The following scripts do not contain \"#DEBHELPER#\" in them,");
+	warning("and so debhelper will not automatically add commands to them:");
+	warning(join(" ",@filelist));
+}
+
+doit("dh_installdeb");
+
+if (! $ds{SUMS}) {
+	doit("dh_md5sums");
+}
 
 # This causes the main binary package to be built, which
 # real debstd does not do. Shouldn't be a problem though,
 # if that package gets built twice.
-doit "dh_builddeb"
+doit("dh_builddeb");
diff --git a/dh_debstd.1 b/dh_debstd.1
index e3568eb6..8e2d5453 100644
--- a/dh_debstd.1
+++ b/dh_debstd.1
@@ -5,7 +5,7 @@ dh_debstd \- mimic debstd with debhelper commands
 .B dh_debstd
 .I "[-v] [--no-act] [-m] [-c] [-u] [-s] [[changelog] file ...]"
 .SH "DESCRIPTION"
-dh_debstd is a debhelper command that mimics the behavior of debstd, by
+dh_debstd is a program that mimics the behavior of debstd, by
 calling other debhelper commands. Its behavior is not a complete nor an
 exact copy of what debstd does, but it should be close enough to be usable.
 .P
@@ -59,14 +59,17 @@ generated if dh_debstd notices scripts without "#DEBHELPER#" in them.
 Enables verbose mode
 .TP
 .I DH_NO_ACT
-Enables no-act mode (see above).
+Enables no-act mode
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/from-debstd
-,
+.TP
+.BR /usr/share/doc/debhelper/from-debstd
+.TP
 .BR debstd (1)
+.TP
+.BR debhelper (1)
 .SH BUGS
 It doesn't completly mimic debstd. Some things debstd handles are not supported
-by debhelper. With the exception of buildinfo.Debian files, everything that
-is not supported will generate a warning message.
+by debhelper. Everything that is not supported will generate a warning
+message if you try to use it.
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_fixperms b/dh_fixperms
index a2fd9442..0ad5c605 100755
--- a/dh_fixperms
+++ b/dh_fixperms
@@ -1,29 +1,42 @@
-#!/bin/sh -e
+#!/usr/bin/perl -w
 #
 # Do some general file permission fixups.
 
-PATH=debian:$PATH:/usr/lib/debhelper
-source dh_lib
+BEGIN { push @INC, "debian", "/usr/share/debhelper" }
+use Dh_Lib;
+init();
 
-# General things..
-if [ -d debian/tmp ]; then
-	doit "chown -R root.root debian/tmp"
-	doit "chmod -R go=rX debian/tmp"
-fi
+foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
+	$TMP=tmpdir($PACKAGE);
 
-# Fix up premissions in /usr/doc, setting everything to not exectable
-# by default.
-files=`find debian/tmp/usr/doc -type f 2>/dev/null | tr "\n" " "` || true
-if [ "$files" ]; then
-	doit "chmod 644 $files"
-fi
-files=`find debian/tmp/usr/doc -type d 2>/dev/null | tr "\n" " "` || true
-if [ "$files" ]; then
-	doit "chmod 755 $files"
-fi
+	if (! defined($dh{EXCLUDE_FIND}) || $dh{EXCLUDE_FIND} eq '') {
+		$find_options="";
+	}
+	else {
+		$find_options="! \\( $dh{EXCLUDE_FIND} \\)";
+	}
 
-# Executable man pages is just not done.
-files=`find debian/tmp/usr/man/ debian/tmp/usr/X11*/man/ -type f 2>/dev/null | tr "\n" " "` || true
-if [ "$files" ]; then
-	doit "chmod 644 $files"
-fi
+	# General permissions fixing.
+	complex_doit("find $TMP ! -type l $find_options -print0",
+		"2>/dev/null | xargs -0r chown root.root");
+	complex_doit("find $TMP ! -type l $find_options -print0",
+		"2>/dev/null | xargs -0r chmod go=rX,u+rw,a-s");
+		
+
+	# Fix up premissions in usr/share/doc, setting everything to not
+	# executable by default, but leave examples directories alone.
+	complex_doit("find $TMP/usr/share/doc $TMP/usr/doc -type f $find_options ! -regex '.*/examples/.*' -print0",
+		"2>/dev/null | xargs -0r chmod 644");
+	complex_doit("find $TMP/usr/share/doc $TMP/usr/doc -type d $find_options -print0",
+		"2>/dev/null | xargs -0r chmod 755");
+
+	# Executable man pages are a bad thing..
+	complex_doit("find $TMP/usr/share/man $TMP/usr/man/ $TMP/usr/X11*/man/ -type f",
+		"$find_options -print0 2>/dev/null | xargs -0r chmod 644");
+
+	# ..and so are executable shared and static libraries 
+	# (and .la files from libtool)
+	complex_doit("find $TMP -perm -5 -type f",
+		"\\( -name '*.so*' -or -name '*.la' -or -name '*.a' \\) $find_options -print0",
+		"2>/dev/null | xargs -0r chmod a-X");
+}
diff --git a/dh_fixperms.1 b/dh_fixperms.1
index 6722bd11..5958d21c 100644
--- a/dh_fixperms.1
+++ b/dh_fixperms.1
@@ -1,45 +1,38 @@
-.TH DH_INSTALLDOCS 1
+.TH DH_FIXPERMS 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_fixperms \- fix permissions of files in package build directories
 .SH SYNOPSIS
 .B dh_fixperms
-.I "[-v] [-a] [-i] [-ppackage]"
+.I "[debhelper options] [-Xitem]"
 .SH "DESCRIPTION"
 dh_fixperms is a debhelper program that is responsible for setting the
-permissions of files in package build directories to a sane state.
+permissions of files and directories in package build directories to a
+sane state -- a state that complies with Debian policy.
 .P
-dh_fixperms makes all files in usr/doc in the package build directory be 
-mode 644. It also changes the permissions of all man pages to mode 644.
-It makes all files be owned by root, and it removes group and other write
-permission from all files.
+dh_fixperms makes all files in usr/share/doc in the package build directory
+(excluding files in the examples/ directory) be mode 644. It also changes 
+the permissions of all man pages to mode 644. It makes all files be owned by 
+root, and it removes group and other write permission from all files.
+It removes execute permissions from any libraries that have it set. Finally,
+it removes the setuid and setgid bits from all files in the package.
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-a
-Fix permissions for all architecture dependent packages.
-.TP
-.B \-i
-Fix permissions for all architecture independent packages.
-.TP
-.B \-ppackage
-Fix permissions for 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 have thier permissions fixed.
+.B \-Xitem, \--exclude=item
+Exclude files that contain "item" anywhere in their filename from having
+their permissions changed. You may use this option multiple times to build 
+up a list of things to exclude.
 .SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1)
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_gencontrol.1 b/dh_gencontrol.1
index 7b78248f..84bdb0a2 100644
--- a/dh_gencontrol.1
+++ b/dh_gencontrol.1
@@ -1,55 +1,36 @@
-.TH DH_INSTALLDEBFILES 1
+.TH DH_GENCONTROL 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_gencontrol \- generate and install control file
 .SH SYNOPSIS
 .B dh_gencontrol
-.I "[-v] [-a] [-i] [-ppackage] [-Ptmpdir] [-uparams]"
+.I "[debhelper options] [-uparams]"
 .SH "DESCRIPTION"
-dh_gencontrol is a debhelper program that is responsible for generating and
-installing control files, and installing them into the DEBIAN directory with
-the proper permissions.
+dh_gencontrol is a debhelper program that is responsible for generating 
+control files, and installing them into the DEBIAN directory with the proper
+permissions.
 .P
 This program is merely a wrapper around
 .BR dpkg-gencontrol (1)
-You may prefer to simply run
-.BR dpkg-gencontrol (1)
-by hand.
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
-.TP
-.B \-a
-Install files for all architecture dependent packages.
-.TP
-.B \-i
-Install files for all architecture independent packages.
-.TP
-.B \-ppackage
-Install files for the package named "package".
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-Ptmpdir
-Use "tmpdir" for package build directory. 
-.TP
-.B \-uparams
+.B \-uparams, \--dpkg-gencontrol-params=params
 Pass "params" to 
 .BR dpkg-gencontrol (1)
-.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
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.TP
+.BR debhelper (1)
+.TP
 .BR dpkg-shlibdeps (1)
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installchangelogs b/dh_installchangelogs
index 935a87a6..187e134c 100755
--- a/dh_installchangelogs
+++ b/dh_installchangelogs
@@ -1,4 +1,4 @@
-#!/bin/sh -e
+#!/usr/bin/perl -w
 #
 # Installs debian/changelog. If another filename is passed to it, installs
 # that file as the upstream changelog.
@@ -7,26 +7,57 @@
 # if so, the debian changelog is just installed as "changelog", and it is an 
 # error to specify an upstream changelog on the command line.
 
-PATH=debian:$PATH:/usr/lib/debhelper
-source dh_lib
+BEGIN { push @INC, "debian", "/usr/share/debhelper" }
+use Dh_Lib;
+init();
 
-UPSTREAM=$1
+$upstream=shift;
 
-if [ "$NATIVE" -a "$UPSTREAM" ]; then
-	error "Cannot specify an upstream changelog for a native package."
-fi
+if (isnative($dh{MAINPACKAGE}) && defined $upstream) {
+	error("Cannot specify an upstream changelog for a native debian package.");
+}
 
-if [ "$NATIVE" ]; then
-	CHANGELOG_NAME=changelog
-else
-	CHANGELOG_NAME=changelog.Debian
-fi
+if (isnative($dh{MAINPACKAGE})) {
+	$changelog_name='changelog';
+}
+else {
+	$changelog_name='changelog.Debian';
+}
 
-if [ ! -d debian/tmp/usr/doc/$PACKAGE ]; then
-	doit "install -d debian/tmp/usr/doc/$PACKAGE"
-fi
-doit "install -p -m644 debian/changelog debian/tmp/usr/doc/$PACKAGE/$CHANGELOG_NAME"
+foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
+	$TMP=tmpdir($PACKAGE);
+	$changelog=pkgfile($PACKAGE,"changelog");
 
-if [ "$UPSTREAM" ]; then
-	doit "install -p -m644 $UPSTREAM debian/tmp/usr/doc/$PACKAGE/changelog"
-fi
+	if (!$changelog) {
+		$changelog="debian/changelog";
+	}
+
+	if (! -e $changelog) {
+		error("could not find changelog $changelog");
+	}
+
+	if (! -d "$TMP/usr/share/doc/$PACKAGE") {
+		doit("install","-d","$TMP/usr/share/doc/$PACKAGE");
+	}
+	doit("install","-o","root","-g","root","-p","-m644",$changelog,
+		"$TMP/usr/share/doc/$PACKAGE/$changelog_name");
+
+	if ($upstream) {
+		if ($upstream=~m/\.html?$/i) {
+			# HTML changelog
+			doit("install","-o","root","-g","root","-p","-m644",
+				$upstream,"$TMP/usr/share/doc/$PACKAGE/changelog.html");
+			doit("ln", "-sf", 'changelog.html',
+				"$TMP/usr/share/doc/$PACKAGE/changelog");
+		}
+		else {
+			doit("install","-o","root","-g","root","-p","-m644",
+				$upstream,"$TMP/usr/share/doc/$PACKAGE/changelog");
+		}
+		if ($dh{K_FLAG}) {
+			# Install symlink to original name of the upstream changelog file.
+			# Use basename in case original file was in a subdirectory or something.
+			doit("ln","-sf","changelog","$TMP/usr/share/doc/$PACKAGE/".Dh_Lib::basename($upstream));
+		}
+	}
+}
diff --git a/dh_installchangelogs.1 b/dh_installchangelogs.1
index 2371af17..7942b7cb 100644
--- a/dh_installchangelogs.1
+++ b/dh_installchangelogs.1
@@ -1,52 +1,52 @@
-.TH DH_INSTALLCHANGELOGS 1
+.TH DH_INSTALLCHANGELOGS 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_installchangelogs \- install changelogs into package build directories
 .SH SYNOPSIS
 .B dh_installchangelogs
-.I "[-v] [-a] [-i] [-ppackage] upstream"
+.I "[debhelper options] [-k] [upstream]"
 .SH "DESCRIPTION"
 dh_installchangelogs is a debhelper program that is responsible for installing
 changelogs into package build directories.
 .P
 dh_installchangelogs determines if the package is a debian native package,
-and if so, it installs debian/changelog into usr/doc/package/changelog in
-the package build directory. Otherwise, it installs debian/changelog into
-usr/doc/package/changelog.Debian in the package build directory.
+and if so, it installs debian/changelog into usr/share/doc/package/changelog
+in the package build directory. Otherwise, it installs debian/changelog into
+usr/share/doc/package/changelog.Debian in the package build directory. (If
+files named debian/package.changelog exist, they will be used in preference to
+debian/changelog.)
 .P
 If an upstream changelog file is specified as an option, and the package is
 not a native debian package, then this upstream changelog will be installed
-as usr/doc/package/changelog in the package build directory.
+as usr/share/doc/package/changelog in the package build directory. If the
+changelog is a html file (determined by file extention), it will be
+installed as usr/share/doc/package/changelog.html instead (with a link to
+usr/share/doc/package/changelog).
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-a
-Install changelogs for all architecture dependent packages.
+.B \-k, \--keep
+Keep the original name of the upstream changelog. This will be accomplished
+by installing the upstream changelog as "changelog", and making a symlink from
+that to the original name of the changelog file. This can be useful if the
+upstream changelog has an unusual name, or if other documentation in the
+package refers to the changelog file.
 .TP
-.B \-i
-Install changelogs for all architecture independent packages.
-.TP
-.B \-ppackage
-Install changelogs for the package named "package".
+.B upstream
+Install this file as the upstream changelog.
 .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 have the changelogs installed into them.
-.P
 It is an error to specify an upstream changelog file for a debian native
 package.
 .SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1)
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installcron.1 b/dh_installcron.1
index 2819958b..6987fd3a 100644
--- a/dh_installcron.1
+++ b/dh_installcron.1
@@ -1,44 +1,30 @@
-.TH DH_INSTALLCRON 1
+.TH DH_INSTALLCRON 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_installcron \- install cron scripts into etc/cron.*
 .SH SYNOPSIS
 .B dh_installcron
-.I "[-v] [-a] [-i] [-ppackage]"
+.I "[debhelper options]"
 .SH "DESCRIPTION"
 dh_installcron is a debhelper program that is responsible for installing
-cron scripts into etc/cron.* in package build directories. The files 
-debian/cron.daily, debian/cron.weekly, and debian/cron.monthly are
-installed. If your package generates multiple binary packages, you can also
-use filenames like debian/package.cron.daily, where "package" is replaced
-with the name of the binary package this cron script goes into.
+cron scripts into etc/cron.* in package build directories. The files
+debian/cron.daily, debian/cron.weekly, debian/cron.monthly, and debian/cron.d
+are installed. If your package generates multiple binary packages (or if you
+just prefer to do it), you can also use filenames like 
+debian/package.cron.daily, where "package" is replaced with the name of the 
+binary package this cron script goes into.
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
-.TP
-.B \-a
-Install cron files for all architecture dependent packages.
-.TP
-.B \-i
-Install cron files for all architecture independent packages.
-.TP
-.B \-ppackage
-Install cron files for 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 debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1)
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installdeb.1 b/dh_installdeb.1
index 08b6cbae..0ae45641 100644
--- a/dh_installdeb.1
+++ b/dh_installdeb.1
@@ -1,9 +1,9 @@
-.TH DH_INSTALLDEBFILES 1
+.TH DH_INSTALLDEB 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_installdeb \- install files into the DEBIAN directory
 .SH SYNOPSIS
 .B dh_installdeb
-.I "[-v] [-a] [-i] [-ppackage] [-Ptmpdir]"
+.I "[debhelper options]"
 .SH "DESCRIPTION"
 dh_installdeb is a debhelper program that is responsible for installing
 files into the DEBIAN directory in package build directories with the
@@ -11,16 +11,17 @@ correct permissions.
 .P
 dh_installdeb automatically installs the following files from debian/ into
 the DEBIAN directory:
-.IP postinst
-.IP preinst
-.IP postrm
-.IP prerm
-.IP shlibs
-.IP conffiles
+ 	postinst
+ 	preinst
+ 	postrm
+ 	prerm
+ 	shlibs
+ 	conffiles
 .P
 (For packages other than the first binary package listed in debian/control,
-prefix these filenames with then name of the "package.", for example, 
-"foo.postinst".)
+you must prefix these filenames with then name of the "package.", for example,
+"foo.postinst". You can also prefix the filenames the same way for the first
+binary package, for consitency.)
 .P
 The files postinst, preinst, postrm, and prerm are handled specially: If a
 corresponding file named debian/script.debhelper exists, the contents of that 
@@ -30,38 +31,20 @@ inserted. If the script does not exist, then a script is generated from
 the .debhelper file. The .debhelper files are created by other debhelper 
 programs, such as 
 .BR dh_installmenu (1)
-, and are shell scripts.
+, and are shell script fragments.
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
-.TP
-.B \-a
-Install files for all architecture dependent packages.
-.TP
-.B \-i
-Install files for all architecture independent packages.
-.TP
-.B \-ppackage
-Install files for the package named "package".
-.TP
-.B \-Ptmpdir
-Use "tmpdir" for package build directory. 
-.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 debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1)
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installdocs b/dh_installdocs
index 20862bfe..d6c11c89 100755
--- a/dh_installdocs
+++ b/dh_installdocs
@@ -1,6 +1,7 @@
 #!/usr/bin/perl -w
 #
-# Reads debian/docs, installs all files listed there into /usr/doc/$PACKAGE
+# Reads debian/docs, installs all files listed there into
+# /usr/share/doc/$PACKAGE
 # Also installs the debian/copyright and debian/README.debian and debian/TODO
 # and handles debian/doc-base.
 
@@ -12,8 +13,8 @@ foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
 	$TMP=tmpdir($PACKAGE);
 	$file=pkgfile($PACKAGE,"docs");
 
-	if ( ! -d "$TMP/usr/doc/$PACKAGE") {
-		doit("install","-d","$TMP/usr/doc/$PACKAGE");
+	if ( ! -d "$TMP/usr/share/doc/$PACKAGE") {
+		doit("install","-d","$TMP/usr/share/doc/$PACKAGE");
 	}
 
 	undef @docs;
@@ -27,9 +28,9 @@ foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
 	}
 
 	if (@docs) {
-		doit("cp","-a",@docs,"$TMP/usr/doc/$PACKAGE/");
-		doit("chmod","-R","go=rX","$TMP/usr/doc");
-		doit("chmod","-R","u+rw","$TMP/usr/doc");
+		doit("cp","-a",@docs,"$TMP/usr/share/doc/$PACKAGE/");
+		doit("chmod","-R","go=rX","$TMP/usr/share/doc");
+		doit("chmod","-R","u+rw","$TMP/usr/share/doc");
 	}
 
 	# .Debian is correct, according to policy, but I'm easy.
@@ -38,16 +39,19 @@ foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
 		$readme_debian=pkgfile($PACKAGE,'README.debian');
 	}
 	if ($readme_debian) {
-		doit("install","-m","644","-p","$readme_debian","$TMP/usr/doc/$PACKAGE/README.Debian");
+		doit("install","-m","644","-p","$readme_debian",
+			"$TMP/usr/share/doc/$PACKAGE/README.Debian");
 	}
 
 	$todo=pkgfile($PACKAGE,'TODO');
 	if ($todo) {
 		if (isnative($PACKAGE)) {
-			doit("install","-m","644","-p",$todo,"$TMP/usr/doc/$PACKAGE/TODO");
+			doit("install","-m","644","-p",$todo,
+				"$TMP/usr/share/doc/$PACKAGE/TODO");
 		}
 		else {
-			doit("install","-m","644","-p",$todo,"$TMP/usr/doc/$PACKAGE/TODO.Debian");
+			doit("install","-m","644","-p",$todo,
+				"$TMP/usr/share/doc/$PACKAGE/TODO.Debian");
 		}
 	}
 
@@ -59,7 +63,8 @@ foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
 		$copyright="debian/copyright";
 	}
 	if ($copyright) {
-			doit("install","-m","644","-p",$copyright,"$TMP/usr/doc/$PACKAGE/copyright");
+			doit("install","-m","644","-p",$copyright,
+				"$TMP/usr/share/doc/$PACKAGE/copyright");
 	}
 	
 	# Handle doc-base files. There are two filename formats, the usual
@@ -104,4 +109,15 @@ foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
 			);
 		}
 	}
+
+
+	# Add in the /usr/doc compatability symlinks code.
+	if (! $dh{NOSCRIPTS}) {
+		autoscript($PACKAGE,"postinst","postinst-doc",
+			"s/#PACKAGE#/$PACKAGE/g",
+		);
+		autoscript($PACKAGE,"prerm","prerm-doc",
+			"s/#PACKAGE#/$PACKAGE/g",
+		);
+	}
 }
diff --git a/dh_installdocs.1 b/dh_installdocs.1
index f21563ca..54d1a136 100644
--- a/dh_installdocs.1
+++ b/dh_installdocs.1
@@ -1,59 +1,86 @@
-.TH DH_INSTALLDOCS 1
+.TH DH_INSTALLDOCS 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_installdocs \- install documentation into package build directories
 .SH SYNOPSIS
 .B dh_installdocs
-.I "[-v] [-a] [-i] [-ppackage] [file ...]"
+.I "[debhelper options] [-A] [-n] [file ...]"
 .SH "DESCRIPTION"
 dh_installdocs is a debhelper program that is responsible for installing
-documentation into usr/doc/package in package build directories.
+documentation into usr/share/doc/package in package build directories.
 .P
 dh_installdocs automatically installs debian/copyright if it exists. If
-dh_installdocs is acting on multiple packages, debian/copyright files will be 
-installed into all packages.
+dh_installdocs is acting on multiple packages, debian/copyright files will be
+installed into all packages. However, if you need to have seperate copyright
+files for different binary packages, you can use files named 
+debian/package.copyright.
 .P
-Any filenames specified as parameters, as well as debian/README.debian and
-debian/TODO, if they exist, will be installed into the first binary
-package listed in debian/control, if dh_installdocs is acting on that
-package.
+Any filenames specified as parameters will be installed into the first
+package dh_installdocs is told to act on. By default, this is the first 
+binary package in debian/control, but if you use -p, -i, or -a flags, it 
+will be the first package specified by those flags.
 .P
-A file named debian/docs (for the first binary package in debian/control),
-or debian/package.docs (for each additional package in debian/control) can
-list other files to be installed.
+Also, debian/README.Debian (or debian/README.debian) and debian/TODO, if 
+they exist, will be installed into the first binary package listed in 
+debian/control, if dh_installdocs is acting on that package. Note that 
+debian/TODO will be installed named TODO.Debian, if the package is not a 
+debian native package. Also note that README.debian is installed as
+README.Debian, for consitency. Note that debian/package.README.Debian and
+debian/package.TODO can be used to specify files for subpackages.
+.P
+A file named debian/package.docs (debian/docs may be used for the first
+binary package in debian/control) can list other files to be installed.
+.P
+This program will automatically generate postinst and prerm commands to
+maintain a compatability symlink, /usr/doc/package, to the documentation in
+/usr/share/doc/package. See
+.BR dh_installdeb (1)
+for an explanation of how this works.
+.P
+A file named debian/package.doc-base (debian/doc-base may be used for the
+first binary package in debian/control), if it exists, will be installed as 
+a doc-base control file, and will make this program automatically generate the
+postinst and prerm commands needed to interface with the doc-base package. See
+.BR dh_installdeb (1)
+for an explanation of how this works.
+Note that the doc-id will be determined from the doc-base control file 
+in question.
+.PP
+If your package needs to register more
+than one document, you need multiple files. To accomplish this, you can use
+files named debian/package.doc-base.*
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-a
-Install files for all architecture dependent packages.
+.B \-A, \--all
+Install all files specified by command line parameters in ALL packages
+acted on.
 .TP
-.B \-i
-Install files for all architecture independent packages.
-.TP
-.B \-ppackage
-Install files for the package named "package".
+.B \-n, \--noscripts
+Do not modify postinst/prerm scripts.
 .TP
 .B file ...
-Install these files as documentation into the first binary package listed in
-debian/control, if we are acting on that package.
+Install these files as documentation into the first package acted on. (Or in
+all packages if -A is specified).
 .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.
+Note that dh_installdocs will happily copy entire directory hierarchies if
+you ask it to (it uses cp -a internally). If it is asked to install a
+directory, it will install the complete contents of the directory.
 .SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1)
+.TP
+.BR install-docs (8)
 .SH BUGS
-Filenames with spaces in them will not currently be installed.
+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.
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installexamples b/dh_installexamples
index 7aec26eb..033564ef 100755
--- a/dh_installexamples
+++ b/dh_installexamples
@@ -1,21 +1,31 @@
-#!/bin/sh -e
+#!/usr/bin/perl -w
 #
 # Reads debian/examples, installs all files listed there into
-# /usr/doc/$PACKAGE/examples
+# /usr/share/doc/$PACKAGE/examples
 
-PATH=debian:$PATH:/usr/lib/debhelper
-source dh_lib
+BEGIN { push @INC, "debian", "/usr/share/debhelper" }
+use Dh_Lib;
+init();
 
-if [ -e debian/examples ]; then
-	examples=`cat debian/examples | tr "\n" " "`
-fi
+foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
+	$TMP=tmpdir($PACKAGE);
+	$file=pkgfile($PACKAGE,"examples");
+	
+	undef @examples;
+	
+	if ($file) {
+		@examples=filearray($file);
+	}	
 
-if [ "$examples" -o $@ ]; then
-	if [ ! -d debian/tmp/usr/doc/$PACKAGE/examples ]; then
-		doit "install -d debian/tmp/usr/doc/$PACKAGE/examples"
-	fi
+	if (($PACKAGE eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
+		push @examples, @ARGV;
+	}
 
-	for file in $examples $@; do
-		doit "cp -a $file debian/tmp/usr/doc/$PACKAGE/examples/"
-	done
-fi
+	if (@examples) {
+		if (! -d "$TMP/usr/share/doc/$PACKAGE/examples") {
+			doit("install","-d","$TMP/usr/share/doc/$PACKAGE/examples");
+		}
+		
+		doit("cp","-a",@examples,"$TMP/usr/share/doc/$PACKAGE/examples");
+	}
+}
diff --git a/dh_installexamples.1 b/dh_installexamples.1
index 1fb5c44a..d1b10ff0 100644
--- a/dh_installexamples.1
+++ b/dh_installexamples.1
@@ -1,54 +1,48 @@
-.TH DH_INSTALLEXAMPLES 1
+.TH DH_INSTALLEXAMPLES 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_installexamples \- install example files into package build directories
 .SH SYNOPSIS
 .B dh_installexamples
-.I "[-v] [-a] [-i] [-ppackage] [file ...]"
+.I "[debhelper options] [-A] [file ...]"
 .SH "DESCRIPTION"
 dh_installexamples is a debhelper program that is responsible for installing
-examples into usr/doc/package/examples in package build directories.
+examples into usr/share/doc/package/examples in package build directories.
 .P
-Any filenames specified as parameters will be installed into the first
-binary package listed in debian/control, if dh_installexamples is acting on
-that package.
+Any file names specified as parameters will be installed into the first 
+package dh_installexamples is told to act on. By default, this is the first 
+binary package in debian/control, but if you use -p, -i, or -a flags, it
+will be the first package specified by those flags.
 .P
-A file named debian/examples (for the first binary package in debian/control),
-or debian/package.exmaples (for each additional package in debian/control) can
-list other files to be installed.
+A file named debian/package.examples (debian/examples may be used for the
+first binary package in debian/control) can list other files to be installed.
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-a
-Install files for all architecture dependent packages.
-.TP
-.B \-i
-Install files for all architecture independent packages.
-.TP
-.B \-ppackage
-Install files for the package named "package".
+.B \-A, \--all
+Install any files specified by command line parameters in ALL packages
+acted on.
 .TP
 .B file ...
-Install these files as documentation into the first binary package listed in
-debian/control, if we are acting on that package.
+Install these files as examples into the first package acted on. (Or into all
+packages if -A is specified.)
 .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.
+Note that dh_installexamples will happily copy entire directory hierarchies if
+you ask it to (it uses cp -a internally). If it is asked to install a
+directory, it will install the complete contents of the directory.
 .SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1)
 .SH BUGS
-Filenames with spaces in them will not currently be installed.
+It's impossible to specify filenames with spaces or other whitespace in them
+in debian/examples file. This is more a historical design flaw than a bug.
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installinfo.1 b/dh_installinfo.1
index 33e388a7..d413a2da 100644
--- a/dh_installinfo.1
+++ b/dh_installinfo.1
@@ -49,6 +49,6 @@ for a list of environment variables that affect all debhelper commands.
 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.
 .SH "CONFORMS TO"
-Debian policy, version 2.5.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_installmanpages b/dh_installmanpages
index 9dbf1c93..7e8eae6a 100755
--- a/dh_installmanpages
+++ b/dh_installmanpages
@@ -1,31 +1,131 @@
-#!/bin/sh -e
+#!/usr/bin/perl -w
 #
-# Automatically find and install man pages.
-# This is a little bit DWIMish, but still very handy.
+# Automatically find and install man pages. However, do not install any man 
+# pages listed on the command line.
+# Also change man pages with .so commands in them into symlinks.
+#
+# This is a little bit (hah!) DWIMish, but still very handy.
+
+use File::Find;
+BEGIN { push @INC, "debian", "/usr/share/debhelper" }
+use Dh_Lib;
+init();
+
+# Check if a file is a man page, for use by File::Find.
+my @manpages;
+my @allpackages;
+sub find_man {
+	# Does its filename look like a man page?
+	# .ex files are examples installed by deb-make,
+	# we don't want those, or .in files, which are
+	# from configure.
+	if (! (-f $_ && /^.*\.[1-9].*$/ && ! /\.(ex|in)$/)) {
+		return;
+	}
+	
+	# It's not in a tmp directory is it?
+	if ($File::Find::dir=~m:debian/.*tmp.*:) {
+		return;
+	}
+	foreach $dir (@allpackages) {
+		if ($File::Find::dir=~m:debian/\Q$dir\E:) {
+			return;
+		}
+	}
+	
+	# And file does think it's a real man page?
+	my $type=`file -z $_`;
+	if ($type !~ m/:.*roff/) {
+		return;
+	}
+
+	# Good enough.
+	push @manpages,"$File::Find::dir/$_";
+}
+
+# Check if a file is a .so man page, for use by File::Find.
+my @sofiles;
+my @sodests;
+sub find_so_man {
+	# The -s test is becuase a .so file tends to be small. We don't want
+	# to open every man page. 1024 is arbitrary.
+	if (! -f $_ || -s $_ > 1024) {
+		return;
+	}
+
+	# Test first line of file for the .so thing.
+	open (SOTEST,$_);
+	my $l=<SOTEST>;
+	close SOTEST;
+	if ($l=~m/\.so\s+(.*)/) {
+		my $solink=$1;
+		# This test is here to prevent links like ... man8/../man8/foo.8
+		if (Dh_Lib::basename($File::Find::dir) eq Dh_Lib::dirname($solink)) {
+			$solink=Dh_Lib::basename($solink);
+		}
+		else {
+			$solink="../$solink";
+		}
+	
+		push @sofiles,"$File::Find::dir/$_";
+		push @sodests,$solink;
+	}
+}
 
-PATH=debian:$PATH:/usr/lib/debhelper
-source dh_lib
+foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
+	$TMP=tmpdir($PACKAGE);
 
-# Note: this was mostly copied from debstd, and not verified to work.
-# Find all filenames that look like man pages.
-for file in `find * -name "*.[1-9]*" ! -name "*.ex" ! -name "*.in"`; do
-	# Make sure they arn't alreadt in debian/tmp
-	if ! expr $file : 'debian/tmp/.*' >/dev/null; then
-		# Make sure file thinks they are man pages.
-		if file $file|grep -q roff; then
-			if echo $file|grep -q /; then
-				NAME=`expr $file : '.*/\(.*\)'`
-			else
-				NAME=$file
-			fi
-			SECTION=man`expr $NAME : '.*\.\([123456789]\)'`
-			if [ ! -e debian/tmp/usr/man/$SECTION/$NAME -a \
-			     ! -e debian/tmp/usr/X11*/man/$SECTION/$NAME ]; then
-				if [ ! -d debian/tmp/usr/man/$SECTION ]; then
-					doit "install -d debian/tmp/usr/man/$SECTION"
-				fi
-				doit "install -p -m644 $file debian/tmp/usr/man/$SECTION/$NAME"
-			fi
-		fi
-	fi
-done
+	# Find all filenames that look like man pages.
+	@manpages=();
+	@allpackages=GetPackages('');
+	find(\&find_man,'.'); # populates @manpages
+	
+	foreach $page (@manpages) {
+		$page=~s:^\./::; # just for looks
+		
+		$basename=Dh_Lib::basename($page);
+		
+		# Skip all files listed on command line.
+		my $install=1;
+		foreach $skip (@ARGV) {
+			# Look at basename of what's on connect line
+			# for backwards compatability.
+			if ($basename eq Dh_Lib::basename($skip)) {
+				$install=undef;
+				last;
+			}
+		}
+		
+		if ($install) {
+			my $extdir="share";
+			# Handle X man pages specially.
+			if ($basename=~/x$/) {
+				$extdir="X11R6";
+			}
+			
+			my ($section)=$basename=~m/.*\.([1-9])/;
+			
+			my $destdir="$TMP/usr/$extdir/man/man$section/";
+			$destdir=~tr:/:/:s; # just for looks
+			if (! -e "$destdir/$basename" && !-l "$destdir/$basename") {
+				if (! -d $destdir) {
+					doit "install","-d",$destdir;
+				}
+				doit "install","-p","-m644",$page,$destdir;
+			}
+		}
+	}
+	
+	# Now the .so conversion.
+	@sofiles=@sodests=();
+	foreach $dir (qw{usr/share/man usr/X11R6/man}) {
+		if (-e "$TMP/$dir") {
+			find(\&find_so_man, "$TMP/$dir");
+		}
+	}
+	foreach $sofile (@sofiles) {
+		my $sodest=shift(@sodests);
+		doit "rm","-f",$sofile;
+		doit "ln","-sf",$sodest,$sofile;
+	}
+}
diff --git a/dh_installmanpages.1 b/dh_installmanpages.1
index 5fbad2b1..e4525bd7 100644
--- a/dh_installmanpages.1
+++ b/dh_installmanpages.1
@@ -1,67 +1,59 @@
-.TH DH_INSTALLDOCS 1
+.TH DH_INSTALLMANPAGES 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_installmanpages \- install man pages into package build directories
 .SH SYNOPSIS
 .B dh_installmanpages
-.I "[-v] [-a] [-i] [-ppackage] [file ...]"
+.I "[debhelper options] [file ...]"
 .SH "DESCRIPTION"
 dh_installmanpages is a debhelper program that is responsible for
-automatically installing man pages into usr/man/ and usr/X11R6/man/ in
+automatically installing man pages into usr/share/man/ and usr/X11R6/man/ in
 package build directories.
 .P
 dh_installmanpages scans the current directory and all subdirectories for
-filenames that look like man pages. It uses
+filenames that look like man pages. (Note that only real files are looked
+at; symlinks are ignored.) It uses
 .BR file (1)
 to verify that the files are in the correct format. Then, based on the
-files' extentions, it installs them into the correct man directory.
+files' extensions, it installs them into the correct man directory.
 .P
 All filenames specified as parameters will be skipped by dh_installmanpages.
 This is useful if by default it installs some man pages that you do not want
 to be installed.
+.P
+After the man page installation step, dh_installmanpages will check to see if
+any of the man pages are ".so" links. If so, it changes them to symlinks.
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
-.TP
-.B \-a
-Install man pages into all architecture dependent packages.
-.TP
-.B \-i
-Install man pages into all architecture independent packages.
-.TP
-.B \-ppackage
-Install man pages into the package named "package".
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
 .B file ...
 Do not install these files as man pages, even if they look like valid man
 pages.
 .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.
-.P
 dh_installmanpages will install the man pages it finds into
 .B all
 packages you tell it to act on, since it can't tell what package the man
 pages belong in.
 .SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1)
 .SH BUGS
-Man pages with the extention
+Man pages with the extension
 .B .man
 are not automatically installed. 
 .P
 Files specified as parameters that contain spaces in their filenames will
 not be processed properly.
 .P
+By default, all man pages are installed into all binary packages, which is
+almost never what you really want (use -p to work around this).
+.P
 This is a "Do what I Mean" type program - you have been warned!
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_link.1 b/dh_link.1
index 5a3fbbc2..734d4934 100644
--- a/dh_link.1
+++ b/dh_link.1
@@ -24,14 +24,12 @@ ackage dh_link is told to act on. By default, this is the first binary
 package in debian/control, but if you use -p, -i, or -a flags, it will be 
 the first package specified by those flags.
 .P
-Be sure to only use file names relative to the package build
-directory. Ie, "/usr/bin/foo" should not be used, use "usr/bin/foo" instead.
-Also, be sure you
+Be sure you
 .B do
 specify the full filename to both the source and destination files (unlike
 you would do if you were using something like
 .BR ln (1)
-)
+).
 .P
 dh_link will generate symlinks that comply with debian policy - absolute
 when policy says they should be absolute, and relative links with as short a
@@ -54,10 +52,10 @@ this in the package build directory of the first package acted on.
 (Or in all packages if -A is specified.)
 .SH EXAMPLES
 .TP
-.B dh_link usr/man/man1/foo.1 usr/man/man1/bar.1
+.B dh_link usr/share/man/man1/foo.1 usr/share/man/man1/bar.1
 Make bar.1 be a symlink to foo.1
 .TP
-.B dh_link var/lib/foo usr/lib/foo usr/X11R6/man/man1/foo.1x usr/man/man1/bar.1
+.B dh_link var/lib/foo usr/lib/foo usr/X11R6/man/man1/foo.1x usr/share/man/man1/bar.1
 Make /usr/lib/foo/ be a link to /var/lib/foo/, and bar.1 be a symlink to the
 X man page foo.1x
 .SH ENVIRONMENT
@@ -70,6 +68,6 @@ for a list of environment variables that affect all debhelper commands.
 It's impossible to specify filenames with spaces or other whitespace in them
 in debian/links file. This is more a historical design flaw than a bug.
 .SH "CONFORMS TO"
-Debian policy, version 2.5.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_perl.1 b/dh_perl.1
index f1277b0b..f3188259 100644
--- a/dh_perl.1
+++ b/dh_perl.1
@@ -1,9 +1,9 @@
-.TH DH_PERLCHECK 1 "22 June 1999" "Debhelper Commands" "Debhelper Commands"
+.TH DH_PERL 1 "22 June 1999" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_perl \- calculates perl scripts & modules dependencies
 .SH SYNOPSIS
 .B dh_perl
-.I "[debhelper options] [-k]"
+.I "[debhelper options] [-k] [-d] [library dirs ...]"
 .SH "DESCRIPTION"
 dh_perl is a debhelper program that is responsible for generating
 the perl:Depends substitutions and adding them to substvars files. 
@@ -28,6 +28,22 @@ for a list of options common to all debhelper commands.
 .TP
 .B -k
 Keep .packlist files.
+.TP
+.B -d
+In some specific cases you may want to depend on a -base package
+(ie perl-5.00X-base or perl5-base). If so, you can pass
+the -d option to make
+.BR dh_perl 
+generate a dependency on the correct base package. This is only necessary
+for some modules that are included in the base system.
+.TP
+.B library dirs
+If your package does install perl modules in non-standard 
+directories, you can make
+.BR dh_perl
+check those directories by passing their names on the command line.
+.BR dh_perl
+will only check usr/lib/perl5 by default.
 .SH ENVIRONMENT
 See
 .BR debhelper (1)
@@ -37,7 +53,7 @@ for a list of environment variables that affect all debhelper commands.
 .BR debhelper (1)
 .SH "CONFORMS TO"
 .P
-Debian policy, version 2.5.0.0
+Debian policy, version 3.0.1
 .P
 Perl policy, version 1.0
 .SH AUTHOR
diff --git a/dh_shlibdeps.1 b/dh_shlibdeps.1
index 77d90c25..6b124cbf 100644
--- a/dh_shlibdeps.1
+++ b/dh_shlibdeps.1
@@ -1,9 +1,9 @@
-.TH DH_INSTALLDEBFILES 1
+.TH DH_SHLIBDEPS 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_shlibdeps \- calculate shared library dependancies
 .SH SYNOPSIS
 .B dh_shlibdeps
-.I "[-v] [-a] [-i] [-ppackage] [-Ptmpdir] [-uparams]"
+.I "[debhelper options] [-uparams]"
 .SH "DESCRIPTION"
 dh_shlibdeps is a debhelper program that is responsible for calculating
 shared library dependancies for all executables found in the package build
@@ -11,46 +11,27 @@ directory.
 .P
 This program is merely a wrapper around
 .BR dpkg-shlibdeps (1)
-that calls it once for each package listed in the control file. You may 
-prefer to simply run 
-.BR dpkg-shlibdeps (1)
-by hand.
+that calls it once for each 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 files for all architecture dependent packages.
-.TP
-.B \-i
-Install files for all architecture independent packages.
-.TP
-.B \-ppackage
-Install files for the package named "package".
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-Ptmpdir
-Use "tmpdir" for package build directory. 
-.TP
-.B \-uparams
+.B \-uparams, \--dpkg-shlibdeps-params=params
 Pass "params" to 
 .BR dpkg-shlibdeps (1)
-.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
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.TP
+.BR debhelper (1)
+.TP
 .BR dpkg-shlibdeps (1)
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_strip.1 b/dh_strip.1
index 2eba9914..4e44d4b3 100644
--- a/dh_strip.1
+++ b/dh_strip.1
@@ -1,9 +1,9 @@
-.TH DH_STRIP 1
+.TH DH_STRIP 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
 dh_strip \- strip executables, shared libraries, and some static libraries.
 .SH SYNOPSIS
 .B dh_strip
-.I "[-v] [-a] [-i] [-ppackage]"
+.I "[debhelper options] [-Xitem]"
 .SH "DESCRIPTION"
 dh_strip is a debhelper program that is responsible for stripping
 executables, shared libraries, and static libraries that are not used for
@@ -13,33 +13,22 @@ It assumes that files that have names like lib*_g.a are static libraries
 used in debugging, and will not strip them.
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-a
-Strip files in all architecture dependent packages.
-.TP
-.B \-i
-Strip files in all architecture independent packages (likely, this is
-pointless :-).
-.TP
-.B \-ppackage
-Strip files for 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 have their files stripped.
+.B \-Xitem, \--exclude=item
+Exclude files that contain "item" anywhere in their filename from being
+stripped. You may use this option multiple times to build up a list of
+things to exclude.
 .SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1)
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/dh_undocumented b/dh_undocumented
index ebde8904..c8aa5623 100755
--- a/dh_undocumented
+++ b/dh_undocumented
@@ -1,51 +1,54 @@
-#!/bin/sh -e
+#!/usr/bin/perl -w
 #
 # Passed a list of undocumented man pages, generates symlinks to
-# undocumented.7 for those man pages.
+# undocumented.7.gz for those man pages.
 #
 # Also, it looks for debian/undocumented files for more lists of
 # undocumented man pages.
 
-PATH=debian:$PATH:/usr/lib/debhelper
-. dh_lib
-
-for PACKAGE in $DH_DOPACKAGES; do
-        TMP=`tmpdir $PACKAGE`
-	EXT=`pkgext $PACKAGE`
-
-	undoc=""
-
-	if [ -e debian/${EXT}undocumented ]; then
-		undoc=`tr "\n" " " < debian/${EXT}undocumented`
-	fi
-
-	if [ "$PACKAGE" = "$MAINPACKAGE" -a "$*" ]; then
-		undoc="$* $undoc"
-	fi
-
-	if [ "$undoc" ]; then
-		for file in $undoc; do
-			# Remove .gz extention from the filename, if present.
-			if [ `expr "$file" : '\(.*\).gz'` ]; then
-				file=`expr "$file" : '\(.*\).gz'`
-			fi
-
-			# Determine what directory the file belongs in,
-			# /usr/man, or /usr/X11R6/man.
-			section=`expr "$file" : '.*\.\([123456789]\)'`
-			if [ `expr "$file" : '.*\.[123456789]\(x\)'` ] ; then
-				dir=usr/X11R6/man/man$section
-				reldir=../../../man
-			else
-				dir=usr/man/man$section
-				reldir=..
-			fi
-
-			if [ ! -d debian/$TMP/$dir ]; then
-				doit "install -d debian/$TMP/$dir"
-			fi
-
-			doit ln -s $reldir/man7/undocumented.7.gz debian/$TMP/$dir/$file.gz
-		done
-	fi
-done
+BEGIN { push @INC, "debian", "/usr/share/debhelper" }
+use Dh_Lib;
+init();
+
+foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
+	$TMP=tmpdir($PACKAGE);
+	$undocumented=pkgfile($PACKAGE,"undocumented");
+
+	@undoc=();
+	if ($undocumented) {
+		@undoc=filearray($undocumented);
+	}
+
+	if (($PACKAGE eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
+		push @undoc, @ARGV;
+	}	
+
+	foreach $file (@undoc) {
+		$file=~s/.gz$//; # .gz extention is optional in input.
+
+		# Determine what directory the file belongs in,
+		# /usr/share/man, or /usr/X11R6/man, and how the link to
+		# the undocuemtned.7 man page will look.
+		($section)=$file=~m/^.*\.(\d)/;
+		if (!$section) {
+			error("\"$file\" does not have an extention.");
+		}	
+		if ($file=~/.*\.\dx/) {
+			$dir="usr/X11R6/man/man$section";
+			$reldir="../../../man/man7/";
+		}
+		elsif ($section != 7) {
+			$dir="usr/share/man/man$section";
+			$reldir="../man7/";
+		}
+		else {
+			$dir="usr/share/man/man$section";
+			$reldir="";
+		}
+
+		if (! -d "$TMP/$dir") {
+			doit("install","-d","$TMP/$dir");
+		}
+		doit("ln","-sf","${reldir}undocumented.7.gz","$TMP/$dir/$file.gz");
+	}
+}
diff --git a/dh_undocumented.1 b/dh_undocumented.1
index ab45baad..d5f8cc46 100644
--- a/dh_undocumented.1
+++ b/dh_undocumented.1
@@ -1,9 +1,9 @@
-.TH DH_UNDOCUMENTED 1
+.TH DH_UNDOCUMENTED 1 "" "Debhelper Commands" "Debhelper Commands"
 .SH NAME
-dh_undocumented \- make symlinks to undocumented.7 man page
+dh_undocumented \- make symlinks to undocumented.7.gz man page
 .SH SYNOPSIS
 .B dh_undocumented
-.I "[-v] [-a] [-i] [-ppackage] [manpage ...]"
+.I "[debhelper options [-A] [manpage ...]"
 .SH "DESCRIPTION"
 dh_undocumented is a debhelper program that is responsible for making
 symlinks to the
@@ -13,56 +13,50 @@ man page for man pages that are not present in your package.
 The program takes a list of man pages that should be symlinked to
 .BR undocumented (7)
 It determines what directory the man pages should be placed in by examining
-their extentions - pages ending in "x" go into /usr/X11R6/man/, while pages
-that end in anything else go in /usr/man/. It also examines the extention to
-see what section the man page belongs in. After figuring this out, it
+their extensions - pages ending in "x" go into /usr/X11R6/man/, while pages
+that end in anything else go in /usr/share/man/. It also examines the extention
+to see what section the man page belongs in. After figuring this out, it
 generates the necessary symlinks to
 .BR undocumented (7)
 , placing the sylinks in the package build directory.
 .P
 The lists of man pages that need 
 .BR undocumented (7)
-symlinks can be specified in two ways. Any man page names specified as 
-parameters will be set up in the first binary package listed in 
-debian/control, if dh_installdocs is acting on that package. 
-Also, if a file named debian/undocumented (for the first binary package in 
-debian/control), or debian/package.undocumented (for each additional package 
-in debian/control) can list other man page names to set up.
+symlinks can be specified in two ways. Any man page names specified as
+parameters will be set up in the first package dh_undocumented is told
+to act on. By default, this is the first binary package in debian/control, 
+but if you use -p, -i, or -a flags, it will be the first package specified 
+by those flags.
+Also, a file named debian/package.undocumented (or debian/undocumented, for 
+the first binary package in debian/control) can list other man page names to
+set up.
 .SH OPTIONS
 .TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
 .TP
-.B \-a
-Install undocumented man page symlinks for all architecture dependent packages.
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
 .TP
-.B \-i
-Install undocumented man page symlinks for all architecture independent packages.
-.TP
-.B \-ppackage
-Install undocumented man page symlinks for the package named "package".
+.B \-A, \--all
+Install undocumented man page symlinks for any man pages specified by 
+command line parameters in ALL packages acted on. I doubt anyone will find
+this useful, it's here for consitency with other debhelper programs.
 .TP
 .B manpage ...
 Install undocumented man page symlinks for each of these man pages
-into the first binary package listed in debian/control, if we are acting on 
-that 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.
+into the first package acted on. (Or in all packages acted on if -A is
+specified.)
 .SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
 .SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
-,
+.TP
+.BR debhelper (1)
+.TP
 .BR undocumented (7)
 .SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
 .SH AUTHOR
 Joey Hess <joeyh@master.debian.org>
diff --git a/doc/README b/doc/README
index 986eb02c..9ea93ca4 100644
--- a/doc/README
+++ b/doc/README
@@ -1,17 +1,31 @@
 Debhelper is a collection of programs that can be used in debian/rules files
-to automate common tasks. For further documentation, see the man pages for
-dh_* commands.
+to automate common tasks related to building debian binary packages. For 
+further documentation, see the man pages for dh_* commands. For an overview 
+of debhelper, including a list of all the available commands, see the
+debhelper(1) man page.
 
 To help you get started, I've included examples of debian/rules files
-that use debhelper commands extensively. See /usr/doc/debhelper/examples/ . 
-These files are also useful as they give one good order you can run the 
-various debhelper scripts in (though other variations are possible).
+that use debhelper commands extensively. See 
+/usr/share/doc/debhelper/examples/ . These files are also useful as they give
+one good order you can run the various debhelper scripts in (though other
+variations are possible).
+
+For a more gentle introduction, the maint-guide debian package contains a
+tutorial about making your first package using Debhelper.
+
+Debhelper v2:
+------------
+
+Debhelper v2 is a major new version of Debhelper, still under development.
+Debhelper will continue to work in v1 compatability mode for now, if you're
+interested in trying the new versiln, read the file named "v2".
+
 
 Starting a new package:
 ----------------------
 
 You can just use the example rules files and do the rest of the new package
-set up by hand, or you could try the new dh-make package, which contains a
+set up by hand, or you could try the dh-make package, which contains a
 "dh_make" command that is similar to debmake, and tries to automate the
 process.
 
@@ -34,67 +48,24 @@ by the -n parameter.
 
 Note that it will be shell code, so you cannot directly use it in a perl 
 script. If you would like to embed it into a perl script, here is one way to
-do that:
+do that (note that I made sure that $1, $2, etc are set with the set command):
 
-print << `EOF`
+my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
 #DEBHELPER#
 EOF
-
-
-Notes on multiple binary packages:
----------------------------------
-
-If your source package generates more than one binary package, debhelper
-programs will default to acting on all binary packages when run. If your
-source package happens to generate one architecture dependent package, and
-another architecture independent package, this is not the correct behavior,
-because you need to generate the architecture dependent packages in the
-binary-arch debian/rules target, and the architecture independent packages
-in the binary-indep debian/rules target.
-
-To facilitate this, as well as give you more control over which packages
-are acted on by debhelper programs, all debhelper programs accept the
-following parameters:
-
--a		Act on architecture dependent packages
--i		Act on architecture independent packages
--ppackage	Act on the package named "package" (may be repeated multiple
-		times)
-
-These parameters are cumulative. If none are given, the tools default to
-affecting all packages.
-
-See examples/rules.multi for an example of how to use this.
-
-Package build directories -- debian/tmp, etc:
---------------------------------------------
-
-By default, all debhelper programs assume that the temporary directory used
-for assembling the tree of files in a package is debian/tmp for the first
-package listed in debian/control, and debian/<packagename> for each
-additional package.
-
-Sometimes, you might want to use some other temporary directory. This is
-supported by the -P flag. The directory to use is specified after -P, for
-example, "dh_installdocs -Pdebian/tmp", will use debian/tmp as the temporary
-directory. Note that if you use -P, the debhelper programs can only be
-acting on a single package at a time. So if you have a package that builds
-many binary packages, you will need to use the -p flag to specify which
-binary package the debhelper program will act on. For example:
-
-	dh_installdocs -pfoolib1 -Pdebian/tmp-foolib1
-	dh_installdocs -pfoolib1-dev -Pdebian/tmp-foolib1-dev
-	dh_installdocs -pfoolib-bin -Pdebian/tmp-foolib-bin
-
-This uses debian/tmp-<package> as the package build directory.
+system ($temp) / 256 == 0
+	or die "Problem with debhelper scripts: $!\n";
 
 Other notes:
 -----------
 
-* In general, if any debhelper program needs a directory to exist under
-  debian/, it will create it. I haven't bothered to document this in all the
-  man pages, but for example, dh_installdeb knows to make debian/tmp/DEBIAN/
-  before trying to put files there, dh_installmenu knows you need a
-  debian/tmp/usr/lib/menu/ before installing the menu files, etc.
+Note that if you are generating a debian package that has arch-indep and
+arch-dependent portions, and you are using dh_movefiles to move the
+arch-indep files out of debian/tmp, you need to make sure that dh_movefiles
+does this even if only the arch-dependent package is being built (for ports
+to other architectures). I handle this in debian/rules.multi by calling
+dh_movefiles in the install target.
+
+Debhelper's home page is at http://kitenet.net/programs/debhelper/
 
 -- Joey Hess <joeyh@master.debian.org>
diff --git a/doc/v2 b/doc/v2
index 4889c398..abca26c1 100644
--- a/doc/v2
+++ b/doc/v2
@@ -3,14 +3,20 @@ being worked on, and will change in drastic ways without notice. To keep
 this from breaking packages, debhelper will continue to operate in v1
 compatability mode by default.
 
-To enable debhelper v2 features (do this with *caution*), set DH_COMPAT=2
+To enable debhelper v2 features (do this with *caution*), set DH_COMPAT=2 in
+your debian/rules. Also, it is a very good idea to add a call to your
+debian/rules like this:
+	dh_testversion 2
+To ensure that your package won't be built with some old version of
+debhelper that ignores the DH_COMPAT flag.
+
 Here are the changes I'm planning to make to debhelper for v2, based on
 prior discussion on debian-devel.
 
 Items marked with a + are done. All others will happen as soon as I can code
 them.
 
-* Standardize on the name used for the temporary build directory of a
++ Standardize on the name used for the temporary build directory of a
   package. Currently it's debian/tmp/ for the first package and 
   debian/<package>/ for other packages of a multi-binary package. I've
   decided after much agonizing to to use debian/<package>. The main thing this
@@ -39,9 +45,9 @@ them.
 * dh_movefiles should delete empty directories after it's moved all files
   out of them. (#17111)  
 
-* debian/README will be installed as /usr/doc/<package>/README in native
-  packages, and as README.Debian in non-native packages. This is consistent
-  with the handing of debian/TODO and debian/changelog. (#34628)
+* debian/README will be installed as /usr/share/doc/<package>/README in
+  native packages, and as README.Debian in non-native packages. This is
+  consistent with the handing of debian/TODO and debian/changelog. (#34628)
 
 * There will be no change to the names of debhelper config files used, I've
   decided against debian/<package>/* and the like, because although those