Bug 632594 created; review, approval, commit requested

[Thomas Bullock]

Thanks, for the words of support.  It is flattering for you to overstate the case about my documentation abilities.  I know otherwise only too well -- witness the most recent effort!

Tom

> -----Original Message-----
> From: Yawar Amin [mailto:yawar.amin at gmail.com]
> Sent: Wednesday, October 20, 2010 2:55 PM
> To: Thomas Bullock
> Cc: Geert Janssens; gnucash-devel at gnucash.org
> Subject: Re: Bug 632594 created; review, approval, commit requested
> 
> Hi Tom,
> 
> On 2010-10-20, at 13:39, Thomas Bullock wrote:
> 
> > [...]
> > When I ran the first svn diff I found many changes needed to
> gnucash-guide.xml.  Cristian Marchi's reply let me find the way to
> correct those.  I ran another xmllint and found still 2 more xml
> errors.  I fixed those and thought they would be in the next diff
> output.  Part of what confused me is that my changes.patch (the one
> attached to the bug) had to have been changed by both Cristian's svn
> updates and my own.
> 
> This is a really tricky svn behaviour if you weren't actively
> expecting it, I never would have thought of it myself. Lesson learned
> for all of us! :-)
> 
> >  In the last instance the ch_basics.xml file now has changes to fix
> line breaks, which is different than the original content of that
> file.   That probably happened either to Yawar or Cristian doing svn
> updates.
> 
> Not sure how the line breaks got into the patch ... anyway, we can set
> the re-wrapping and reformatting commits to a future effort to keep
> all the cosmetic changes together.
> 
> > [...]
> >
> >> The overview will always show continuous numbering even if you
> delete
> >> a chapter. The chapter numbering is dynamic. At best you could see
> >> the last number has gone missing.
> >
> > I did not know that either.  It sounds strange.  I expect if chapter
> 14 is missing, its number would  be skipped.
> > Elsewhere in the documentation you have to refer to each specific
> chapter if you want it mentioned.
> 
> Think about it-we don't have to worry about the chapter numbering-we
> just refer to chapters by their IDs (<xref
> linkend="chapter_oth_assets"/>-meaning 'put in a reference here to the
> Other Assets chapter') and let the software worry about the numbering.
> 
> >> You could check in your original xml file if you have still
> linkends
> >> for both chapter_bus_pay and chapter_budgets. The patch suggests
> you
> >> don't.
> >
> >
> > You are exactly right -- chapter_bus_pay was missing there!  This is
> really sneaky, at least for the uninitiated.  Well, I have  been
> burned.  Thanks for explaining how it happened.  I see why you or John
> early on suggested running many small patches rather than few large
> ones.  It is very easy to get tripped up.
> 
> Well, editing mistakes can happen from time to time too. I've made
> plenty of patches where I keep noticing errors and correcting them,
> one after the other.
> 
> > Thank you for the careful review of my issues.  I will try to be
> more careful as I go forward.
> 
> Hang in there, I'd say you're almost a GnuCash docs veteran by now :-)
> 
> Best,
> 
> Yawar