NLM/NCBI Journal Publishing 3.0 Preview Stylesheets:
Technical documentation

Stylesheets in this package

While the preview stylesheets in this distribution are intended as fairly comprehensive solutions, the supporting stylesheets may serve simply as demonstrations of how to achieve common tasks. Projects should feel free to copy, modify or extend any of them in order to support local requirements better.

Using the provided shell stylesheets

The easiest way to apply either of the preview stylesheets is to use one of the shell ("wrapper") stylesheets with Saxon, the XSLT 2.0 engine, as described in the Quick Start and User guides. The shell stylesheets use Saxon extensions to apply a set of transformations in sequence quickly, with a minimum of memory or disk overhead. Each one calls one or the other main preview stylesheet, with different pre- or postprocessors depending on its intended application.

As delivered, each shell stylesheet provided also depends on the module main/shell-utility.xsl to function. This module must be in place, and its location in relation to the stylesheets named in the shell must be stable, for things to work.

Because running the XSL-FO previews stylesheet also entails running an XSL-FO formatter, there are slightly different considerations in setting this up for each type of output:

Extending or writing your own Saxon shell stylesheet

The shell stylesheets included in this package all have the same logic. Stylesheets to be called in and applied to the source data, in sequence, are named in a variable in the stylesheet. Inserting or removing components is as easy as changing this variable.

For example, the stylesheet jpub3-PMCcit-xhtml.xsl has the variable $processes declared as follows:

<xsl:variable name="processes">
  <step>citations-prep/jpub3-PMCcit.xsl</step>
  <step>preview/jpub3-html-preview.xsl</step>
  <step>post/xhtml-ns.xsl</step>
</xsl:variable>

<xsl:variable name="processes">
  <step>prep/jpub3-webfilter.xsl</step>
  <step>citations-prep/jpub3-PMCcit.xsl</step>
  <step>main/jpub3-html-preview.xsl</step>
  <step>post/xhtml-ns.xsl</step>
</xsl:variable>

Of course, we recommend copying a shell with a new name and making changes there, in order to preserve the integrity of files in the distribution.

All paths given are relative to the shell stylesheet at the top level of this distribution.

Note that configuration of the output serialization using the xsl:output instruction is designated by the shell stylesheet. Accordingly, a shell stylesheet intended to generate plain HTML might have method="html" indicated in its xsl:output, while a shell stylesheet generating XHTML should have method="xhtml".

Designing and running your own pipeline

The shell stylesheets are provided for convenience, but they do introduce a dependency on the Saxon XSLT processor. You can remove this dependency by implementing a pipeline in the framework of your choice, including shell scripts or batch files, scripting languages, build tools such as Unix make or Apache Ant, or full-blown pipeline processors possibly including XProc implementations.[4]

The principle is simple: each step in the pipeline generates results that are taken as the input for the next step in the pipeline. Serialization may follow each step (if each pipeline reads its input from the file system) or may be performed only after the last step (if steps are connected using event streams or if intermediate results are held in memory).

Keep in mind that an XSLT engine will still be required to run the separate steps, and that several of the stylesheets provided do require an XSLT 2.0 processor.

Running without a pipeline

Running a single preview stylesheet standalone is not recommended since no support for formatting of citation elements is provided outside the preprocessors designed for that purpose. Nevertheless, if bibliographic citations are not an issue, either the HTML or the XSL-FO preview transformation can be run in an XSLT 1.0 processor, including client-side (in a web browser or other XSLT-capable display engine).

CSS stylesheet

HTML results are generated with a link to jpub-preview.css, given as a relative path that expects the named file to be in the same subdirectory as the HTML result file (or the XML source file if it is processed directly in a browser).

This can be altered at runtime by overriding the value of the css parameter supplied to the main HTML Preview stylesheet. This allows a CSS stylesheet with another name to be used or a stylesheet to be located elsewhere. If an empty string is provided, the HTML results will have no link to an external CSS.

Of course, altering jpub-preview.css or providing your own CSS stylesheet is an easy way to alter the look and feel of output without editing any XSLT. Many of the basic settings in the HTML presentation, including fonts, rules, colors (including the colors of warnings or generated text) may be customized in this way.

Enabling autonumbering in the XSLT

As described in the User's Guide, the Preview stylesheet does not generate labels with automatic numbering for elements in presentation, except the fn and ref elements as described there. However, the stylesheets are provided with templates that can be modified in order to provide automated numbering. See the templates in mode "label-text" in the stylesheets.