Re: Documentation

[Francesco Salvestrini]

Hi Peter,

On Friday 17 July 2009, Peter Simons wrote:
> 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?

I usually prefer to have the package self-contained, looking for documentation  
inside the tarball itself (or into the info installed pages).

 It is a personal taste obviously but it seem to me that our target audience 
is an autotools-somewhat-skilled one and IMHO they averagely prefer their 
terminal to a browser :-P

We could use the texinfo format as an intermediate one:

A) Macro documentation (macro master role): extracted directly from the 
macros, massaged into texinfo, texinfo used to build the HTML pages

B) Distribution related documentation (text master role): usual autotools 
files (README, INSTALL ...) should remain plain text files. They could be 
rearranged into some texinfo pages (during site generation).

C) Documentation for archive maintainers (mixed roles):
C.1) docs for the maintainers: text files into the repository (they shouldn't 
be packed into the distribution)
C.2) docs for the submitters: texinfo translated to text and packaged into the 
distribution tarball

All the texinfos pages should be packed into a single texinfo file (shipped 
with the distribution).

A + B + C could even lead to have an autotooled autoconf-archive (which I 
would prefer for the sake of maintenance) ...

Ciao,
Francesco

> Take care,
> Peter

-- 
And do you think (fop that I am) that I could be the Scarlet Pumpernickel?