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, 228 insertions, 0 deletions

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>