=====================
1. Copyright & Licensing
   =====================

   autogen.sh is Copyright (C) 2001 AbiSource and is licensed under the GNU GPL (see COPYING).
   See individual plugins for copyright and licensing.

   ===========================
2. The autogen.sh Build System
   ===========================

   -----------------
   Developer's notes
   -----------------

   The recommended build method for UNIX et al. is to use the GNU development utilities autoconf,
   automake and libtool, since building modules is tricky business and nothing does it better
   (i.e., more portably) than libtool - which is not to say that libtool is without problems,
   since even CVS libtool has problems with darwin (most of them zsh-related) and no doubt there
   are issues on some other operating systems...

   abiword-plugins/autogen.sh is a script which (a) detects plugins, and (b) creates the umbrella
   build system. This makes it easy to add new plugins.

   a. Plugin Detection

      Any subdirectory of abiword-plugins which contains a file called 'plugin.cfg' is treated
      as a plugin source directory. This file sets a number of variables that influence the
      behaviours of both abiword-plugins/autogen.sh and abiword-plugins/configure:

         abi_plugin_autoconf=[yes|no]      # Whether the plugin uses autoconf
         abi_plugin_configure=[yes|no]     # Whether the plugin has a configure script
         abi_plugin_script=[<script>|no]   # A plugin script that autogen.sh should execute

      In each case the default is no, but abi_plugin_autoconf=yes => abi_plugin_configure=yes.
      If necessary, <script> should build the plugin's local build system (by running autoconf,
      automake, etc.). The environment variable 'abi_topdir' is the path of abiword-plugins,
      which can be useful, e.g.:

         aclocal -I $abi_topdir/ac-helpers

      There are a number of useful package detection macros in this directory. Also, if
      compiling against AbiWord source, use the macro ABI_PLUGIN_SETUP in configure.{in,ac}
      which defines the substitutions @ABI_CPPFLAGS@, as well as @ABI_PLUGIN_DIR@ - the plugin
      installation directory.

      If not using autoconf, the following environment variables are set by
      abiword-plugins/configure:

         abi_plugin_source   - AbiWord source directory
         abi_plugin_target   - plugin installation directory
         abi_plugin_version  - Corresponding AbiWord version number

      NOTE: configure should always be run from the top, i.e., abiword-plugins/configure

   b. The Umbrella Build System

      abiword-plugins/autogen.sh will not recurse into directories with a 'plugin.cfg'. Instead
      it will tag these as plugins, and will construct a GNUmakefile.am tree that reaches all
      plugin sources. These GNUmakefile.am files consist of a single SUBDIRS rule, e.g.:

         SUBDIRS = OpenWriter bz2abw graphics

      In this example, the first two are plugins and the 3rd is a subdirectory containing
      further plugins (AbiGdkPixbuf and magick). abiword-plugins/autogen.sh will therefore
      create a GNUmakefile.am in graphics but not in OpenWriter or bz2abw.

      NOTE: The use of 'GNUmakefile' presumes the use of GNU make.

      NOTE: There is a bug in automake-1.5 which causes problems when using 'GNUmakefile'.
            Either use an earlier version of automake or add the following at line 16 of
            $prefix/share/aclocal/depout.m4:

               GNUmakefile) dirpart=.;;
               */GNUmakefile) dirpart=`echo "$mf" | sed -e 's|/[^/]*$||'`;;

      Once the GNUmakefile.am tree is constrcuted, abiword-plugins/autogen.sh creates
      abiword-plugins/configure.{in,ac}, runs libtoolize, aclocal, automake and autoconf,
      and, finally, for each plugin in turn, executes the requested script (if any).

   ------------------------------
   Configuring in abiword-plugins
   ------------------------------

   './configure --help' lists a number of options, others may be available. Try also running
   'configure --help' in individual plugin directories.

   The AbiWord sources are required for most plugins, and abiword-plugins/configure requires
   them. It searches for a peer directory called 'abi' and (if found) assumes it to be the
   AbiWord sources. Otherwise, or to override this selection, use the --with-AbiWord=<dir>
   option to configure to specify the real location (dir) of the AbiWord sources.

   An installation directory is required as well. If 'AbiWord' is in the PATH,
   abiword-plugins/configure scans it for ABISUITE_HOME and sets $ABISUITE_HOME/plugins as
   the plugin installation directory. Otherwise, or to override this selection, use the
   --prefix=<dir> option to configure to install plugins in <dir>/plugins.

2nd December, 2001
Francis James Franklin <fjf@alinameridon.com>