so

DocBook “by hand”

Volume 3, Issue 20; 14 Sep 2019

The easy way to publish DocBook documents “by hand”.

A while back, I wrote about making DocBook easy to use. (Perhaps “easier to use” would be a more fair assertion.) That was an introduction to the work I’d done to make formatting DocBook documents with the DocBook XSLT 2.0 Stylesheets easier.

Recently, I had occasion to setup a build system without all of the Gradle and Maven infrastructure. Here’s a summary of how that works.

By far the hardest part is getting all of the dependencies sorted out. But if you’re not using a Maven, I assume you’ve worked out some other mechanism for dealing with your class path.Fair warning: there are a lot of dependencies for the solution outlined here because we’re really running XML Calabash behind the scenes. Get everything on your class path.

If you grab the version 2.3.16 release of the DocBook XSLT 2.0 Stylesheets, you can “execute” the jar file:

java -jar docbook-xslt2-2.3.16.jar mydoc.xml
     --style mystyle.xsl -o mydoc.html \
     verbatim.markup=1

That will process mydoc.xml with mystyle.xsl to produce mydoc.html. The last line just demonstrates how you can pass parameters to the stylesheet.

The stylesheet also has a special form:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns="http://www.w3.org/1999/xhtml"
                xmlns:db="http://docbook.org/ns/docbook"
                xmlns:t="http://docbook.org/xslt/ns/template"
                exclude-result-prefixes="db t"
                version="2.0">

<xsl:import href="https://cdn.docbook.org/release/xsl20/current/xslt/base/html/final-pass.xsl"/>

<!-- Everything below this line is just for the example. -->

<xsl:param name="verbatim.markup" select="'1'"/>

<xsl:template match="db:markup">
  <xsl:choose>
    <xsl:when test="$verbatim.markup = '0'">
      <xsl:call-template name="t:inline-charseq"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:call-template name="t:inline-monoseq"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

</xsl:stylesheet>

The important bit is to import the final-pass.xsl stylesheet from the distribution.

You can download the distribution, unpack it, and make relative file references, of course. But if you use the CDN URI as I’ve shown above, you don’t have to. The main class that you execute with Java will construct a catalog dynamically that resolves the current versions of the stylesheets to files in the jar file. That means you’ll automatically get the correct versions whenever you update the jar file.

If you want to point to a specific version, you can do that too. But then you’ll probably want to setup the resolver so that it can get them locally. My XML Resolver will cache them for you automatically, or you can download them.

You might find a minimal .calabash configuration file useful as well:

<cc:xproc-config xmlns:cc="http://xmlcalabash.com/ns/configuration">
  <cc:schema-aware>false</cc:schema-aware>

  <cc:entity-resolver class-name="org.xmlresolver.Resolver"/>
  <cc:uri-resolver class-name="org.xmlresolver.Resolver"/>

  <cc:extension-function class-name="org.docbook.extensions.xslt20.Cwd"/>
  <cc:extension-function class-name="org.docbook.extensions.xslt20.ImageProperties"/>
</cc:xproc-config>

This one configures the resolver classes and identifies the extension functions that are useful in DocBook stylesheets.

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 minus six?  (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.