Documentation

[Peter Simons]

Hi,

I wonder how to improve the documentation of the Autoconf Archive and I
would like to know what you guys think about the subject.

Basically, there are three kinds of documentation:

 1) Macro documentation that explains how to use a specific macro.

 2) Documentation concerning the distribution that explains how to
    download and install the tarballs, how to access the Git repository,
    and how to contribute patches.

 3) Documentation for archive maintainers that explains how to
    regenerate the web site, how to compile a release tarball,
    submission guidelines, etc.

As of now, (1) and (2) are available in HTML and (3) doesn't exist at
all. :-)

The GNU people have suggested that the Autoconf Archive should
distribute macro documentation (1) in Texinfo. IMHO, that sounds
reasonable. Texinfo can be used to generate a website, and it can also
be compiled to Info, which is particularly convenient to use in Emacs.

Documentation related to the distribution itself is probably best
distributed in ASCII, i.e. as a README file. Currently, there is such a
README in the 'maint' branch that is also used to generate the HTML
front page for the site.

Now, what to do about maintainer documentation? Currently, there is a
NOTES file in the 'maint' branch. Is that a good enough solution? I'm
inclined to think so, but I don't know the alternatives. Does anyone
like the documentation tracker that Savannah offers?

Take care,
Peter