Another question about Boost Documentation

From: Robert Ramey (ramey_at_[hidden])
Date: 2024-08-18 17:34:08

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.

Robert Ramey