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

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

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

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

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. These don’t all work reliably because of different parameter settings. But it can be useful for quick testing of a particular set of features.

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.

tagnameTest

The build file constructs tests for different tag types. For example, to run all the XSpec tests that involve “revhistory”, you can use the target revhistoryTest. In practice, this feature is little used and may not be wholly up-to-date with respect to the most recent tests.

helloWorld

A smoke test target. It just prints a message, but doing so will exercise a bunch of the build machinery in Gradle.

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