[clisp/doc/Makefile patch attached]
This patch adds support for making and using an XML
catalog during the doc build, so developers can specify
the location for the DocBook stylesheets at run time.
Problem: The following files all have a hard-coded
"/usr/share/docbook-xsl" path where it'd be better to
have the "canonical" URI for the DocBook stylesheets
So developers are required to manually edit those files
are replace the pathname with the correct path for
their own systems (if they are not using catalogs), or
the canonical URI (if they are using catalogs or if
they don't have the stylesheets installed locally.
Solution: Give developers the run-time option of
specifying the location of the DocBook stylesheets on
their system, using an XML catalog.
So, even if the hard-coded path names are retained in
the files listed above, developers can override that at
run-time and point the build at the correct location
for the DocBook stylsheets on their systems.
The way to do that is this:
Passing the CATALOG_FILE variable to make triggers the
creation of a catalog file with the specified name; if
no CATALOG_FILE variable is specified, the makefile
logic is conditionalized such the not catalog file is
created or used.
The STYLESHEETS_PATH variable specifies the path to the
DocBook stylesheets directory on the local system.
The STYLESHEETS_URI variable is whatever URI is
actually used in the files listed above. If the URI in
those files is changed to the canonical URI above,
specifying the STYLESHEETS_URI variable at run time
won't be necessary. Instead, you can just do this:
(Or if the default for STYLESHEETS_URI is changed to
/usr/share/docbook-xsl/ in the Makefile. Which I
Setting CATALOG_FILE creates an XML catalog that remaps
all $STYLESHEETS_URI references to $STYLESHEETS_PATH.
Then, every time xsltproc is called, it is called in
such a way as to cause it to use that catalog.
Bonus: This patch also adds some fallback logic for
finding xml.soc file, if it is not in one of the
locations already coded into the makefile. It uses the
locate(1) command and so will only help if you have an
up-to-date locatedb on your system (if you don't, the
added logic won't hurt anything).