Re: Documentation

[Francesco Salvestrini]

Hi Peter,

Sorry for the delay in my reply.

On Monday 20 July 2009, Peter Simons wrote:
> Hi Francesco,
>
>  > * README, README-maint, INSTALL -> plain text into the root
>
> yes, that's fine. README exists, INSTALL is copied-in by Autotools, and I
> have renamed NOTES accordingly, so that's taken care of.

Got it in the last pull. 

>  > * ChangeLog                     -> autogenerated
>
> Gnulib's "gitlog-to-changelog -- --branches >ChangeLog" seems to do a good
> job at generating that file, but I wonder: should the ChangeLog contain
> messages from all branches? Or just 'master' -- a.k.a. the macros?

I would say that the ChangeLog file should contains all the logs pertaining to 
items that are going to be packed in the distribution tarball. 

>  > * NEWS                          -> plain text / autogenerated
>
> We might be able to generate NEWS from annotated tags in Git. This would
> mean, of course, that we'd have create a tag every time we want to change
> the NEWS file. That sounds somewhat unreasonable to me. Maybe a plain file
> is good enough.

Forcing to tag the repository in order to fill the NEWS sounds unreasonable to 
me too since the procedure doesn't give anything more that filling NEWS 
manually while pollutes the repository with tags in the meanwhile.

Since a NEWS entry borns from a single commit or a set of commits ... it 
should be more natural to extract such information from commits. A 
pre-commit-msg hook could came handy (a hook which analyzes the commit 
message, looks for some header, strip those lines and drops them into the 
NEWS file).

But let's keep it simple by filling the NEWS file manually (and for your own 
sake ... *cooperatively*).

Have a good night,
Francesco
-- 
Don't make a big deal out of everything; just deal with everything.