Documentation Revision Description & Authors List

[John Ralls]

On Jul 28, 2010, at 4:14 PM, Tom Bullock wrote:

> Hi John,
> 
> <<snip>>
> You don't need to generate it: It's in the SVN repository, so you'll get it when you check out gnucash-docs. (It's at guide/C/gnucash-guide.xml). You needn't modify it unless you add a new chapter or appendix, though you may want to add yourself to the authors list and add a description of your revisions.<</snip>>
> 
> Where are these two actions done?  I noticed that there are several modules that have author's notations and of the same people at approximately the same times.  Is that because their changes had broader scope?  In short is the principle that you state authorship in broader scope modules only if your change impacted that module and all below it?
> 
> Also, I assume the revision description would go in the header of the changed module, but not higher up the Guide's hierarchy.  Is that correct?
To add a chapter, create a new file and a corresponding ENTITY declaration in the local DTD (in gnucash-guide.xml). Add your new file to the list in Makefile.am (don't forget the trailing "\" on all but the last line of the list).

Author annotation: Heck if I know. Absent better guidance from Derek, do what seems right to you. They're only comments, after all.

You need to learn proper XML-speak; "header" is a part of a document (which the chapter files are not, since they lack a <!DOCTYPE> statement, which is what constitutes a "header" in XML. The few I looked at just now each have a short comment block at the beginning with very limited authorship and revision information.

The best place for change information is in the SVN log. Make your patches more or less atomic around a single revision subject, and provide a description along with the patch. Whoever checks in the patch will include the description in the checkin command, and that will add it to the log. Lots of small patches is better than few big ones for logging purposes. (It's better for source code control, too, but that's not really an issue here.)

Regards,
John Ralls