Re: [Firebird-docs] Translators: Changes to Docbuilding & Docwriting Howtos

[Paul V. <pa...@vi...>]

Hi Fabricio,

>>>>- Section "Building the HTML and PDF docs":

>>> Change the link from docwritehowto to docwritinghowto. The link
>>> is pointing to a non-existant entity. It's on last sentence.

>> No, it's correct but XXE reports an error because the id
>> "docwritehowto" is not in the current document. Once rendered to
>> HTML and PDF, the link works: in the HTML the entire set is
>> connected, and in the PDF docbuildhowto and docwritehowto are in
>> the same document.  There is no id "docwritinghowto".

> You need to sleep.

Without any doubt, but *you* need to wake up ;-)
Please read on.

> See this part of firebirddocs.xml (I got a update
> seconds ago):
> **************
> 	<!ENTITY docbuilding-howto SYSTEM
> "file:../docs/firebirddocs/docbuilding-howto.xml">
> 	<!ENTITY docwriting-howto SYSTEM
> "file:../docs/firebirddocs/docwriting-howto.xml">
> *************

Those two are *entities*, they are used later on to include the
files they refer to. In fb-docwriters-info.xml you see these lines:
    &docbuilding-howto;
    &docwriting-howto;

But a linkend must be an element's *id*. In this case it says
  <link linkend="docwritehowto">
because the id of the <article> containing the Firebird Docwriting
Guide is "docwritehowto". You can verify this by opening
docwriting-howto.xml in XXE, selecting the <article> element and
looking at the if attribute. Or open it in a text editor and look
at line 2:
  <article id="docwritehowto">

If you're still not convinced, change the link to "docwritinghowto"
or "docwriting-howto" and you'll find it will be broken in the PDF
and the HTML.


Greetings,
Paul Vinkenoog