-*-text-*-

===========================================================================
* Adding files to AC_OUTPUT in configure.in.

Please do not add any non-makefiles to AC_OUTPUT unless you're
*absolutely* sure that it's safe and necessary to do so.  If you're
not sure, then please use the "generation with sed by hand approach"
that we use for other non-makefiles like src/scm/bootstrap.scm.  See
src/scm/bootstrap.scm.in and src/scm/Makefile.in for details.

The reasoning behind this is that there are often variables that
autoconf uses and replaces via the @@ mechanism that are recursively
defined in terms of other variables.  For example, @datadir@ might
expand into $prefix/share, which itself contains an unexpanded
variable.  Unless the @datadir@ replacement is performed on a file
that will eventually be processed by make, there's no guarantee that
the variable will *ever* be fully expanded and then your code will
break.

To get around this, we handle all non-makefiles (with a few notable
exceptions) manually with sed.  For example, we have
src/scm/bootstrap.scm.in which is processed in src/scm/Makefile.in
according to the following rule:

  ## We borrow guile's convention and use @-...-@ as the substitution
  ## brackets here, instead of the usual @...@.  This prevents autoconf
  ## from substituting the values directly into the left-hand sides of
  ## the sed substitutions.  *sigh*
  bootstrap.scm: bootstrap.scm.in
        rm -f $@.tmp
        sed < $@.in > $@.tmp \
            -e 's:@-VERSION-@:${VERSION}:g' \
            -e 's:@-GNC_CONFIGDIR-@:${GNC_SHAREDIR}:g' \
            -e 's:@-GNC_SHAREDIR-@:${GNC_CONFIGDIR}:g'
        chmod +x $@.tmp
        mv $@.tmp $@

This approach guarantees that the variables referred to will be
properly expanded at the right times.

The only non-Makefiles files that must be handled directly by
AC_OUTPUT are files that refer to variables that, when expanded, may
have makefile-hostile characters like '#' in them like
INCLUDE_LOCALE_H.  These may need to be replaced directly in the
relevant file via AC_OUTPUT since going through a makefile would break
the makefile when it interprets the '#' as the beginning of a comment.
You'd have something like this:

  FOO = "#include <locale.h>"

If you end up in a situation where you need to refer to both these
makefile-hostile variables and non-makefile hostile variables in the
same file, please restructure things (breaking the file up if
necessary) so that only the makefile hostile variables are in the
files being handled by AC_OUTPUT directly.

===========================================================================

It is not safe to use $prefix in configure.in for anything other than
an unexpanded reference.  If the user doesn't specify a --prefix, then
it'll be set to NONE until the end of the configure process.

===========================================================================

Deleting .SUFFIX rules

While working on some other problems, I discovered that this implicit
rule 

  % : %.tmpl
    ...

fails for files like message_i18n.h.tmpl because some other .h
implicit rule that's been defined is keeping this one from working.  I
could have worked around it by defining a "terminal rule" using "::"
instead (See "Match-Anything Pattern Rules" in the make info pages),
and in truth, :: might be more appropriate here anyway, but instead I
used .SUFFIX: to delete all the default suffix rules.  I think that we
probably want control of this anyhow...

===========================================================================

*EXPANDED* .in file variables:

I've added some rules to configure.in that look like GNC_EXPANDED_*.
These are intended for use in any non-makefile .in files.  The
difference between them and another variable of the same name
(i.e. the difference between GNC_LIBDIR and GNC_EXPANDED_LIBDIR is
that the latter has been expended in configure.in via
recursively_expand().  This is critical for variables that are going
in to non-makefiles because there's no other way for any variable
references to get expanded.  For example, what if configure were to
assign GNC_CONFIGDIR to be "${prefix}/etc/gnucash" and then this exact
string were substituted into gnucash.h.in or bootstrap.scm?  The C
compiler and Scheme interpreter would have no idea what to do with
$prefix, so you'd be stuck.  recursively_expand fixes this.

===========================================================================