13 files changed, 1398 insertions, 70 deletions

diff --git a/Debian/Debhelper/Buildsystem/autoconf.pm b/Debian/Debhelper/Buildsystem/autoconf.pm
index 60fa9e85..9121a1d7 100644
--- a/Debian/Debhelper/Buildsystem/autoconf.pm
+++ b/Debian/Debhelper/Buildsystem/autoconf.pm
@@ -6,6 +6,34 @@
 
 package Debian::Debhelper::Buildsystem::autoconf;
 
+=head1 NAME
+
+B<autoconf> - GNU Autoconf (configure)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<autoconf>] ...
+
+=head1 DESCRIPTION
+
+GNU Autoconf is a popular cross-platform build system. Autoconf F<configure>
+script prepares the source for building and generates necessary F<Makefile>s
+and other temporary files in the build directory. Then a standard set of
+make targets needs to be executed in the build directory to complete source
+build process. GNU Autoconf build system can be typically identified by
+presence of the F<configure> script in the source directory.
+
+=head1 DH_AUTO NOTES
+
+Both in source (default) and out of source tree building modes are supported.
+However, please note that some original source packages might not be compatible
+with out of source tree building mode of Autoconf and hence build process may
+fail later even if the I<configure> step succeeds. 
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use Debian::Debhelper::Dh_Lib qw(dpkg_architecture_value sourcepackage);
 use base 'Debian::Debhelper::Buildsystem::makefile';
