[sr-dev] Why fetch docbook stylesheets remotely?

[Olle E. Johansson]

16 okt 2009 kl. 18.54 skrev Jan Janak:

> On Fri, Oct 16, 2009 at 5:18 PM, Jan Janak <jan at ryngle.com> wrote:
>> On Fri, Oct 16, 2009 at 4:32 PM, Olle E. Johansson <oej at edvina.net>  
>> wrote:
>>>>
>>>> The catalog file contains references for Docbook 4.3, have you  
>>>> changed
>>>> the docbook version number in documentation files perhaps? If yes  
>>>> then
>>>> this could be the reason why the build system tries to download XSL
>>>> stylesheets from the internet.
>>>
>>> Checking modules directory I see that we have both 4.2 and 4.4  
>>> used. Maybe
>>> we should standardize
>>> and make sure that we have the 4.4 files referenced.
>>
>> Changing docbook version only makes sense if you need to use any of
>> the bug-fixes or improvements done between 4.2 and 4.4 in XML source
>> files, that means in docbook sources. Those changes fix minor bugs in
>> the schema and sometimes allow some elements to be used in new
>> contexts. In other words, you only need to change docbook version if
>> you want to use something that has been specified after 4.2 and it
>> makes your docbook documents invalid.
>>
>> Changing Docbook version does not change the version of XSL
>> stylesheets that are used to generate various output formats, such as
>> HTML or READMEs. These are configured in catalog files and in *.xsl
>> files in sip-router/docbook.
>>
>> If you want to change docbook versions anyway then the latest
>> compatible version is 4.5. There is also version 5.0, but that would
>> require changes in source XML files because this version is not
>> backwards compatible anymore.
>>
>> Also, if you do the change, please wait until the master branch is  
>> unfrozen.
>
> After second reading of emails in this thread I realized that my
> earlier explanation of the Docbook system is not only confusing, but
> also incorrect. I apologize, please forget what I wrote in the email
> sent yesterday and let me try again.
>
> The usual text at the beginning of Docbook source documents
>
> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
>   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
>
> determines the particular version of the DTD (Document Type
> Definition) the Docbook document tries stay compatible with. This
> information is only used if you try to validate your Docbook document
> against the schema, for example by running make check in sip-router or
> if you use an editor which performs document validation on the fly as
> you edit the document.
>
> The HTTP URL in the example above refers to the DTD file online, this
> is the recommended way of writing DTD declarations in Docbook XML
> files. If you actually try to download the document then you get the
> DTD file for Docbook version 4.2.
>
> If you try to validate a Docbook document in sip-router by typing
> "make check" in a doc directory then the makefile system runs xmllint
> to validate the document. Xmllint uses the document type declaration
> presented above to locate the DTD file needed for the validation. But
> before it tries to download it using the HTTP URL above, the tool
> consults the file sip-router/docbook/catalog.xml to see if there is
> perhaps a local copy of the file already on a local disk.
>
> The file catalog.xml is a XML catalog file. XML catalog files are used
> to map document type declarations (like the one above) to local files.
> XML catalogs can map both type of identifiers, the textual one
> "//OASIS//DTD.." and the HTTP URL as well. If the catalog file has a
> reference to  a local DTD file then Xmllint uses the local file and
> does not try to download it from the HTTP URL. If there is no local
> copy of the DTD file then Xmllint downloads it using the HTTP URL
> above.
>
> The XML catalog file in sip-router/docbook/catalog.xml refers to
> system-wide "standard" catalog files by default. On Debian (and
> perhaps other Linux/GNU based systems) the system-wide catalog is
> /etc/xml/catalog.
>
> On Debian systems the system-wide catalog file is updated by the
> package manager. That means if you install the package docbook-xml,
> which contains Docbook DTD files for all 4.x versions, the DTD files
> from that package become automatically available to the Docbook build
> system in sip-router and it never has to download anything from the
> internet.
On Mac, I just found a package named docbook-xml in MacPorts.

[....]

Now, is the catalog.xml protected by .gitignore? If I have to change  
it and later commits, I see another oej mistake coming along...

Thanks for a very good text. We do need to save it so we can reuse it  
later. Wiki or doxygen.

Thanks!

/O