First look at Guide update

John Ralls jralls at ceridwen.us
Mon Aug 16 12:53:00 EDT 2010


On Aug 16, 2010, at 9:06 AM, Thomas Bullock wrote:

> H. Ellenberger [mailto:f.ellenberger at online.de]<mailto:[mailto:f.ellenberger at online.de]> writes:
>> -                                               '''BEGIN NEW CONTENT HERE!!'''
>> 
>> +                                               <!-- '''BEGIN NEW CONTENT HERE!!''' -->
> 
> I am confused by your comment.  I am glad to try to follow your suggestion.  But the example you listed above is from a patch that you seem to have run.  I was not making a patch.  What I put on the wiki is the xml listing of ch_accts.xml.  I inserted the all caps START STOP comments only to show what had been added and where it ended.
> 
> 
> 
> If this confuses everyone, then what you seem to want is for me to put a patch on the wiki?  Is that correct?  If so, I cannot do that because I continue to have an xml validation error that I have not resolved yet.
> 
> 
> 
> Please tell me the exact process to quote my annotations that you want me to follow.  The patch process seems to do that nicely.  What in addition do you wish me to do?
> 

Tom,

What Frank is trying to tell you is that you should use XML comments rather than wiki markup in the code block so that others can help you with your validation problem. (Wiki markup gets turned off in code blocks anyway, as you see from the result.) It looks like a patch because, being a dev, Frank used patch notation as shorthand for what you should do differently.

He also apparently found tab characters in the code block. That might be an artifact of the wiki rather than anything you did overtly; if so, no problem. It might also be something that your editor does for you when indenting the text elements to look pretty. If so, that might create differences from the original which are whitespace only, not content, and make your diff larger. This is often an avoidable problem in code, but is probably not avoidable in text because if you add a sentence to a paragraph and then re-justify the paragraph it's going to affect every line after your inserted sentence anyway. (A diff program that "normalized" the XML before generating the diff would solve that problem. Those typically have their own formats, so everyone working with your changes would need to agree on which one.)

Anyway, perhaps you could make a diff from your first attempt and put it in bugzilla. Then some of us with more XML experience can apply it in our own sandboxes and help you with the errors. Once they're fixed and other comments applied, you can replace the attachment to the bug. After everyone is happy, a dev will apply the final version of the patch and close the bug, and you start the process again with a new edit and a new bug. Keep the patches small at first. This helps you track down validation problems and makes writing the change memo easier. After you've had some practice at writing DocBook markup and change memos, you may want to submit larger patches -- or not. In general, lots of small revisions makes for better change history than a few large ones, especially if the large ones cover multiple topics.

Regards,
John Ralls




More information about the gnucash-devel mailing list