Re: Please make the Autoconf manual less vague and add more examples

[Stefano Lattarini]

On 11/24/2012 10:50 AM, Eli Zaretskii wrote:
> (I'm not subscribed to the list, so please CC me on any responses.)
> 
> For the context, see
> 
>   https://lists.gnu.org/archive/html/emacs-devel/2012-11/msg00441.html
> 
> I never before had to do anything serious in Autoconf, so please take
> the below with a grain of salt and consider it as a first impression
> of a naive newbie.
> 
> I find the Autoconf manual too terse and cryptic to penetrate for
> someone, such as myself, who needs to do a relatively simple Autoconf
> job for the first time.
>
While the Autoconf reference manual is very good as a, well, reference
manual, it is inadequate as an introductory manual.  For that, I
suggest:

  <http://www.lrde.epita.fr/~adl/autotools.html>

which helped me greatly wean I was a newbie.  This might also be useful:

  <http://www.flameeyes.eu/autotools-mythbuster/>

albeit it's more of a WIP than a finished document.

> The manual describes the Autoconf facilities
> in a way that is too abstract, using vague language, and includes too
> few examples to help the reader understand that vague language.  I
> found myself grepping configure.ac files on my disk for examples, to
> be able to understand what to do.
>
Warning: that way lies madness.  This kind of copy & paste is the
source of countless anti-patterns in autotooled packages, as well
as of a good part of Autoconf's own bad reputation: many configure
scripts out there are brittle and messy not because of Autoconf's
limitations, but because the corresponding configure.ac have been
written through tentative copy & paste, without a clear understanding
of what the pasted code snippets are really about, or how they will
interact with each other.  Which, granted, can in turn be caused by
an overly terse or unclear Autoconf documentation ...

As for your concrete objections, I must say I can sympathize with
most of them (but I'm not going to write any patch addressing them
myself, sorry).

Regards,
  Stefano