autoconf-archive-maintainers | |
[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation
From: |
Francesco Salvestrini |
Subject: |
Re: Documentation |
Date: |
Sat, 18 Jul 2009 00:27:21 +0200 |
User-agent: |
KMail/1.9.10 |
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?
- Documentation, Peter Simons, 2009/07/17
- Re: Documentation,
Francesco Salvestrini <=