[ clisp-Patches-1237581 ] Make and use XML catalog during doc build.

[SourceForge.net <no...@so...>]

Patches item #1237581, was opened at 2005-07-13 10:40
Message generated for change (Comment added) made by sds
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=301355&aid=1237581&group_id=1355

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Michael Smith (xmldoc)
Assigned to: Nobody/Anonymous (nobody)
Summary: Make and use XML catalog during doc build.

Initial Comment:
[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
(http://docbook.sourceforge.net/release/xsl/current/)

  chunk.xsl
  man.xsl
  olink-chunk.xml
  olink-pile.xml
  pile.xsl

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:

  make CATALOG_FILE=catalog.xml
STYLESHEETS_PATH=/sandbox/xsl/
STYLESHEETS_URI=/usr/share/docbook-xsl/

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:

  make CATALOG_FILE=catalog.xml
STYLESHEETS_PATH=/sandbox/xsl/

(Or if the default for STYLESHEETS_URI is changed to
/usr/share/docbook-xsl/ in the Makefile. Which I
wouldn't recommend...)

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).

----------------------------------------------------------------------

>Comment By: Sam Steingold (sds)
Date: 2005-07-13 12:07

Message:
Logged In: YES 
user_id=5735

why "|| exit"? 
I think make should not need that.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=301355&aid=1237581&group_id=1355