so

One more thing…

Volume 2, Issue 9; 10 Mar 2018

A few notes about using the DocBook stylesheets without Gradle and on catalogs in jar files.

Since I posted about the DocBook XSLT 2.0 Stylesheets a few days ago, I’ve made a few refinements to the stylesheets distribution.

That last post was about how easy it is to use the stylesheets in a Gradle project to format DocBook documents. That isn’t going to suit everyone. If you don’t want to use Gradle, or you can’t, or you’ve already got a build system in place and you don’t want to change it more than you have to, that’s fine.

One option is to simply download the zip file (e.g., docbook-xslt2-2.3.1.zip), unpack it where you like, and have at it. You’ll need to setup your favorite XProc processor to run the pipelines, or decompose the pipeline workflow into steps using some other tool, but that’ll work.

Another option, at least for simple workflows, is to download the “-app” zip file (e.g, docbook-xslt2-2.3.1-app.zip), unpack it where you like, and run the pipeline directly. Unpacking the zip file will create a directory containing a jar file and a subdirectory of “lib” jars. You can run the stylesheet jar directly from that location:

java -jar /path/to/docbook-xslt2-2.3.1.jar mydocument.xml

The “app” distribution includes all of the open source libraries required to run the pipeline. If you need additional libraries, for example, for print formatting, put them on your classpath, or simply copy them into the lib/ directory.

Making catalogs

The other thing that the Gradle task does is construct a catalog file for the resources in the jar file. It then makes sure that catalog is added to the resolver before running the pipeline.

If you’re incorporating the stylesheets into your own build system, you can get the catalog with a few simple lines of Java (or your favorite JVM language). Here’s a toy example:

import org.docbook.XSLT20;

public class TestJvm {
    public static void main(String[] args) {
        XSLT20 docBookXslt = new XSLT20();

        String catalog = docBookXslt.createCatalog();

        // This catalog is a temporary file and will be deleted automatically.
        System.out.println("Temp catalog: " + catalog);

        catalog = docBookXslt.createCatalog("/tmp/dbcat.xml");

        // This catalog is "permanent"; you have to delete it yourself.
        System.out.println("Perm catalog: " + catalog);
    }
}

If you’re running the build inside a single JVM, the first form will create a catalog file that automatically gets deleted when the process finishes. If you’re running it in separate calls to the JVM, from make, for example, then use the latter form to create a persistent catalog.

For those who are curious, the resulting catalog has entries that look like this:

<uri name="https://cdn.docbook.org/release/2.3.1/xslt/base/html/final-pass.xsl"
     uri="jar:file:/home/ndw/…/docbook-xslt2-2.3.1.jar!/xslt/base/html/final-pass.xsl"/>

The XMLResolver supports jar: scheme URIs and will return the final-pass.xsl file from the jar when referenced with the URI from the CDN. No network access is required.

One last note, it’s also possible to obtain the catalogs through reflection, if you don’t have, or want to have, the DocBook XSLT classes as compile time dependencies. Here’s how the DocBook Task loads the schemas catalog:

String schemaCatalog = null
try {
    Class klass = Class.forName("org.docbook.Schemas")
    Object schemas = klass.newInstance()
    Method method = schemas.getClass().getMethod("createCatalog")
    schemaCatalog = "file://" + method.invoke(schemas)
} catch (ClassNotFoundException cfne) {
    // not found
}

Here’s hoping that’s useful to someone.

Please provide your name and email address. Your email address will not be displayed and I won’t spam you, I promise. Your name and a link to your web address, if you provide one, will be displayed.

Your name:

Your email:

Homepage:

Do you comprehend the words on this page? (Please demonstrate that you aren't a mindless, screen-scraping robot.)

What is nine times seven?  (e.g. six plus two is 8)

Enter your comment in the box below. You may style your comment with the CommonMark flavor of Markdown.

All comments are moderated. I don’t promise to preserve all of your formatting and I reserve the right to remove comments for any reason.