#15 Make and use XML catalog during doc build.

closed-accepted
Sam Steingold
None
5
2005-07-14
2005-07-13
No

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

Discussion

  • clisp/doc/Makefile patch

     
    Attachments
  • Sam Steingold
    Sam Steingold
    2005-07-13

    Logged In: YES
    user_id=5735

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

     
  • Sam Steingold
    Sam Steingold
    2005-07-13

    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?

     
  • Sam Steingold
    Sam Steingold
    2005-07-13

    • assigned_to: nobody --> sds
     
  • Sam Steingold
    Sam Steingold
    2005-07-13

    Logged In: YES
    user_id=5735

    I checked in something based on your patch.
    thanks!

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

     
  • 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/

     
  • Sam Steingold
    Sam Steingold
    2005-07-14

    Logged In: YES
    user_id=5735

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

     
  • 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

     
  • Sam Steingold
    Sam Steingold
    2005-07-14

    • status: open --> closed-accepted
     
  • Sam Steingold
    Sam Steingold
    2005-07-14

    Logged In: YES
    user_id=5735

    thanks for your help!