Chapter 6. Building the stylesheets

If you wish, you can also clone the distribution and build them yourself. The distribution is designed to be self contained. In a Unix or Mac environment, running:

./gradlew dist

will build the stylesheets. Building will:

Compile the stylesheets and run the unit tests. The compiled stylesheets will be available in build/xslt.
Running all the tests requires building the reference guide and a few other things. You can build the stylesheets without running any of the tests with the makeXslt task.
Compile the extension functions. The compiled extension functions will be available in build/libs. The jar task will compile the extensions without running the tests.
“Compile” the Python script that helps run the stylesheets. (It’s not really compiled, but several stylesheet-version-specific strings are interpolated.) The copyBin task will setup the Python script without running the tests.

☝

Important

In principle, it should be possible to build the stylesheets on Windows. In practice, it isn’t entirely reliable. It has been much improved as of version 2.1.4, but still fails randomly on some Windows machines, but not others. It may be more expedient to build in the Linux subsystem on Windows 10 or in a Docker container.

6.1. Prerequisites

In order to build the stylesheets, you must configure your system with several prerequisites:

Gradle. The stylesheet builds use the Gradle wrapper to assure a consistent environment across systems, it’ll be downloaded automatically the first time you build.
A modern version of Java. (Java 1.8 or later, for example.)
Python 3 and the click module. The Pygmentize program is also required for syntax highlighting, though that’s not technically a build requirement.

If you discover other prerequisites that have been overlooked, or have questions or suggestions about how best to manage them, please let us know.

6.2. Repository structure

The most significant parts of the repository hierarchy are:

src/main/xslt
src/main/xslt/transforms
src/main/xslt/modules

These are the sources for the stylesheets themselves. The transform subdirectory contains the preprocessing stylesheets that are run as separate transforms. The modules directory doesn’t have any special significance, it just makes the main entry points easier to find.

You cannot run the XSLT stylesheets directly from the source location. You must build them first with the makeXslt build target.

src/main/web
src/main/web/resources/css
src/main/web/resources/js

These are the CSS and JavaScript files needed for accurate rendering in the browser or formatter process.

src/main/locales/locale-10
src/main/locales/locale

The local-10 directory holds copies of the localization files from the XSLT 1.0 stylesheets. They’re transformed into the locale versions by the build system. This whole area is one that needs work.

src/test/xspec
src/test/generators
src/test/resources/xml
src/test/resources/expected

These are the testing resources. You cannot run the XSpec tests directly from src/test/xspec. The build system copies them into build/xspec along with a few XSpec tests generated automatically by the stylesheets in generators.

The library of DocBook documents that are used for testing is stored in the xml directory. The HTML files in expected correspond to the expected results. The expected results aren’t usefully viewed in a browser. Only the body element and its decendants are stored in the expected results. This avoids a lot of noise in the head.

src/main/java

These are the sources for the extension functions.

src/guide
src/website

These are the sources, resources, and ancillary files for the reference guide and the website.

tools

The tools directory holds a number of stylesheets and other scripts used by the build process.

lib

The lib directory holds third party jar files. This is also where you can put your Saxon PE or EE files if you have them.

build
build/actual
build/xslt

The build system puts all of its temporary files under build. It’s always safe to delete the entire directory and start over, though it will require internet access and it may take a while.

Test files that you format are published to build/actual and the images, CSS, and JavaScript resources are copied under there so that everything will look right in the browser. For security reasons, some JavaScript features may not work if you are looking at the documents from the filesystem. You can work around this by pointing a local web server at the build directory.

The built stylesheets are in build/xslt. You can run them directly from there.

6.3. Build configuration

Several build properties are defined in gradle.properties.

verbose: If true, enables additional messages in the extension functions.
requireCompileSuccess: If true, the build will fail if there are any errors building the stylesheets.
requireTestSuccess: If true, the build will fail if any tests fail.
xspecVersion: The version of XSpec.
xsltExplorerVersion: The version of XSLT Explorer.
pdftool: Select a tool for formatting PDFs. Expected values are antennahouse or prince.
antennahouse: The path to the Antenna House Formatter.
prince: The path to the Prince formatter.

There are four additional properties that are used by the dbtransform target. This target allows you to process arbitrary documents with the stylesheets. It takes care of loading all of the extension functions.

dbsource: The URI of the source document.
dboutput: The path for outputting the principle result document.
dbstyle: The URI of the base stylesheet, defaults to the main DocBook xslTNG stylesheet.
dbparams: Stylesheet parameters.

You can change these variables in your local version of gradle.properties, or you can specify them on the command line. For example, to enable verbose processing, pass -Pverbose=true on the Gradle command line.

6.4. Build tasks

The build system is Gradle. Gradle’s processing model operates in several phases, this allows an initial configuration phase to construct build targets (called tasks) dynamically. The DocBook xslTNG Stylesheets build script uses this facility quite a bit.

In the discussion that follows, testdoc is the base name of a test document, that is, one of the example files from the src/test/resources/xml directory. For example, one of the test documents is src/test/resources/xml/article.001.xml. In the build targets that would be the “testdoc” article.001. In an analogous way, “testset” is the root name of an XSpec test file in src/test/xspec.

The most important tasks are:

makeXslt: This tasks “compiles” the stylesheets into build/xslt.
report: This task runs all of the tests and generates a unified report in build/report. This is the default task.
test: Runs the test suite against the stylesheets.
jar: Compiles the extension functions and creates the jar file in build/libs.
dist: Builds an archive in build/distributions suitable for distribution.
guide: Builds the reference guide.
website: Builds the website.
explorer: Generates the XSLT Explorer report for the stylesheets in build/explorer.
helloWorld: A smoke test target. It just prints a message, but doing so will exercise a bunch of the build machinery in Gradle.

6.5. Testing tasks

The way tests are managed was completely refactored in version 2.0.13. The new system is largely automatic.

Create a new test document in src/test/resources/xml. For this example, we’ll create para.003.xml, an example of a sidebar in a para.
Use the build target para.003.html to format the document. This build target (and several others) exist automatically because the source file has been created.
Inspect the results (in build/actual/para.003.html) and adjust the stylesheets until you are satisfied that the results are correct. Each time you make a stylesheet change, you can re-run the para.003.html target to rebuild the output.
When you are satisified, run param.003.expected to update the expected results.
Run the report target to make sure no other tests have broken as a result of your changes.

More generally, the following targets exist for any source document in src/test/resources/xml:

testdoc.html: Formats testdoc into HTML and stores the result in build/actual where it can be viewed in the browser with the appropriate CSS, JavaScript, images, etc.
testdoc.expected: Formats testdoc into HTML and stores the result in src/test/resources/expected. You should only run this task when you’ve made a change and determined that the new results are correct and should replace the previously expected results.
testdoc.pdf.html: Formats testdoc into HTML suitable for paged media and stores the result in build/actual.
testdoc.pdf: The .pdf target will generate the .pdf.html output and then attempt to transform it into PDF with either AntennaHouse or PrinceXML. Additional configuration may be necessary to get this to work.
testdoc.chunk: Formats testdoc into HTML with chunking turned on. The result is stored in index.html and other files in build/actual. No attempt is made to avoid having the output files from different documents overwrite each other. At the moment, none of the automated tests create chunked output.
testset.xspec: Runs the testset set of XSpec tests. The test sets that are available are the sets constructed from build environments and the sets created by hand (in src/test/xspec).

6.6. Running XSpec

In order to get consistent results across different runs and in different environments, the XSpec tests run a driver stylesheet, xspec-driver.xsl.

Note also that the XSpec shell script is modified by the stylesheets.