First look at Guide update

[John Ralls]

On Aug 16, 2010, at 12:49 PM, Thomas Bullock wrote:

> John Ralls [mailto:jralls at ceridwen.us] writes:
> 
> OK, I've taken your wiki posting and run it through xmllint. The output (after reformating it for clarity) is
> 
>> (sect1info? , 
>>  (title , subtitle? , titleabbrev?) , 
>>  (toc | lot | index | glossary | bibliography)* , 
>>  (
>>    (
>>      (calloutlist | glosslist | itemizedlist | orderedlist | segmentedlist | 
>> 	   simplelist | variablelist | caution | important | note | tip | warning |
>> 	   literallayout | programlisting | programlistingco | screen | screenco |
>> 	   screenshot | synopsis | cmdsynopsis | funcsynopsis | classsynopsis |
>> 	   fieldsynopsis | constructorsynopsis | destructorsynopsis | 
>> 	   methodsynopsis | formalpara | para | simpara | address | blockquote | 
>> 	   graphic | graphicco | mediaobject | mediaobjectco | informalequation | 
>> 	   informalexample | informalfigure | informaltable | equation | example | 
>> 	   figure | table | msgset | procedure | sidebar | qandaset | anchor | 
>> 	   bridgehead | remark | highlights | abstract | authorblurb | epigraph | 
>> 	   indexterm | beginpage)+, 	  
>>      (refentry* | sect2* | simplesect*)
>>    ) | 
>>  refentry+ | sect2+ | simplesect+), 
>>  (toc | lot | index | glossary | bibliography)*
>> ), got 
>> (title 
>>       para 
>>       para 
>>       para 
>>       para 
>>       sect2 <- "BEGIN NEW CONTENT" is in the middle of this section
>>       sect2 
>>       sect2 
>>       sect2 
>>       sect2 <- "SIGNIFICANT NEW CONTENT ENDS HERE" is at the end of this one. 
>>       tip 
>>       sect2 
>>       tip 
>>       sect2 
>>       tip 
>>       note 
>>       sect2 
>> )
> 
> 
> which pretty clearly shows the problem: You promoted those <tip> and <note> elements to the top level; they should have remained in the <sect2> elements that they were in originally. In every case, the </sect2> tag needs to be moved from just above to just below the offending elements, after which xmllint passes.
> 
> Regards,
> John Ralls
> 
> 
> [<<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