version references in documentation

Tom Bullock tbullock at nd.edu
Mon Sep 20 19:18:21 EDT 2010


On 09/19/2010 04:12 PM, Yawar Amin wrote:
> Hi Tom,
>
> On 2010-09-19, at 15:30, Tom Bullock wrote:
>
>    
>> Hi Yawar,
>>
>> I am pulling together the pieces of my patch.  When I ran it thru "xmllint", I got these xml error messages that I hope you understand and can tell me what is my error:
>>
>> 1.  validity error: Element xref was declared EMPTY this one has content
>> <xref linkend="ch_oth_assets.xml">Chapter 16</xref>  of this Guide.</para>
>>     [the message does identify the line number in error]
>>      
> The ‘xref’ element is defined as being empty, that is, it doesn’t look like
>
>    <xref linkend=“whatever”>whatever</xref>
>
> but rather like
>
>    <xref linkend=“whatever”/>
>
> It’s an XML thing. If you want to know more about empty v non-empty tags, see [1]. To see more about the<xref>  tag, see [2]. By the way, being an accountant, I think you’ll be hearing more and more about XML in the next few years, thanks to the upcoming XBRL (XML Business Reporting Language) standard [3].
>
>    
>> 2.  gnucash-guide.xml:293: element xref: validity error : IDREF attribute linkend references an
>>     unknown ID "ch_oth_assets.xml"
>>
>> I have listed ch_oth_assets.xml in gnucash-guide.xml both as<!ENTITY chapter16 SYSTEM "ch_oth_assets.xml">  (given on line 19)  and also as&chapter16; (given on line 284)
>>      
> OK, this means that you’ve defined a system entity (basically, a file living on the disk) named ‘ch_oth_assets.xml’ and which can be referred to as ‘chapter16’. What you can do with this is by writing
>
>    &chapter16;
>
> at a certain point in the documentation, you can make the XML processor read in the entire contents of the file at that point. And in fact this is how the documentation is put together for all chapters, if you look at the last part of the gnucash-guide.xml file.
>
> But this won’t work with the<xref>  tag, because it uses a different way of referring to chapters.
>
> What you would do is, in your ch_oth_assets.xml file, you would have something like
>
>    <chapter id=“chapter_oth_assets”>
>      <title>Other Assets</title>
>>    </chapter>
>
> Then, anywhere else in the docs, you would be able to write something like
>
>    <xref linkend=“chapter_oth_assets”/>  of this Guide.</para>
>
> The vital thing is that in the<xref linkend=“whatever”/>, ‘whatever’ must match the<chapter id=“whatever”>…</chapter>. That way, the correct chapter number will be put in at that point:
>
>    Chapter 16 of this guide.
>
>    
>> So why does the error mention line 293, which is after last line 292, past the end of</book>  shown on line 292?
>>      
> Sometimes, because of the way these error-detection programs work, they can only point you towards the general vicinity of the error. I’ve experienced this many times where the program runs along nicely even after an error has appeared, until it is forced to stop because of the effects of the error introduced earlier. At that point, it complains with the current line number.
>
>    
>> It seems to me I am not using the referencing method correctly.   But I wonder also about the
>> possibility that I may need to set a value in a symbolic parameter you have introduced.
>>
>> I did include ch-oth-assets.xml in the directory "guide/C" where all the modules are that make up the guide.
>>
>> TIA for  all help.
>>
>> Tom
>>      
> You’re welcome, hope all of the above makes sense. Do ask for details if anything seems unclear.
>
> Regards,
>
> Yawar
>
> [1] http://www.w3.org/TR/REC-xml/#sec-starttags
> [2] http://www.oasis-open.org/docbook/documentation/reference/html/xref.html
> [3] http://www.ifrs.org/XBRL/Resources/Fundamentals.htm
>
>    

Hi Yawar,

Your reply is just great! Thanks. I will apply your instructions and 
read the 3 references you provided. Depending on results, I hope to have 
a bugzilla item soon to send you all.

Tom


More information about the gnucash-devel mailing list