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 19:22:19 +0200 |
User-agent: |
KMail/1.9.10 |
Hi Peter,
On Saturday 18 July 2009, Peter Simons wrote:
> Hi Francesco,
>
> >> 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).
>
> that's a good point. I feel the same way: documentation related to the
> archive shouldn't be scattered all over the place. It would be really
> nice if we could produce a comprehensive texinfo document that feels
> like more than just a bare-minimum reference documentation. I guess this
> means that auxiliary topics -- like submission and maintainer guidelines
> -- should be covered in that document, too.
I agree for the auxiliary topics with an exception: maintainer guidelines
should be cointained in a README-maint (or something like that). The info
file shouldn't contain maintenance related instructions IMHO.
> > 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
>
> I agree.
>
> > 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).
>
> I wonder whether texinfo is capable of generating reasonable plain text
> output? If it is, we might want to have the README in texinfo, too, and
> generate the file. This doesn't apply to INSTALL, NEWS, and ChangeLog,
> though.
IMHO:
* README, README-maint, INSTALL -> plain text into the root
* NEWS -> plain text / autogenerated
* ChangeLog -> autogenerated
For ChangeLog autogeneration we could use gitlog-to-changelog from gnulib.
Ciao,
Francesco
--
Must I hold a candle to my shames?
-- William Shakespeare, "The Merchant of Venice"