Re: autotools cookbook needed

[Ralf Wildenhues]

Hi John, Matt,

> On Mon, 6 Feb 2006, John Calcote wrote:
> 
> > You know, I've recently finished reading the manuals for m4, libtool,
> > autoconf, and automake. After 1000 pages of reading, I was frustrated to
> > walk away knowing very little more than I started with. I believe this
> > is primarily due to the lack of examples and background context in the
> > explanations presented in these manuals (m4 and libtool manuals were
> > quite good, BTW - only the autotools manuals left much to be desired).

The manuals are not tutorials.

This one is good, not complete, but pretty much up-to-date:
http://www-src.lip6.fr/homepages/Alexandre.Duret-Lutz/autotools.html
This book is good, but quite a bit outdated:
http://sourceware.org/autobook/autobook/autobook_toc.html

> > I suggest we start a wiki page where people can post cookbook
> > information - detailed examples of how to do common things. A good
> > starting point would be FAQ and mailing list archives. The most
> > frequently asked questions would be answered first.

Possibly that would be a good idea.  But even a better idea would be to
improve the Autoconf documentation itself, right?  So that users
following your path don't have such a long learning curve?

I realize that this answer has drawbacks to you as the immediate user:
Autoconf releases do not happen too often, so in turn updated
information propagates very slowly compared to a wiki or FAQ.

On the other hand: a FAQ needs a volunteer/volunteers to keep it up to
date.  A wiki is not useful if it will only be used/updated by new
users.  AFAIK, savannah has no easy means to provide wiki space to
projects.  A wiki has a difficult time of being adopted on an official
GNU page if the information in it is not kept in good state by
experienced users.

There are lots of subtle issues in Autoconf which many users are not
aware of (because of bugs in certain systems or tools, or other rarely
encountered issues); this is the primary reason why third-party
tutorials/FAQs are often not a good source of information.

If you ask me, I would try to help someone who wants to either update
the manual, or collect information for a FAQ.  Time constraints
unfortunately won't allow me to create one myself.

* Matt Hull wrote on Mon, Feb 06, 2006 at 11:53:17PM CET:
> ill second that.
> 
> autoconf is that bad.

Hey, here's your time to improve upon it!

I should also mention that good tone helps encourage positive feedback.

> i havent written any m4 scripts though.  and
> couldnt get automake to work.

Well, I'm sorry no one has had time to go through the problems you
posted; but I don't think the issue was automake but much rather some
specific third-party macro.

Cheers,
Ralf