First look at Guide update

[Thomas Bullock]

Monday, August 16, 2010 5:10 PM: John Ralls [mailto:jralls at ceridwen.us] wrote
 
> 
> [<<Tom>>: ] that's what I got too, except I did not format for clarity.  What you seem to be saying is that tips and notes always have to be the last things in a section, or at least section2's.
> 
> I accept that you are saying it, but how did you figure that out from the xmllint output?  I have not been able to find any DTD or equivalent that spells out the expected sequence.  I realize that xmllint has access to that in order for it to work.  Where do I find what xmllint is using?
> 
> And thanks very much for clearing up my problem.  I will make the changes and proceed to setting up a bugzilla patch.
> 
> Tom
> 

No, I'm saying that the <tip> and <note> elements can't be direct children of <sect1> after the first <refentry>, < sect2>, or  <simplesect> element.

The first part of the error message shows the types of elements that xmllint expects; the second part what it found. Study it and you'll see how I found the problem. Here's the decoder ring:
+ means one or more
* means zero or more
? means zero or one
If a symbol isn't followed by one of those, it means exactly one.
( foo | bar | baz) means that one of these elements must appear. If the whole group is followed by a numeration symbol, it means that all of the elements in the group may appear in any order the number of times indicated, so (foo|bar|baz)+ means at least one of them must appear, but there can be as many as you like. If the numeration symbol is inside (foo+|bar+|baz+), then only one type is allowed -- in that example, one or more foo, one or more bar, or one or more baz.

The top-level DTD 's URL is in the header block of gnucash-guide.xml:
 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
The child DTDs are located in the same directory, along with a readme and a handy zip file.

(I find RelaxNG compact schemas to be much easier to read than DTDs. Trang (http://code.google.com/p/jing-trang/) will convert the DTDs if you're interested in pursuing that. Java required.)

Before you make a patch, build the html and look at the result in a browser to make sure that all of the formatting came out the way you want.

Regards,
John Ralls

[<<Tom>>: ] thanks, John.  I guess your name now is Captain Marvel.  I remember the breakfast cereal magic decoder rings from my childhood, something that Captain Marvel gave the devoted followers of his radio programs!

I will follow up with Trang and the child DTDs to know what you are explaining.  As always, I do appreciate your support.

Tom Bullock