First look at Guide update

[Thomas Bullock]

John Ralls [mailto:jralls at ceridwen.us]<mailto:[mailto:jralls at ceridwen.us]> writes:


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.
[<<Tom>>: ] thanks for interpreting.  Nothing against Frank.  I am just too new to catch the short-hand.


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.)
[<<Tom>>: ]  Since you did not mention the name of such a program that normalizes XML, I assume that GC developers have not adopted one as the standard.  It would be handy for those working with a lot of XML.  Let me know if I assume wrong.


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.
[<<Tom>>: ]   I can work with that plan!


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.
[<<Tom>>: ]  Sounds like very good advice.  In fact, maybe the first small patch won't have the present xml  validation complaint!


Regards,
John Ralls
[<<Tom>>: ] I appreciate the extra effort you and Geert are putting in to keeping me afloat while my learning curve grows!  Thanks again.