[sr-dev] Why fetch docbook stylesheets remotely?

[Jan Janak]

On Thu, Oct 15, 2009 at 4:26 PM, Olle E. Johansson <oej at edvina.net> wrote:
> Is there any particular reason for why we always fetch docbook style sheets
> over HTTP when running "make README" ?
>
> I can tell you that it doesn't work well with lousy connections. The result
> is an empty README file - just a few blank lines.
>
> Maybe we should consider storing the versions we use in the docbook
> directory.

This should not happen if you have a local copy of docbook xsl
stylesheets on your computer and those stylesheets can be located
using the catalog file in sip-router/docbook/catalog.xml.

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.

The whole system works as follows:

1) All documentation files refer to docbook using public identifiers.
Public identifiers use HTTP URIs as identifiers:
http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd

2) If you try to compile a docbook file into README, the toochain
needs to first convert the docbook file to HTML and then convert it to
a plaintext file with lynx. To convert the docbook file into HTML, it
needs Docbook XSLT stylesheets.

3) The processor tool consults sip-router/docbook/catalog.xml file for
instructions where to find the XSLT stylesheets. The catalog file
refers to /etc/xml/catalog which is a system wide catalog file. If you
have the XSLT stylesheets installed on your computer then they are
registered in /etc/xml/catalog and thus the tool will use the local
copy and will not download it from the internet.

4) If a local copy of XSLT stylesheets cannot be found in the catalog
then it will simply try to download it using the HTTP uri present in
the documentation file.

If you have a local copy of XSLT stylesheets for docbook (in debian
they are in the package docbook-xslt, docbook DTD files are in
docbook-xml) then there is either problem in the catalog file in
sip-router/docbook/catalog.xml or the source documentation files are
referring to a wrong version of docbook.

Which documentation files are causing problems?

  -- Jan