Post by Nick BowlerPost by Shawn H CoreyAfter some investigation, I discovered that the documentation for GNU
AutoTools was crappy. This is surprising considering how long it has
been in use. ☹
Can you be more constructive? I think Autoconf and Automake have rather
good manuals[1][2]. Why are they crappy? How can we make them better?
[1] https://gnu.org/s/autoconf/manual/autoconf.html
[2] https://gnu.org/s/automake/manual/automake.html
My problem in the past is getting an idea for how to create a very
simple project with automake and autoconf.
I had a brief look at the autoconf manual to refresh my memory and
here's one thing I noticed:
In the "Results of Tests" chapter
(http://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Results.html#Results),
there are 4 ways to record results of tests listed: "There are four
sorts of things it can do: define a C preprocessor symbol, set a
variable in the output files, save the result in a cache file for
future configure runs, and print a message letting the user know the
result of the test." Then if you look at the first subsection
("Defining Symbols",
http://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Defining-Symbols.html#Defining-Symbols),
you get:
"A common action to take in response to a feature test is to define a
C preprocessor symbol indicating the results of the test. That is done
by calling AC_DEFINE or AC_DEFINE_UNQUOTED.
"By default, AC_OUTPUT places the symbols defined by these macros into
the output variable DEFS, which contains an option -Dsymbol=value for
each symbol defined. Unlike in Autoconf version 1, there is no
variable DEFS defined while configure is running. To check whether
Autoconf macros have already defined a certain C preprocessor symbol,
test the value of the appropriate cache variable, as in this example:"
This is not easy to read because it mentions "output variables" and
"cache variables", which haven't been explained so far in the manual:
they are described in later sections. (Also no-one cares about what
happened in older versions.) "Output variables" should probably be
described first.
Under the "Setting Output Variables" section, AC_SUBST is explained,
but there's nothing about how automake uses this information. (You've
got to look at the "Other things automake recognizes" section in the
automake manual
(http://www.gnu.org/software/automake/manual/html_node/Optional.html#Optional)
This is right if you are documenting how to use autoconf independently
of automake, but this underscores the importance of being able to
learn about the autotools from a single manual (i.e. the automake
manual). A flow chart like that in the autoconf manual
(http://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/Making-configure-Scripts.html#Making-configure-Scripts)
(which incidentally does use a fixed-width font for the diagram) could
be placed in the automake manual as well.
There are some problems with the automake manual, for example the
section "An Introduction to the Autotools" is too rambly ("It is a
truth universally acknowledged, that as a developer in possession of a
new package, you must be in want of a build system."). Jokes and
cultural references are fine as long as they don't get in the way,
which they do here, and just annoy the reader who is looking for
useful information.
The "Introduction" of the automake manual is not great:
"The GNU Makefile Standards Document is long, complicated, and subject
to change. The goal of
Automake is to remove the burden of Makefile maintenance from the back
of the individual GNU maintainer (and put it on the back of the Automake
maintainers)."
Generally, most people won't care about adhering to the "GNU Makefile
Standards Document". Instead, it could be mentioned here that using
automake provides many useful targets in the Makefiles it generates
(and these targets happen to be described in a Standards Document).
The three example packages in the automake manual don't have a simple
bare-bones project. The Hello World example
(http://www.gnu.org/software/automake/manual/html_node/Hello-World.html#Hello-World)
is a project with subdirectories. I find it annoying that it boasts
about how simple this package is: "The package is simple enough so
that we will only need to write 5 files." - having to write 5 files
doesn't seem very simple to me. The true/false example seems like a
logic puzzle and not anything useful. The 'zardoz' example
(http://www.gnu.org/software/automake/manual/html_node/Complete.html#Complete),
in fact isn't a complete example from start to finish. It assumes that
the project is already using autoconf, which will not be the case for
the vast majority of people reading the manual who are trying to
master both autoconf and automake at the same time. It doesn't show
the full contents of configure.ac. Also I am annoyed by the cheery
tone when it says "Now you can run ‘automake --add-missing’ to
generate your Makefile.in and grab any auxiliary files you might need,
and you’re done!", which implies that it is easy, which is annoying
for people who are struggling to get it to work.
In general I've found when using automake on small personal projects
that I don't care about what autoconf has to offer (portability
between OS variants). I'd like the automake manual to give a brief
explanation of what I needed to know about autoconf to get started
(i.e. what do I put in configure.ac), with pointers to the autoconf
manual for how to add, e.g., checks for libraries I might need.
A problem with having a manual that has flaws is that readers will
think that its authors had reasons for writing it the way they did and
like it the way it is, so they may be reluctant to suggest changes.
We'd be better off if people rewrote the manuals to be more helpful
instead of writing other tutorials or books about it (not that there's
anything wrong with that, of course). Hopefully there will be some
useful suggestions in this conversation.