Update dh_auto documentation.

* dh_auto.pod -> dh_auto.7 - contains general information about dh_auto,
  its features, build systems supported by default (the latter is injected by
  man/dh_auto_pod script from Debian/Debhelper/Buildsystem/*.pm PODs via
  placeholders (#PLACEHOLDER#))
* POD in Debian/Debhelper/Buildsystem/*.pm -> dh_auto_<buildsystem>.7 - build
  system specific information.
* dh_auto_* -> dh_auto_*.1 - relatively shorty description of the specific
  dh_auto_* program and build system specific info for that step injected from
  Debian/Debhelper/Buildsystem/*.pm with man/dh_auto_pod script.
* man/dh_auto_pod $step - generates full dh_auto_$step POD (replaces
  placeholders).
* man/dh_auto_pod - generates full dh_auto.pod (replaces placeholders).

Signed-off-by: Modestas Vainius <modestas@vainius.eu>

1 files changed, 132 insertions, 0 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;