Re: Documentation

[Francesco Salvestrini]

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"