xproc (for DocBook)

There are a bunch of files related to running Gradle (the wrapper, settings, build scripts, etc.) The files that are relevant to this project are:

• src/main/

  • css/

    • local.css

      • Local CSS customizations

    • letter.css

      • Style rules for letters

    • letterhead.css

      • Style rules for the letterhead

  • xml/

    • Sample documents (replace with your own documents)

  • xpl/

    • pdf/

      • pdf.pdf

        • Pipeline to produce PDF output

    • html/

      • html.xpl

        • Pipeline to produce HTML output

      • chunk.xpl

        • Pipeline to produce "chunked" HTML output

    • config.xml

      • An XML Calabash configuration file

    • address.html

      • The text of the "address" portion of the letterhead

    • standalone.xpl

      • A pipeline step that incline stylesheets, images, and scripts as data: URIs

  • img/

    • logotype.png

      • The image portion of the letterhead

  • xsl/

    • html.xsl

      • The plain HTML output stylesheet

    • chunk.xsl

      • The chunked HTML output stylesheet

    • letter-templates.xsl

      • Additional templates for letters

    • print.xsl

      • The print output stylesheet

    • docbook.xsl

      • A few global customizations

  • rng/

    • docbook.rnc

      • The DocBook schema with the letter customizations

• lib/

  • Empty, but any jar files added to this directory will automatically be added to the classpath

• bin/

  • xdocbook

    • A shell script that automates using the Gradle project from other directories

When the build starts, it looks at all of the documents and all of the pipelines. For document/pipeline pair, it creates a Gradle task to format that document with that pipeline. In other words, the target

doc1.html

Processes doc1.xml with html/html.xpl (to produce build/doc1.html)

doc1.chunk.html

Processes doc1.xml with html/chunk.xpl (to produce build/index.html)

doc1.pdf

Processes doc1.xml with pdf/pdf.xpl (to produce build/doc1.pdf)

And so forth. If you create a new pipeline foo.xpl in the src/main/xpl/html directory, a new target doc1.foo.html will be created automatically. Likewise, if you create a new pipeline bar.xpl in the src/main/xpl/pdf directory, a new target doc1.bar.pdf will be created.

(There’s a little special case for html.xpl and pdf.xpl to simplify the targets; that’s why it’s doc1.html and not doc1.html.html.)

As you create new pipelines and new documents, the targets are automatically created.

Running ./gradlew doc1.html will format doc1.xml into HTML as described above; running ./gradlew doc1.pdf will format doc1.xml into PDF, etc.

The build script takes care of copying all of the standard DocBook resources and your local resources into the build directory.

One caveat: the output from different documents run with the chunking stylesheet will overwrite each other. You should copy the build directory to keep them separate.

./gradlew -Pletterhead=true letter1.pdf

The xslTNG stylesheets have lots of parameters. Passing values from the command line, through the pipelines, into the stylesheets would be cumbersome. Instead, what I envision is that small custom stylesheets with the correct parameters will be created.

The bin/xdocbook script attempts to make it easy to process DocBook documents in any directory, instead of just in the src/main/xml directory. It works out the absolute location of the source, changes to the xproc project directory, and runs the Gradle script with appropriate -Psource and -Presult options.

It only works for the standard html and pdf transformations.

Since the output files will not be in the build directory, by default, the standalone option is true. That means the images, CSS, and other resources, will be inserted directly into the result using data: URIs. This makes the documents portable at the expense of some increased size.

xdocbook [options...] source-file [result-file]

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:v="http://docbook.org/ns/docbook/variables"
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 exclude-result-prefixes="#all"
 version="3.0">
<xsl:import href="/path/to/where/you/installed/docbook/xproc/src/main/xsl/html.xsl"/>
<xsl:variable name="local-css" as="xs:string+">
 <xsl:sequence select="'css/local.css'"/>
 <xsl:sequence select="'css/letter.css'"/>
 <xsl:sequence select="'/path/to/custom.css"/>
</xsl:variable>
<xsl:param name="user-css-links" select="string-join($local-css, ' ')"/>
<xsl:variable name="v:user-xref-groups" as="element()*">
 <crossref xpath="self::db:figure|self::db:example"
 group="xref-number"/>
</xsl:variable>
</xsl:stylesheet>