docs: Libtool configuration diagram.

[Ralf Wildenhues]

Ethan suggested we have a Libtool flow chart, similar to how Automake
has one in its manual.

Here we go.  OK to commit?

Thanks,
Ralf

    docs: Libtool configuration diagram.
    
    * doc/libtool.texi (Integrating libtool): Add diagrams
    explaining the dependencies between Libtool files.
    Suggestion by Ethan Mallove.

diff --git a/doc/libtool.texi b/doc/libtool.texi
index 12d006b..04c5507 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -1791,6 +1791,56 @@ The remaining @var{mode-args} are either flags for the 
deletion program
 This chapter describes how to integrate libtool with your packages so
 that your users can install hassle-free shared libraries.
 
+There are several ways in which Libtool may be integrated in your
+package, described in the following sections.  Typically, the Libtool
+macro files as well as @file{ltmain.sh} are copied into your package
+using @command{libtoolize} and @command{aclocal} after setting up the
address@hidden and toplevel @file{Makefile.am}, then
address@hidden adds the needed tests to the @file{configure} script.
+These individual steps are often automated with @command{autoreconf}.
+
+Here is a diagram showing how such a typical Libtool configuration works
+when preparing a package for distribution, assuming that @file{m4} has
+been chosen as location for additional Autoconf macros, and
address@hidden as location for auxiliary build tools (@pxref{Input,,
+The Autoconf Manual, autoconf, The Autoconf Manual}):
+
address@hidden
address@hidden
+libtool.m4 -----.                .--> aclocal.m4 -----.
+ltoptions.m4 ---+  .-> aclocal* -+                    +--> autoconf*
+ltversion.m4 ---+--+             `--> [copy in m4/] --+       |
+ltsugar.m4 -----+  |                    ^             |       \/
+lt~obsolete.m4 -+  +-> libtoolize* -----'             |    configure
+[ltdl.m4] ------+  |                                  |
+                   `----------------------------------'
+
+ltmain.sh -----------> libtoolize* -> [copy in build-aux/]
address@hidden group
address@hidden example
+
+During configuration, the @file{libtool} script is generated either
+through @command{config.status} or @command{config.lt}:
+
address@hidden
address@hidden
+             .--> config.status* --.
+configure* --+                     +--> libtool
+             `--> [config.lt*] ----'      ^
+                                          |
+ltmain.sh --------------------------------'
address@hidden group
address@hidden example
+
+At @command{make} run time, @command{libtool} is then invoked as needed
+as a wrapper around compilers, linkers, install and cleanup programs.
+
+There are alternatives choices to several parts of the setup; for
+example, the Libtool macro files can either be copied or symlinked into
+the package, or copied into @file{aclocal.m4}.  As another example, an
+external, pre-configured @command{libtool} script may be used,
+by-passing most of the tests and package-specific setup for Libtool.
+
 @menu
 * Autoconf macros::             Autoconf macros exported by libtool.
 * Makefile rules::              Writing @file{Makefile} rules for libtool.