Re: Documentation

[Peter Simons]

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.


 > 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.


 > 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

I agree.

Take care,
Peter