To m4 and back. Where do I start again?

[Steven T. Hatton]

Firstly, I came upon this interesting comment in the automake documentation:

<quote url=http://sources.redhat.com/automake/automake.html#Local-Macros>
5.8 Handling Local Macros

Feature tests offered by Autoconf do not cover all needs. People often have to 
supplement existing tests with their own macros, or with third-party macros.

There are two ways to organize custom macros in a package.

The first possibility (the historical practice) is to list all your macros in 
acinclude.m4. This file will be included in aclocal.m4 when you run aclocal, 
and its macro(s) will henceforth be visible to autoconf. However if it 
contains numerous macros, it will rapidly become difficult to maintain, and 
it will be almost impossible to share macros between packages.

The second possibility, which we do recommend, is to write each macro in its 
own file and gather all these files in a directory. This directory is usually 
called m4/. To build aclocal.m4, one should therefore instruct aclocal to 
scan m4/. From the command line, this is done with aclocal -I m4. The 
top-level Makefile.am should also be updated to define

      ACLOCAL_AMFLAGS = -I m4
</quote>

I have attempted more than once to gain a comprehensive understanding of the 
gnu autotools.  There have been many reasons I've never gotten very far.  One 
of the biggest problems has been that the documentation for automake and 
autoconf seem to be at odds with oneanother.  It seems there is a good deal 
of overlap between what these tools will do.  I'm not sure which of the two 
documents I should take as "definitive" in terms of what people actually do.  

The reason I was reading §5.8 of the Automake info is because I noticed 
aclocal is the first to be invoked by KDevelop.   §5.8 seems like the wrong 
place to start.  The Autobook http://sources.redhat.com/autobook/ seemed 
quite out of date when I tried to read it and reproduce what it provided as 
examples.  Should I simply slog my way through it and try to figure out what 
is and isn't obsolete?

-- 
Regards,
Steven