@@ -25,6 +53,35 @@ sub check_auto_buildable {
 	return 0;
 }
 
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute F<configure> from the source directory with working directory set to
+the build directory. A set of standard arguments are passed to the F<configure>
+script:
+
+ --build=`dpkg_architecture -qDEB_BUILD_GNU_TYPE`
+ --prefix=/usr
+ --includedir=${prefix}/include
+ --mandir=${prefix}/share/man
+ --infodir=${prefix}/share/info
+ --sysconfdir=/etc
+ --localstatedir=/var
+ --libexecdir=${prefix}/lib/$name_of_debian_source_package
+ --disable-maintainer-mode
+ --disable-dependency-tracking
+ --host=`dpkg_architecture -qDEB_HOST_GNU_TYPE` (if different from --build)
+
+=item I<Auto-selection>
+
+If executable file F<configure> exists in the source directory.
+
+=back
+
+=cut
 sub configure {
 	my $this=shift;
 
@@ -52,4 +109,79 @@ sub configure {
 	$this->doit_in_builddir($this->get_source_rel2builddir("configure"), @opts, @_);
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make> in the build directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute either C<make test> or C<make check> in the build directory. See
+I<makefile> build system documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make install DESTDIR=$destdir> in the build directory with $destdir
+set to the appropriate temporary installation directory. See I<makefile> build
+system documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Remove the build directory if building out of source tree or execute C<make
+distclean> if building in source. See I<makefile> build system documentation
+for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head1 SEE ALSO
+
+L<dh_auto_makefile(7)>
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/cmake.pm b/Debian/Debhelper/Buildsystem/cmake.pm
index 56628740..0275bfb8 100644
--- a/Debian/Debhelper/Buildsystem/cmake.pm
+++ b/Debian/Debhelper/Buildsystem/cmake.pm
@@ -6,6 +6,36 @@
 
 package Debian::Debhelper::Buildsystem::cmake;
 
+=head1 NAME
+
+B<cmake> - CMake (CMakeLists.txt)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<cmake>] ...
+
+=head1 DESCRIPTION
+
+CMake is a family of tools designed to build, test and package software. CMake
+generates F<Makefile>s and other temporary files in the build directory from
+the directives present in the F<CMakeLists.txt> and a couple of other build
+system source files. Then a standard set of make targets needs to be executed
+in the build directory to complete source building process. CMake is available
+in the cmake package that is essential throughout the whole build process.
+
+=head1 DH_AUTO NOTES
+
+Out of source tree building is done by default if this debhelper build system
+is selected. This is due to the fact that there is no way to properly clean up
+build directory from temporary files unless it is removed completely.
+Therefore I<clean> step cannot be fully implemented if building is done in
+source. However, the user may still enable in source building by explicitly
+specifying a build directory path that is equal to the source directory path.
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use base 'Debian::Debhelper::Buildsystem::makefile';
 
@@ -29,6 +59,27 @@ sub new {
 	return $this;
 }
 
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<cmake> in the build directory passing a path to the source directory
+and defining the following flags:
+
+ -DCMAKE_INSTALL_PREFIX=/usr
+ -DCMAKE_SKIP_RPATH=ON
+ -DCMAKE_VERBOSE_MAKEFILE=ON
+
+=item I<Auto-selection>
+
+If F<CMakeLists.txt> file exists but neither F<configure>, F<Makefile.PL>,
+F<setup.py> or F<Build.PL> exist in the source directory.
+
+=back
+
+=cut
 sub configure {
 	my $this=shift;
 	my @flags;
@@ -42,4 +93,78 @@ sub configure {
 	$this->doit_in_builddir("cmake", $this->get_source_rel2builddir(), @flags);
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make> in the build directory. See I<makefile> build system documentation
+for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make test> in the build directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make install DESTDIR=$destdir> in the build directory with $destdir
+set to the appropriate temporary installation directory. See I<makefile> build
+system documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Remove the build directory if building out of source tree (complete clean up)
+or execute C<make clean> if building in source (incomplete clean up). See
+I<makefile> build system documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head1 SEE ALSO
+
+L<dh_auto_makefile(7)>
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/makefile.pm b/Debian/Debhelper/Buildsystem/makefile.pm
index d84d3349..32ad5178 100644
--- a/Debian/Debhelper/Buildsystem/makefile.pm
+++ b/Debian/Debhelper/Buildsystem/makefile.pm
@@ -6,6 +6,56 @@
 
 package Debian::Debhelper::Buildsystem::makefile;
 
+=head1 NAME
+
+B<makefile> - make (Makefile)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<makefile>] ...
+
+=head1 DESCRIPTION
+
+Makefile based projects use C<make> to control build process. C<make> utility
+is the most popular tool on *NIX for building & installing packages from
+source. It is also a basis for most other popular build systems. For example,
+GNU Autoconf (autoconf) or CMake (cmake) generate F<Makefile>s during I<configure>
+step and leave the rest of build process for C<make> to handle.
+
+=head1 DH_AUTO NOTES
+
+Since C<make> itself does not strictly define standard target names, a couple
+of the most popular targets are tried for each building step. Whichever first
+of them is discovered to exist, it is run. If neither of the tried targets
+exist in the actual, the building step is assumed to have completed
+successfully. However, if executed C<make> target fails, the respective dh_auto
+program will fail too.
+
+If MAKE environment variable is set, its value is executed rather than default
+C<make> command.
+
+Both in source (default) and out of source tree building modes are supported.
+Either F<Makefile>, F<makefile> or F<GNUmakefile> file should be present in the
+build directory for this debhelper build system to work.
+
+=head1 BUILD PROCESS
+
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Do nothing (auto-selection continues).
+
+=item I<Auto-selection>
+
+It will never be auto-selected at this step.
+
+=back
+
+=cut
+
 use strict;
 use Debian::Debhelper::Dh_Lib qw(escape_shell);
 use base 'Debian::Debhelper::Buildsystem';
@@ -69,22 +119,92 @@ sub check_auto_buildable {
 	return 0;
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make> (without arguments) with working directory changed to the build
+directory.
+
+=item I<Auto-selection>
+
+If either F<Makefile>, F<makefile> or F<GNUmakefile> exists in the build
+directory, but F<Makefile.PL> does not exist in the source directory.
+
+=back
+
+=cut
 sub build {
 	my $this=shift;
 	$this->doit_in_builddir($this->{makecmd}, @_);
 }
 
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Try to C<make> either I<test> or I<check> target (the first existing one) with
+working directory changed to the build directory.
+
+=item I<Auto-selection>
+
+If either F<Makefile>, F<makefile> or F<GNUmakefile> exists in the build
+directory, but F<Makefile.PL> does not exist in the source directory.
+
+=back
+
+=cut
 sub test {
 	my $this=shift;
 	$this->make_first_existing_target(['test', 'check'], @_);
 }
 
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Try to run C<make install DESTDIR=$destdir> with working directory changed to
+the build directory. $desdir is the path to the appropriate temporary
+installation directory under debian/ (see L<dh_auto_install(1)>).
+
+=item I<Auto-selection>
+
+If either F<Makefile>, F<makefile> or F<GNUmakefile> exists in the build
+directory, but F<Makefile.PL> does not exist in the source directory.
+
+=back
+
+=cut
 sub install {
 	my $this=shift;
 	my $destdir=shift;
 	$this->make_first_existing_target(['install'], "DESTDIR=$destdir", @_);
 }
 
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+When building in source, try to C<make> either I<distclean>, I<realclean> or
+I<clean> target (the first existing one) in the source directory. When building
+out of source tree, recursively remove the whole build directory.
+
+=item I<Auto-selection>
+
+If either F<Makefile>, F<makefile> or F<GNUmakefile> exists in the build
+directory, but F<Makefile.PL> does not exist in the source directory.
+
+=back
+
+=cut
 sub clean {
 	my $this=shift;
 	if (!$this->rmdir_builddir()) {
@@ -92,4 +212,15 @@ sub clean {
 	}
 }
 
+=head1 SEE ALSO
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/perl_build.pm b/Debian/Debhelper/Buildsystem/perl_build.pm
index 3567cb1a..26210152 100644
--- a/Debian/Debhelper/Buildsystem/perl_build.pm
+++ b/Debian/Debhelper/Buildsystem/perl_build.pm
@@ -6,6 +6,32 @@
 
 package Debian::Debhelper::Buildsystem::perl_build;
 
+=head1 NAME
+
+B<perl_build> - Perl Module::Build (Build.PL)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<perl_build>] ...
+
+=head1 DESCRIPTION
+
+Module::Build is a system for building, testing, and installing Perl modules.
+It does not require a C<make> on your system - most of the Module::Build code is
+pure-perl and written in a very cross-platform way. Its only prerequisites are
+modules that are included with perl 5.6.0. Typically, Module::Build build system
+can be identified by presence of the F<Build.PL> script in the source
+directory.
+
+=head1 DH_AUTO NOTES
+
+Out of source tree building is not supported. C<MODULEBUILDRC=/dev/null>
+environment variable is exported in each building step.
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use base 'Debian::Debhelper::Buildsystem';
 
@@ -37,31 +63,128 @@ sub new {
 	return $this;
 }
 
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build.PL> passing C<installdirs=vendor> parameter by default.
+Environment variable C<PERL_MM_USE_DEFAULT> is set before running the script.
+
+=item I<Auto-selection>
+
+If F<configure>, F<Makefile.PL>, F<setup.py> do not exist, but F<Build.PL>
+exists in the source directory.
+
+=back
+
+=cut
 sub configure {
 	my $this=shift;
 	$ENV{PERL_MM_USE_DEFAULT}=1;
 	$this->do_perl("Build.PL", "installdirs=vendor", @_);
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build>.
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile>, F<GNUmakefile> (build directory) and F<setup.py>
+(source directory) do not exist, but F<Build.PL> and F<Build> files exist in
+the source directory.
+
+=back
+
+=cut
 sub build {
 	my $this=shift;
 	$this->do_perl("Build", @_);
 }
 
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build test>.
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile>, F<GNUmakefile> (build directory) and F<setup.py>
+(source directory) do not exist, but F<Build.PL> and F<Build> files exist in
+the source directory.
+
+=back
+
+=cut
 sub test {
 	my $this=shift;
 	$this->do_perl("Build", "test", @_);
 }
 
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build install destdir=$destdir create_packlist=0>. $destdir is
+the path to the temporary installation directory (see L<dh_auto_install(1)>).
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile>, F<GNUmakefile> (build directory) and F<setup.py>
+(source directory) do not exist, but F<Build.PL> and F<Build> files exist in
+the source directory.
+
+=back
+
+=cut
 sub install {
 	my $this=shift;
 	my $destdir=shift;
 	$this->do_perl("Build", "install", "destdir=$destdir", "create_packlist=0", @_);
 }
 
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build --allow_mb_mismatch 1 distclean>.
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile>, F<GNUmakefile> (build directory) and F<setup.py>
+(source directory) do not exist, but F<Build.PL> and F<Build> files exist in
+the source directory.
+
+=back
+
+=cut
 sub clean {
 	my $this=shift;
 	$this->do_perl("Build", "--allow_mb_mismatch", 1, "distclean", @_);
 }
 
+=head1 SEE ALSO
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/perl_makemaker.pm b/Debian/Debhelper/Buildsystem/perl_makemaker.pm
index 07a827ac..102e23f5 100644
--- a/Debian/Debhelper/Buildsystem/perl_makemaker.pm
+++ b/Debian/Debhelper/Buildsystem/perl_makemaker.pm
@@ -6,6 +6,29 @@
 
 package Debian::Debhelper::Buildsystem::perl_makemaker;
 
+=head1 NAME
+
+B<perl_makemaker> - Perl ExtUtils::MakeMaker (Makefile.PL)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<perl_makemaker>] ...
+
+=head1 DESCRIPTION
+
+Perl ExtUtils::MakeMaker utility is designed to write a Makefile for an
+extension module from a Makefile.PL (at configure step). The rest of build
+process is handled by C<make>. Typically, ExtUtils::MakeMaker build system can
+be identified by presence of the F<Makefile.PL> script in the source directory.
+
+=head1 DH_AUTO NOTES
+
+Out of source tree building is not supported.
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use base 'Debian::Debhelper::Buildsystem::makefile';
 
@@ -42,6 +65,24 @@ sub new {
 	return $this;
 }
 
+=head2 Configure step
+
+=over
+
+=item I<Behaviour>
+
+Execute C<Makefile.PL> script passing C<INSTALLDIRS=vendor> and
+C<create_packlist=0> parameters. Environment variables C<PERL_MM_USE_DEFAULT=1>
+and C<PERL_AUTOINSTALL=--skipdeps> are exported before running the script.
+
+=item I<Auto-selection>
+
+If F<Makefile.PL> file exists but F<configure> does not exist in the source
+directory.
+
+=back
+
+=cut
 sub configure {
 	my $this=shift;
 	# If set to a true value then MakeMaker's prompt function will
@@ -55,10 +96,87 @@ sub configure {
 	    @_);
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make> in the build directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+Both F<Makefile.PL> and F<Makefile> exist in the source directory.
+
+=back
+
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make test> in the source directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+Both F<Makefile.PL> and F<Makefile> exist in the source directory.
+
+=back
+
+=cut
+
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make install DESTDIR=$destdir PREFIX=/usr> in the source directory
+with $destdir set to the appropriate temporary installation directory. See
+I<makefile> build system documentation for more information.
+
+=item I<Auto-selection>
+
+Both F<Makefile.PL> and F<Makefile> exist in the source directory.
+
+=back
+
+=cut
 sub install {
 	my $this=shift;
 	my $destdir=shift;
 	$this->SUPER::install($destdir, "PREFIX=/usr", @_);
 }
 
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make distclean> in the source directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+Both F<Makefile.PL> and F<Makefile> exist in the source directory.
+
+=back
+
+=head1 SEE ALSO
+
+L<dh_auto_makefile(7)>
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/python_distutils.pm b/Debian/Debhelper/Buildsystem/python_distutils.pm
index ad4ea877..8266fa0b 100644
--- a/Debian/Debhelper/Buildsystem/python_distutils.pm
+++ b/Debian/Debhelper/Buildsystem/python_distutils.pm
@@ -7,6 +7,37 @@
 
 package Debian::Debhelper::Buildsystem::python_distutils;
 
+=head1 NAME
+
+B<python_distutils> - Python Distutils (setup.py)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<python_distutils>] ...
+
+=head1 DESCRIPTION
+
+Python Distribution Utilities (Distutils for short) is a standard Python build
+system. It is used to package most of the Python modules in the source
+distribution form. Typically, only two steps (build and install) are needed to
+finish installation of the Distutils based Python module. This build system can
+be typically identified by presence of the F<setup.py> in the source directory.
+
+=head1 DH_AUTO NOTES
+
+Out of source tree building is done by default but in source building is also
+supported. PLEASE NOTE that B<default build directory> is B<$srcdir/build>
+where $srcdir is a path to the source directory.
+
+Due to design flaws of Distutils, it is not possible to set a B<custom> build
+directory via command line arguments to F<setup.py>. Therefore, the same effect
+is achieved by writing appropriate F<.pydistutils.cfg> file to the build
+directory and pointing $HOME environment variable to the build directory.
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use Cwd ();
 use Debian::Debhelper::Dh_Lib qw(error);
@@ -81,17 +112,104 @@ sub setup_py {
 	$this->doit_in_sourcedir("python", "setup.py", $act, @_);
 }
 
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Do nothing but stop auto-selection process.
+
+=item I<Auto-selection>
+
+If neither F<configure>, F<Makefile.PL> exist, but F<setup.py> exists in the
+source directory.
+
+=back
+
+=cut
+
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<python setup.py build>.
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile> F<GNUmakefile> do not exist in the build directory
+and F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
 sub build {
 	my $this=shift;
 	$this->setup_py("build", @_);
 }
 
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Do nothing but stop auto-selection process.
+
+=item I<Auto-selection>
+
+F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
+F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
+
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<python setup.py install> passing temporary installation directory via
+C<--root> parameter. C<--no-compile> and C<-O0> parameters are also passed by
+default. See L<dh_auto_install(1)> for more information.
+
+=item I<Auto-selection>
+
+F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
+F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
 sub install {
 	my $this=shift;
 	my $destdir=shift;
 	$this->setup_py("install", "--root=$destdir", "--no-compile", "-O0", @_);
 }
 
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<python setup.py clean -a>. Additional parameters (if specified) are
+passed to the latter command. F<.pydistutils.cfg> is also removed if it was
+created (together with the build directory if it is ends up empty). Finally,
+recursively find and delete all *.pyc files from the source directory.
+
+=item I<Auto-selection>
+
+F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
+F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
 sub clean {
 	my $this=shift;
 	$this->setup_py("clean", "-a", @_);
@@ -106,4 +224,15 @@ sub clean {
 	$this->doit_in_sourcedir('find', '.', '-name', '*.pyc', '-exec', 'rm', '{}', ';');
 }
 
+=head1 SEE ALSO
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/dh_auto.pod b/dh_auto.pod
new file mode 100644
index 00000000..6eb244fb
--- /dev/null
+++ b/dh_auto.pod
@@ -0,0 +1,228 @@
+=head1 NAME
+
+dh_auto - debhelper based package source building suite
+
+=head1 SYNOPTIS
+
+B<dh_auto_*> [B<--buildsystem=>I<buildsystem>] [B<--sourcedirectory=>I<srcdir>] [B<--builddirectory>[=I<builddir>]]
+
+B<dh_auto_*> B<--list> [B<-S>I<buildsystem>] [B<-D>I<srcdir>] [B<-B>[I<builddir>]]
+
+B<dh_auto_*> B<--help-buildsystem> [B<-S>I<buildsystem>] [B<-D>I<srcdir>] [B<-B>[I<builddir>]]
+
+=head1 DESCRIPTION
+
+dh_auto is a family of debhelper programs that are responsible for managing
+build process of the package sources. dh_auto takes a burden of identifying and
+configuring package build system with a standard set of options that a typical
+Debian package needs. However, it is also flexible enough to allow
+customization of the build process in various ways. Due to good defaults, it
+should be able to handle 90% of packages even without any additional arguments
+passed to the dh_auto programs. Therefore, dh_auto is one of the main driving
+forces behind the L<dh(1)> command sequencer. Similarly, dh_auto programs can
+be easily (either fully or partially) integrated into traditional Debian
+packaging.
+
+One of the key dh_auto features is that it wraps around all common source build
+systems and exposes their common features via well-defined command line
+interface of the dh_auto programs. dh_auto is designed that each type of source
+build system is handled by its corresponding I<debhelper build system> which
+translates dh_auto options into the source build system specific details.
+Therefore, dh_auto is capable to handle e.g. out of source tree building
+transparently.
+
+The build process is split into 5 I<building steps>: configure, build, test,
+install and clean. Each step is managed by the respective dh_auto_$step
+program. Each program accepts a set of shared dh_auto options, step specific
+options (if any) and arbitrary number of extra arguments which are additionally
+passed to the underlying build system command being executed. Whatever is
+executed under the hood depends on the selected debhelper build system,
+building step (i.e.  dh_auto program) and dh_auto options in effect.
+
+=head1 DH_AUTO PROGRAMS
+
+=over 2
+
+#DH_AUTO LIST#
+
+=back
+
+=head1 FEATURES
+
+=over 2
+
+=item I<Build system auto-selection>
+
+dh_auto examines package source and/or build directories at each building step
+looking for typical indications of the source build systems it supports. If the
+build system is recognized, its corresponding building step commands are
+executed. If more than one debhelper build system indicates to match the source
+build system, only the first one is selected. If the build system isn't
+recognized, dh_auto program silently succeeds. dh_auto programs may fail only
+if wrong debhelper build system gets selected and/or source build system
+commands fail or cannot be executed.
+
+The auto-selection process implies that a different but compatible debhelper
+build system may be auto-selected at each building step. For example, GNU
+Autoconf is just a configure layer on top of the simple Makefile build system.
+
+=item I<Manual build system selection>
+
+In addition to the build system auto-selection, dh_auto offers a way for a user
+to specify which debhelper build system to assume for the package. In such a
+case, auto-selection is skipped entirely and no prior checks are made before
+executing commands of the specified build system. Obviously, if a wrong build
+system was specified and/or source build system commands failed or could not be
+executed, the dh_auto program would fail too.
+
+Manual build system selection could be useful if package sources came with more
+than one build system, auto-selection fails/gives wrong results due its
+limitations or you want to use a third party debhelper build system (provided
+by an external package (see below)).
+
+=item I<Source tree switching>
+
+Typically, the top directory of the package sources is where the debianization
+directory (debian/) lives. However, sometimes the whole original source tree
+might be somewhere in the subdirectory or a single Debian source package might
+actually contain multiple original source packages with their contents being in
+the separate subdirectories. dh_auto handles such cases by letting the user to
+specify a path to the source directory. All dh_auto programs regardless of the
+build system selected support source directory switching.
+
+=item I<Out of source tree building>
+
+Throughout the build process of the most packages, lots of temporary files are
+generated by their source build systems. Since they are of no use when binary
+packages are built, it is a task of L<dh_auto_clean(1)> to clean them up.  If
+temporary files are generated in the same directories where source files are,
+it is referred as "in source building" in this documentation. However, some
+build systems support the concept of "out of source tree" building when all
+temporary files are generated in the arbitrary build directory avoiding
+extensive pollution of the source tree. dh_auto allows to specify a path to the
+build directory and then it will do out of source tree building in it if the
+source build system supports this feature.
+
+In source building is a default mode and it is supported by most debhelper
+build systems. However, some source build systems do not support in source
+building or highly recommend out of source tree building. In this case, dh_auto
+follows the recommendation and might default to the out of source tree building
+even if the build directory was not explicitly specified. However, if the build
+system does not support out of source tree building, it is an error to specify
+the build directory.
+
+=item I<Third party debhelper build systems>
+
+It is very easy to write a third party debhelper build system class and ship it
+in the external package. The only limitation is that support for it can only be
+enabled manually (via "Manual build system selection"). Their auto-selection is
+not allowed in order to keep the process stable under various system
+configurations (i.e. when different sets of third party debhelper build systems
+are installed). However, the user can always discover all default and third
+party debhelper build systems supported on the system by passing the L<--list>
+option to any dh_auto program.
+
+=back
+
+Read section L</"DH_AUTO SHARED OPTIONS"> for more details how to enable the
+features listed above.
+
+=head1 SUPPORTED BUILD SYSTEMS
+
+dh_auto provides support for the most popular build systems out of the box
+(listed below). See section L</"DEBHELPER BUILD SYSTEM DETAILS"> for more
+information how each build system is auto-selected and what commands are
+executed to complete each building step. To get information about a third party
+debhelper build system installed on your system, use I<--help-buildsystem>
+option.
+
+#SUPPORTED BUILD SYSTEMS#
+
+=head1 #SUPPORTED BUILD SYSTEMS INTRO FOR DH_AUTO PROGRAMS
+
+Below you will find a list of the debhelper build systems that are shipped with
+debhelper itself along with their details concerning this building step. They
+are listed in the order of auto-selection preference. Consult
+L<dh_auto_$buildsystem(7)> or L</"DEBHELPER BUILD SYSTEM DETAILS"> section of
+L<dh_auto(7)>, or use L<--help--buildsystem> option for a more complete
+reference about each build system.
+
+=head1 DH_AUTO SHARED OPTIONS
+
+=over 4
+
+=item B<--buildsystem=>I<buildsystem>, B<-S>I<buildsystem>
+
+Select the specified debhelper I<buildsystem> instead of trying to auto-select
+one which might be applicable for the package. I<buildsystem> specific commands
+will be executed to complete a building step without any prior checks. This
+option is also the only way to select a third party debhelper build system.
+
+=item B<--sourcedirectory>=I<directory>, B<-D>I<directory>
+
+Assume that the original package source tree is at the specified I<directory>
+rather than the top level directory of the Debian source package tree (C<.>).
+I<directory> path is assumed to be relative to the top level directory (where
+debian/ is) and must exist.
+
+=item B<--builddirectory>=[I<directory>], B<-B>[I<directory>]
+
+Enable out of source building and use the specified I<directory> as the build
+directory. If specified, I<directory> must be relative to the top level
+directory of the Debian source package tree and generally does not need to
+exist before the build process is started. If I<directory> parameter is
+omitted, default build directory will be used. It is S<C<obj-`dpkg_architecture
+-qDEB_BUILD_GNU_TYPE`>> by default but any debhelper build system can choose
+another value (see documentation of the debhelper build systems).
+
+If this option is not specified, building will be done in source by default
+unless the selected build system enforces/prefers out of source tree building.
+In such a case, the default build directory will be used even if
+L<--builddirectory> is not specified. If the selected build system just prefers
+out of source tree building but still allows in source building, the latter can
+be re-enabled by passing a build directory path that is equal to the source
+directory path.
+
+=item B<--list>, B<-l>
+
+List all debhelper build systems available on this system and exit. The list
+includes both default (listed first in the auto-selection order) and third
+party build systems (clearly marked as such). The list is concluded with the
+information about which build system would be auto-selected to complete the
+building step or which one is manually specified with the I<--buildsystem>
+option.
+
+=item B<--help-buildsystem>
+
+Print detailed help about a build system which would be auto-selected or which
+is manually specified with the L<--buildsystem> option. Exit immediately
+afterwards.
+
+=back
+
+=head1 DEBHELPER BUILD SYSTEM DETAILS
+
+This section provides more information about debhelper build systems supported
+by default. They are listed in the order of auto-selection preference. The
+first build system that matches auto-selection criteria is always selected and
+the following ones are not even considered. Auto-selection conditions might
+differ at each building step even for the same debhelper build system.
+
+#BUILD SYSTEM DETAILS#
+
+=head1 SEE ALSO
+
+L<debhelper(7)>
+
+=over 2
+
+=item B<Default debhelper build systems>
+
+#BUILD SYSTEM MAN LIST#
+
+=back
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
diff --git a/dh_auto_build b/dh_auto_build
index 56b9b5f0..d16694cf 100755
--- a/dh_auto_build
+++ b/dh_auto_build
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_auto_build - automatically builds a package
+dh_auto_build - build package sources
 
 =cut
 
@@ -11,18 +11,21 @@ use Debian::Debhelper::Dh_Buildsystems;
 
 =head1 SYNOPSIS
 
-B<dh_auto_build> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_build> [S<I<debhelper options>>] [S<I<dh_auto options>>] [S<B<--> I<params>>]
 
 =head1 DESCRIPTION
 
-dh_auto_build is a debhelper program that tries to automatically
-build a package. If a Makefile is found, this is done by running make (or
-MAKE, if the environment variable is set).
-If there's a setup.py, or Build.PL, it is run to build the package.
+dh_auto_build is a debhelper program that is responsible for the I<build> step
+of the L<dh_auto(7)> building process. Typically, this is the point when
+package sources are compiled into binaries or otherwise transformed into ready
+to use format. Files produced throughout this step are put to the build
+directory.
 
-This is intended to work for about 90% of packages. If it doesn't work,
-you're encouraged to skip using dh_auto_build at all, and just run the
-build process manually.
+You can pass additional parameters via I<params>. However, if dh_auto_build
+does not meet your needs or does not work, it is safe to skip/override it
+entirely and build the package with custom commands.
+
+#DH_AUTO SHARED OPTIONS#
 
 =head1 OPTIONS
 
@@ -35,6 +38,11 @@ or override any standard parameters that dh_auto_build passes.
 
 =back
 
+=head1 SUPPORTED BUILD SYSTEMS
+
+#SUPPORTED BUILD SYSTEMS INTRO#
+#SUPPORTED BUILD SYSTEMS LIST#
+
 =cut
 
 buildsystems_init();
@@ -42,12 +50,16 @@ buildsystems_do();
 
 =head1 SEE ALSO
 
+L<dh_auto(7)>
+
 L<debhelper(7)>
 
-This program is a part of debhelper.
+This program is a part of debhelper and its dh_auto package source building
+suite.
 
 =head1 AUTHOR
 
-Joey Hess <joeyh@debian.org>
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
 
 =cut
diff --git a/dh_auto_clean b/dh_auto_clean
index 1b7d46cd..625675b8 100755
--- a/dh_auto_clean
+++ b/dh_auto_clean
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_auto_clean - automatically cleans up after a build
+dh_auto_clean - clean temporary files after building package sources
 
 =cut
 
@@ -11,19 +11,21 @@ use Debian::Debhelper::Dh_Buildsystems;
 
 =head1 SYNOPSIS
 
-B<dh_auto_clean> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_clean> [S<I<debhelper options>>] [S<I<dh_auto options>>] [S<B<--> I<params>>]
 
 =head1 DESCRIPTION
 
-dh_auto_clean is a debhelper program that tries to automatically clean up
-after a package build. If there's a Makefile and it contains a "distclean",
-"realclean", or "clean" target, then this is  done by running make (or MAKE,
-if the environment variable is set). If there is a setup.py or Build.PL, it
-is run to clean the package.
+dh_auto_clean is a debhelper program that is responsible for the I<clean> step
+of the L<dh_auto(7)> building process. It tries to automatically clean up after
+a package build by removing all temporary files from the build directory or
+even the build directory itself as appropriate. dh_auto_clean will fail only if
+the source build system clean routine fails. However, if the latter does not
+exist or there is nothing to clean it will exit with zero status doing nothing.
 
-This is intended to work for about 90% of packages. If it doesn't work, or
-tries to use the wrong clean target, you're encouraged to skip using
-dh_auto_clean at all, and just run make clean manually.
+If dh_auto_clean does not meet your needs or does not work, it is safe to
+skip/override it entirely and just run clean up manually.
+
+#DH_AUTO SHARED OPTIONS#
 
 =head1 OPTIONS
 
@@ -36,6 +38,11 @@ or override the any standard parameters that dh_auto_clean passes.
 
 =back
 
+=head1 SUPPORTED BUILD SYSTEMS
+
+#SUPPORTED BUILD SYSTEMS INTRO#
+#SUPPORTED BUILD SYSTEMS LIST#
+
 =cut
 
 buildsystems_init();
@@ -43,12 +50,15 @@ buildsystems_do();
 
 =head1 SEE ALSO
 
+L<dh_auto(7)>
+
 L<debhelper(7)>
 
-This program is a part of debhelper.
+This program is a part of debhelper and its dh_auto package source building suite.
 
-=head1 AUTHOR
+=head1 AUTHORS
 
-Joey Hess <joeyh@debian.org>
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
 
 =cut
diff --git a/dh_auto_configure b/dh_auto_configure
index 34d6298a..3f326cef 100755
--- a/dh_auto_configure
+++ b/dh_auto_configure
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_auto_configure - automatically configure a package prior to building
+dh_auto_configure - configure and prepare package sources for building
 
 =cut
 
@@ -11,19 +11,25 @@ use Debian::Debhelper::Dh_Buildsystems;
 
 =head1 SYNOPSIS
 
-B<dh_auto_configure> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_configure> [S<I<debhelper options>>] [S<I<dh_auto options>>] [S<B<--> I<params>>]
 
 =head1 DESCRIPTION
 
-dh_auto_configure is a debhelper program that tries to automatically
-configure a package prior to building. It looks for and runs a ./configure
-script, Makefile.PL, Build.PL, or cmake. A standard set of parameters is
-determined and passed to the program that is run. If no program to run is
-found, dh_auto_configure will exit without doing anything.
+dh_auto_configure is a debhelper program that is responsible for the
+I<configure> step of the L<dh_auto(7)> building process. Since I<configure> is
+the first step, typically it is the point when build configuration options
+are set, system settings are detected and various build system specific
+temporary files are pre-generated in the build directory. Some simpler build
+systems do not need this step. In such a case, dh_auto_configure silently
+succeeds without doing anything.
 
-This is intended to work for about 90% of packages. If it doesn't work,
-you're encouraged to skip using dh_auto_configure at all, and just run
-./configure or its equivalent manually.
+dh_auto_configure usually pre-configures the source build system with a set of
+standard options which most Debian packages need to set anyway. Custom options
+can be passed as I<params>. If dh_auto_configure does not meet your needs or
+does not work, it is safe to skip/override it entirely and just run a configure
+script or its equivalent manually.
+
+#DH_AUTO SHARED OPTIONS#
 
 =head1 OPTIONS
 
@@ -31,7 +37,7 @@ you're encouraged to skip using dh_auto_configure at all, and just run
 
 =item B<--> I<params>
 
-Pass "params" to the program that is run, after the standard
+Pass I<params> to the command that is run, after the standard
 parameters that dh_auto_configure passes. This can be used to supplement
 or override those parameters. For example:
 
@@ -39,6 +45,11 @@ or override those parameters. For example:
 
 =back
 
+=head1 SUPPORTED BUILD SYSTEMS
+
+#SUPPORTED BUILD SYSTEMS INTRO#
+#SUPPORTED BUILD SYSTEMS LIST#
+
 =cut
 
 buildsystems_init();
@@ -46,12 +57,16 @@ buildsystems_do();
 
 =head1 SEE ALSO
 
+L<dh_auto(7)>
+
 L<debhelper(7)>
 
-This program is a part of debhelper.
+This program is a part of debhelper and its dh_auto package source building
+suite.
 
-=head1 AUTHOR
+=head1 AUTHORS
 
-Joey Hess <joeyh@debian.org>
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
 
 =cut
diff --git a/dh_auto_install b/dh_auto_install
index db2c6e90..5c772245 100755
--- a/dh_auto_install
+++ b/dh_auto_install
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_auto_install - automatically runs make install or similar
+dh_auto_install - install built files into the temporary directory under debian/
 
 =cut
 
@@ -13,14 +13,15 @@ use Cwd;
 
 =head1 SYNOPSIS
 
-B<dh_auto_install> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_install> [S<I<debhelper options>>] [S<I<dh_auto options>>] [S<B<--> I<params>>]
 
 =head1 DESCRIPTION
 
-dh_auto_install is a debhelper program that tries to automatically install
-built files. If there's a Makefile and it contains a "install" target,
-then this is done by running make (or MAKE, if the environment variable is
-set). If there is a setup.py or Build.PL, it is used.
+dh_auto_install is a debhelper program that is responsible for the I<install>
+step of the L<dh_auto(7)> building process. dh_auto_install tries to run
+original package installation routine to install built files into the proper
+places of the file system hierarchy recreated under the (temporary) directory
+in debian/.
 
 The files are installed into debian/<package>/ if there is only one binary
 package. In the multiple binary package case, the files are instead
@@ -28,13 +29,10 @@ installed into debian/tmp/, and should be moved from there to the
 appropriate package build directory using L<dh_install(1)> or
 L<dh_movefiles(1)>.
 
-DESTDIR is used to tell make where to install the files. 
-If the Makefile was generated by MakeMaker from a Makefile.PL, it will
-automatically set PREFIX=/usr too, since such Makefiles need that.
+If dh_auto_install does not meet your needs or does not work, it is safe to
+skip/override it entirely and just run C<make install> or the like manually.
 
-This is intended to work for about 90% of packages. If it doesn't work, or
-tries to use the wrong install target, you're encouraged to skip using
-dh_auto_install at all, and just run make install manually.
+#DH_AUTO SHARED OPTIONS#
 
 =head1 OPTIONS
 
@@ -47,6 +45,11 @@ or override the any standard parameters that dh_auto_install passes.
 
 =back
 
+=head1 SUPPORTED BUILD SYSTEMS
+
+#SUPPORTED BUILD SYSTEMS INTRO#
+#SUPPORTED BUILD SYSTEMS LIST#
+
 =cut
 
 buildsystems_init();
@@ -65,12 +68,16 @@ buildsystems_do("install", $destdir);
 
 =head1 SEE ALSO
 
+L<dh_auto(7)>
+
 L<debhelper(7)>
 
-This program is a part of debhelper.
+This program is a part of debhelper and its dh_auto package source building
+suite.
 
-=head1 AUTHOR
+=head1 AUTHORS
 
-Joey Hess <joeyh@debian.org>
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
 
 =cut
diff --git a/dh_auto_test b/dh_auto_test
index e68bf09a..062563fd 100755
--- a/dh_auto_test
+++ b/dh_auto_test
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_auto_test - automatically runs a package's test suites
+dh_auto_test - run package test suites after building
 
 =cut
 
@@ -11,20 +11,26 @@ use Debian::Debhelper::Dh_Buildsystems;
 
 =head1 SYNOPSIS
 
-B<dh_auto_test> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_test> [S<I<debhelper options>>] [S<I<dh_auto options>>] [S<B<--> I<params>>]
 
 =head1 DESCRIPTION
 
-dh_auto_test is a debhelper program that tries to automatically run a
-package's test suite. If there's a Makefile and it contains a "test"
-or "check" target, then this is  done by running make (or MAKE, if the
-environment variable is set). If the test suite fails, the command will
-exit nonzero. If there's no test suite, it will exit zero without doing
-anything.
+dh_auto_test is a debhelper program that is responsible for the I<test> step of
+the L<dh_auto(7)> building process. Typically, this is the point when package
+test suite is run to check if the sources were built successfully and/or
+binaries provide expected functionality. dh_auto_test will fail if test suite
+fails.  However, if there's no test suite, it will exit with zero status
+without doing anything.
 
-This is intended to work for about 90% of packages with a test suite. If it
-doesn't work, you're encouraged to skip using dh_auto_test at all, and
-just run the test suite manually.
+If dh_auto_test does not meet your needs or does not work, it is safe to
+skip/override it entirely and just run the test suite manually.
+
+=head1 NOTES
+
+If the DEB_BUILD_OPTIONS environment variable contains "nocheck", no tests will
+be performed.
+
+#DH_AUTO SHARED OPTIONS#
 
 =head1 OPTIONS
 
@@ -37,10 +43,10 @@ or override the any standard parameters that dh_auto_test passes.
 
 =back
 
-=head1 NOTES
+=head1 SUPPORTED BUILD SYSTEMS
 
-If the DEB_BUILD_OPTIONS environment variable contains "nocheck", no
-tests will be performed.
+#SUPPORTED BUILD SYSTEMS INTRO#
+#SUPPORTED BUILD SYSTEMS LIST#
 
 =cut
 
@@ -53,12 +59,16 @@ buildsystems_do();
 
 =head1 SEE ALSO
 
+L<dh_auto(7)>
+
 L<debhelper(7)>
 
-This program is a part of debhelper.
+This program is a part of debhelper and its dh_auto package source building
+suite.
 
-=head1 AUTHOR
+=head1 AUTHORS
 
-Joey Hess <joeyh@debian.org>
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
 
 =cut
diff --git a/man/dh_auto_pod b/man/dh_auto_pod
new file mode 100755
index 00000000..01817b23
--- /dev/null
+++ b/man/dh_auto_pod
@@ -0,0 +1,288 @@
+#!/usr/bin/perl -w
+
+package CommandStrip;
+use base Pod::Parser;
+
+sub command {
+	my $parser=shift;
+	if (!exists $parser->{_stripped_}) {
+		$parser->{_stripped_} = 1;
+		return;
+	}
+	return $parser->SUPER::command(@_);
+}
+
+package main;
+
+use strict;
+use warnings;
+use Debian::Debhelper::Dh_Lib;
+use Debian::Debhelper::Dh_Buildsystems;
+use Pod::Select;
+use IO::String;
+use File::Spec;
+use Pod::InputObjects;
+
+my @buildsystem_pods;
+my $DH_AUTO_POD = "dh_auto.pod";
+
+# Preloads build system PODs
+sub get_buildsystem_pods {
+	my $parser = new Pod::Select();
+	if (!@buildsystem_pods) {
+		my @buildsystems = load_all_buildsystems([ "." ]);
+		for my $system (@buildsystems) {
+			my $podfile = File::Spec->catfile("Debian/Debhelper/Buildsystem", $system->NAME() . ".pm");
+			my $iostr = new IO::String();
+
+			open(my $fh, $podfile) or error("Unable to read $podfile");
+			$system->{pod_fh} = $fh;
+
+			# Extract build system name from POD
+			$parser->select('NAME');
+			strip_first_command($parser, $fh, $iostr);
+
+			# Remove empty lines and join new lines
+			$system->{pod_name} = join(" ", grep ! /^\s*$/, split(/\n/, ${$iostr->string_ref()}));
+
+			push @buildsystem_pods, $system;
+		}
+	}
+	return @buildsystem_pods;
+}
+
+# Strips the first command (i.e. line starting with =), prints
+# everything else
+sub strip_first_command {
+	my ($parser, $input_fh, $output_fh)=@_;
+
+	my $iostr = new IO::String();
+	seek(\*$input_fh, 0, 0);
+	$parser->parse_from_filehandle($input_fh, $iostr);
+	$iostr->pos(0);
+	CommandStrip->new()->parse_from_filehandle($iostr, $output_fh);
+	$iostr->close();
+}
+
+# Prints everything
+sub print_everything {
+	my ($parser, $input_fh, $output_fh)=@_;
+	seek(\*$input_fh, 0, 0);
+	$parser->parse_from_filehandle($input_fh, $output_fh);
+}
+
+# Prints POD paragraph
+# Common parameters -name, -text. Results into =${-name} ${-text}
+sub print_pod_parag {
+	my %args=@_;
+	my $output_fh = $args{output} || \*STDOUT;
+	print $output_fh Pod::Paragraph->new(@_)->raw_text(), "\n\n";
+}
+
+#sub unique_authors {
+#	my ($authors, $parser, $fh)=@_;
+#	my $iostr = new IO::String();
+
+#	$parser->select('AUTHOR[^\s]*');
+#	seek(\*$fh, 0, 0);
+#	strip_first_command($parser, $fh, $iostr);
+#	$iostr->pos(0);
+#	while (my $author = <$iostr>) {
+#		$author =~ s/\s+/ /g;
+#		$author =~ s/^\s+//;
+#		$author =~ s/\s+$//;
+#		$authors->{$author} = scalar(keys %$authors)
+#		    if !exists $authors->{$author};
+#	}
+#	$iostr->close();
+#}
+
+############# Generation of dh_auto_step POD #############
+
+sub get_dh_auto_shared_options_for_step {
+	my $step=shift;
+	my $parser = new Pod::Select();
+	my $iostr = new IO::String();
+
+	$parser->select('DH_AUTO SHARED OPTIONS');
+	print_everything($parser, \*DH_AUTO, $iostr);
+	return ${$iostr->string_ref()};
+}
+
+sub get_supported_buildsystems_intro_for_step {
+	my $step=shift;
+	my $parser = new Pod::Select();
+	my $iostr = new IO::String();
+
+	# A common "SUPPORTED BUILD SYSTEMS" dh_auto POD 
+	$parser->select('#SUPPORTED BUILD SYSTEMS INTRO FOR DH_AUTO PROGRAMS');
+	strip_first_command($parser, \*DH_AUTO, $iostr);
+	return ${$iostr->string_ref()};
+}
+
+sub get_supported_buildsystems_list_for_step {
+	my $step=shift;
+	my $parser = new Pod::Select();
+	my $iostr = new IO::String();
+
+	# Append build system list from build system PODs
+	for my $bs (get_buildsystem_pods()) {
+		my $bs_fh = $bs->{pod_fh};
+
+		# =head2 Build system name
+		print_pod_parag(output => $iostr, -name => 'head2', -text => $bs->{pod_name});
+
+		# Now print DH_AUTO NOTES
+		$parser->select('DH_AUTO NOTES');
+		strip_first_command($parser, $bs_fh, $iostr);
+
+		# And step specific help follows
+		$parser->select('BUILD PROCESS/' . ucfirst($step) . " step");
+		strip_first_command($parser, $bs_fh, $iostr);
+	}
+	return ${$iostr->string_ref()};
+}
+
+sub generate_step_pod {
+	my $step=shift;
+	$step = $1 if ($step =~ /dh_auto_(.*)$/);
+
+	my $dh_auto_step = "dh_auto_$step";
+	my $dh_auto_shared_options = get_dh_auto_shared_options_for_step($step);
+	my $supported_bs_intro = get_supported_buildsystems_intro_for_step($step);
+	my $supported_bs_list = get_supported_buildsystems_list_for_step($step);
+	open(DH_AUTO_STEP, "podselect $dh_auto_step |")
+	    or error("Unable to read $dh_auto_step");
+	while (<DH_AUTO_STEP>) {
+		s/#DH_AUTO SHARED OPTIONS#/$dh_auto_shared_options/;
+		s/#SUPPORTED BUILD SYSTEMS INTRO#/$supported_bs_intro/;
+		s/#SUPPORTED BUILD SYSTEMS LIST#/$supported_bs_list/;
+		print $_;
+	}
+	close DH_AUTO_STEP;
+}
+
+############# Generation of dh_auto POD #############
+
+sub get_dh_auto_program_list_for_dh_auto {
+	my @steps=@_;
+	my $parser = new Pod::Select();
+	my $collect = "";
+
+	$parser->select('NAME');
+	foreach my $step (@steps) {
+		my $iostr = new IO::String();
+		open (my $fh, "dh_auto_$step") or die "$_: $!";
+		strip_first_command($parser, $fh, $iostr);
+		close $fh;
+		if (${$iostr->string_ref()} =~ /^(.*?) - (.*)/) {
+			$collect .= "=item $1(1)\n\n$2\n\n";
+		}
+	}
+	return $collect;
+}
+
+sub get_supported_buildsystems_for_dh_auto {
+	my $parser = new Pod::Select();
+	my $iostr = new IO::String();
+
+	# Build system list from build system PODs (NAME + DESCRIPTION)
+	for my $bs (sort { $a->NAME() cmp $b->NAME() } get_buildsystem_pods()) {
+		my $bs_fh = $bs->{pod_fh};
+
+		# =head2 Build system name
+		print_pod_parag(output => $iostr, -name => 'head2', -text => $bs->{pod_name});
+
+		$parser->select('DESCRIPTION');
+		strip_first_command($parser, $bs_fh, $iostr);
+	}
+	return ${$iostr->string_ref()};
+}
+
+sub get_buildsystem_details_for_dh_auto {
+	my @steps=@_;
+	my $parser = new Pod::Select();
+	my $iostr = new IO::String();
+
+	# Build system details from build system PODs
+	for my $bs (get_buildsystem_pods()) {
+		my $bs_fh = $bs->{pod_fh};
+
+		print_pod_parag(output => $iostr, -name => 'head2', -text => $bs->NAME());
+
+		# Now print DH_AUTO NOTES
+		$parser->select('DH_AUTO NOTES');
+		strip_first_command($parser, $bs_fh, $iostr);
+
+		# And step specific documentation
+		for my $step (@steps) {
+			$parser->select('BUILD PROCESS/' . ucfirst($step) . " step");
+			print_pod_parag(output => $iostr, -name => 'head3', -text => 'B<' . ucfirst($step) . " step>");
+			strip_first_command($parser, $bs_fh, $iostr);
+		}
+	}
+	return ${$iostr->string_ref()};
+}
+
+sub get_dh_auto_program_man_list_for_dh_auto {
+	return join("\n\n", map { "L<dh_auto_$_(1)>" } @_);
+}
+
+sub get_buildsystem_man_list_for_dh_auto {
+	return join("\n\n", map { "L<dh_auto_" . $_->NAME() . "(7)>" } get_buildsystem_pods());
+}
+
+sub generate_dh_auto_pod {
+	my @steps=@_;
+	my $parser = new Pod::Select();
+	my $iostr = new IO::String();
+	
+	my $dh_auto_list = get_dh_auto_program_list_for_dh_auto(@steps);
+	my $supported_bs = get_supported_buildsystems_for_dh_auto(@steps);
+	my $bs_details = get_buildsystem_details_for_dh_auto(@steps);
+	my $dh_auto_man_list = get_dh_auto_program_man_list_for_dh_auto(@steps);
+	my $bs_man_list = get_buildsystem_man_list_for_dh_auto();
+
+	# Filter out all sections starting with #
+	$parser->select('[^#].*');
+	print_everything($parser, \*DH_AUTO, $iostr);
+	
+	seek(\*$iostr, 0, 0);
+	while (<$iostr>) {
+		s/#DH_AUTO LIST#/$dh_auto_list/;
+		s/#SUPPORTED BUILD SYSTEMS#/$supported_bs/;
+		s/#BUILD SYSTEM DETAILS#/$bs_details/;
+		s/#DH_AUTO MAN LIST#/$dh_auto_man_list/;
+		s/#BUILD SYSTEM MAN LIST#/$bs_man_list/;
+		print $_;
+	}
+	$iostr->close();
+}
+
+############# Entry point #############
+
+my @args;
+my $outfile;
+foreach (@ARGV) {
+	if (/^-o(.*)/) {
+		$outfile = $1;
+	}
+	else {
+		push @args, $_;
+	}
+}
+
+if ($outfile) {
+	open(OUTFILE, ">", $outfile) or die "Unable to open output file $outfile";
+	open(STDOUT, ">&OUTFILE") or die "Unable to redirect standard output";
+}
+
+open(DH_AUTO, $DH_AUTO_POD) or error("Unable to read $DH_AUTO_POD");
+if (@args > 0) {
+	generate_step_pod(@args);
+}
+else {
+	generate_dh_auto_pod(qw(configure build test install clean));
+}
+close DH_AUTO;
+close OUTFILE if $outfile;