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:

  1. 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.

  2. 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.

  3. “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 doesn’t work. One would imagine that mapping path (“:”→“;”) and filename (“\”→“/”) separators and constructing URIs for paths (“C:\Users\…”→“file:///C:/Users/…”) would make it work. In the author’s experience, that is not the case. Pull requests are welcome. 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.1.1. Saxon EE

You don’t need a Saxon EE license to build or run the stylesheets. If you change any of the transforms in src/main/xslt/transforms, you will need a Saxon EE license to recompile them as exported SEF files.

If you don’t have an EE license, the build process will simply omit the SEF versions and the “source” versions, including any modifications that you’ve made, will be used.

That’s the theory, anyway. I’ve tested it, but if you have any trouble, please open an issue.

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 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.4. Testing tasks

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

  1. 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.

  2. 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.

  3. 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.

  4. When you are satisified, run param.003.expected to update the expected results.

  5. 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).a

6.5. 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.