16 okt 2009 kl. 18.54 skrev Jan Janak:
On Fri, Oct 16, 2009 at 5:18 PM, Jan Janak jan@ryngle.com wrote:
On Fri, Oct 16, 2009 at 4:32 PM, Olle E. Johansson oej@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