Tracker: Patches

5 Make and use XML catalog during doc build. - ID: 1237581
Last Update: Comment added ( sds )

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


Michael(tm) Smith ( xmldoc ) - 2005-07-13 07:40:12 PDT

5

Closed

Accepted

Sam Steingold

None

None

Public


Comments ( 8 )

Date: 2005-07-14 16:35:27 PDT
Sender: sdsProject AdminAccepting Donations

Logged In: YES
user_id=5735

thanks for your help!


Date: 2005-07-14 16:27:45 PDT
Sender: xmldocSourceForge.net Subscriber and Donor

Logged In: YES
user_id=118135

> thank a lot for your help!
> note that CATALOG_FILE is now set by default.

OK, that works too :-)

The reason I didn't have it set in the patch I
submitted was this: If somebody already has an XML
catalog environment set up on their system (like me),
with an entry for the canonical URI for the DocBook
stylesheets, that entry will be overrided by the entry
in the catalog.xml file that the CLISP doc build
creates. That may or may not be what you'd want.

Anyway, it is not a big deal, because if you do have a
catalog set up that you don't want to override, you can
just make the CLISP docs like this:

make CATALOG_FILE=

So then the conditional logic in the makefile will
cause the build of the catalog.xml file to be skipped,
and for catalog lookup, xsltproc will instead use
whatever you already have configured.

Anyway, thanks very much for implementing this. Feel
free to close this out now if you want.

I will submit another patch soon -- an attempt to
improve comment handling.

--Mike



Date: 2005-07-14 06:06:41 PDT
Sender: sdsProject AdminAccepting Donations

Logged In: YES
user_id=5735

thank a lot for your help!
note that CATALOG_FILE is now set by default.


Date: 2005-07-13 17:40:54 PDT
Sender: xmldocSourceForge.net Subscriber and Donor

Logged In: YES
user_id=118135

> I checked in something based on your patch.
> thanks!

Thank you -- I appreciate it. Your clisp.xml source is
a great "torture test" for checking features and
boundary cases in the DocBook manpages stylesheets, and
has been a big help to me. It will be great to be able
to just run a "cvs update" to get the latest version of
it and make the man page using from your build setup.
It should help me to get manpages bug reports
investigated a lot more quickly too.

But there remains one problem in the current build
setup that is preventing me from being able to build
without manually changing files. It's related to this:

> why do you need rewriteSystem twice?

The reason I had that was, you had system IDs in your
files with and without the file:// protocol specifier:

/usr/share/docbook-xsl
file:///usr/share/docbook-xsl/

xsltproc seems to see those as two different system
IDs, so I had two rewriteSystem entries in there.

The problem now is that the olink-chunk.xml and
olink-pile.xml files still have the "file://" form with
a local system path:

<!DOCTYPE targetset$
SYSTEM
"file:///usr/share/docbook-xsl/common/targetdatabase.dtd"

Now that you've changed the URIs in the other files to
the canonical (http://) URI, I think you should
probably change that to olink-chunk.xml and
olink-pile.xml to have:

<!DOCTYPE targetset$
SYSTEM
"http://docbook.sourceforge.net/release/xsl/current/common/targetdatabase.dtd"

If I make that change locally in my CVS working
directory, everything works as expected.

> DIUC that to use snapshot all I need is
> STYLESHEETS_PATH=/usr/share/docbook-xsl-snapshot/
> (no symlinks &c)

No symlinks or anything else needed. And since you have
STYLESHEETS_PATH=/usr/share/docbook-xsl-snapshot/ in
the Makefile, you can simply run make like this:

make CATALOG_FILE=catalog.xml

Whereas, in my case, since I have the stylesheets in
the /sandbox/xsl directory, I need to do:

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




Date: 2005-07-13 17:05:56 PDT
Sender: xmldocSourceForge.net Subscriber and Donor

Logged In: YES
user_id=118135

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

You are right. It's not needed.

(I had it in there because I pasted in from an
xmlcatalog shell-script wrapper I wrote.)



Date: 2005-07-13 10:55:49 PDT
Sender: sdsProject AdminAccepting Donations

Logged In: YES
user_id=5735

I checked in something based on your patch.
thanks!


Date: 2005-07-13 09:14:24 PDT
Sender: sdsProject AdminAccepting Donations

Logged In: YES
user_id=5735

DIUC that to use snapshot all I need is
STYLESHEETS_PATH=/usr/share/docbook-xsl-snapshot/
(no symlinks &c)

why do you need rewriteSystem twice?


Date: 2005-07-13 09:07:07 PDT
Sender: sdsProject AdminAccepting Donations

Logged In: YES
user_id=5735

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


Attached File ( 1 )

Filename Description Download
DIFF.diff clisp/doc/Makefile patch Download

Changes ( 5 )

Field Old Value Date By
status_id Open 2005-07-14 16:35:27 PDT sds
resolution_id None 2005-07-14 16:35:27 PDT sds
close_date - 2005-07-14 16:35:27 PDT sds
assigned_to nobody 2005-07-13 09:14:24 PDT sds
File Added 141937: DIFF.diff 2005-07-13 07:40:12 PDT xmldoc