Re: Another question about Boost Documentation

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2024-08-19 00:05:50

On 8/18/24 20:34, Robert Ramey via Boost wrote:
> There are many places where the boostbook xml/xsl files make reference
> to external files that we have no control of.  Here is an example from
> modular-boost/tools/boostbook/xsl/docbook.xsl
> 
> <?xml version="1.0" encoding="utf-8"?>
> <!--
> Â Â  Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
> 
> Â Â  Distributed under the Boost Software License, Version 1.0.
> Â Â  (See accompanying file LICENSE_1_0.txt or copy at
> Â Â  http://www.boost.org/LICENSE_1_0.txt)
> Â  -->
> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
> Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â  xmlns:xi="http://www.w3.org/2001/XInclude"
> Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â  version="1.0">
> Â  <xsl:import
> href="http://docbook.sourceforge.net/release/xsl/current/common/common.xsl"/>
> Â  <xsl:include href="reference.xsl"/>
> ...
> 
> This means that if something changes in
> 
> docbook.sourceforge.net/release/xsl/current/common/common.xsl
> 
> We'll have problems when we try to build documentation.  This recently
> happened to me and it was a bitch to find.  I spent some time looking
> around for the right way to fix this and came upon the concept of XML
> catalogs as explained here:
> 
> https://en.wikipedia.org/wiki/XML_catalog#Example_Catalog.xml
> 
> Seems to me that the maintainer of boostbook should verify that my
> understanding is correct and update boostbook files accordingly.
> 
> Actually, I'd be grateful to any insight on this subject that anyone
> might provide.

I'm by no means an XML guru, but my understanding is that XML catalog is
part of the user's system configuration. For example, installing
docbook-xml package on Ubuntu installs catalog files in
/usr/share/xml/docbook/schema/dtd/<version>/. These files describe
where, on the local system, the local XML/XSL files are installed by the
package.

I don't know how it works on Windows, but there should be a location
where the catalog files are searched.