NISO JATS 1.0 Preview Stylesheets:
Technical Documentation

Copyright and disclaimer information for JATS preview software

The XSL stylesheets and other code (CSS, XProc, and Schematron) provided at the NCBITools/JATSPreviewStylesheets github repository (https://github.com/NCBITools/JATSPreviewStylesheets) is work is in the public domain and may be reproduced, published or otherwise used without the permission of the National Library of Medicine (NLM).

We request only that the NLM is cited as the source of the work.

Although all reasonable efforts have been taken to ensure the accuracy and reliability of the software and data, the NLM and the U.S. Government do not and cannot warrant the performance or results that may be obtained by using this software or data. The NLM and the U.S. Government disclaim all warranties, express or implied, including warranties of performance, merchantability or fitness for any particular purpose.

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 and pipelines

The easiest way to apply either of the preview stylesheets is to use one of the shell ("wrapper") stylesheets or XProc pipelines. The shell stylesheets can be run with Saxon, the XSLT 2.0 engine, and rely on Saxon-specific extensions to XSLT 2.0; the XProc pipelines can be run with any conforming XProc engine that supports XSLT 2.0 stages (no extensions are needed). Either process applies 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.

The Saxon shell stylesheets provided also depend 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 Preview stylesheet also entails running an XSL-FO formatter, there are slightly different considerations in setting things up for each type of output:

Extending the Saxon shell stylesheet or writing your own

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 jats-PMCcit-xhtml.xsl has the variable $processes declared as follows:

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

Add a step to this declaration:

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

Now, an additional preprocess prep/jats-webfilter.xsl is run before the citation preprocessing step.

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's location in the subdirectory structure.

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

Extending an XProc pipeline or writing your own

Of course, the same possibilities are available when using XProc, with many more. For example an XProc pipeline could included DTD or Schematron validation along with processing of documents (or only of valid documents, if preferred), processing sets of documents together, etc.

XProc is a W3C-standard XML process pipelining technology, documented on line.

Designing and running your own pipeline

If you don't want to use XProc or rely on the XSLT extensions supported by Saxon, you can build your own pipelines to apply the stylesheets, using the framework of your choice. Shell scripts, batch files, scripting languages, and build tools such as Unix make or Apache Ant can all be used for this purpose. 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

The stylesheets can also be run individually, without any pipeline automation at all, just by applying preprocessor stylesheets to the input, if needed, and then applying the appropriate main preview stylesheet to the output from the preprocessors.

For input that contains no bibliographic citations, or in which all the bibliographic citations are pre-formatted and conform to the "simple citation" format defined below, no preprocessors are necessary and the main preview stylesheet can be run standalone in any XSLT 1.0 or 2.0 processor (including client-side web browsers or other XSLT-capable display engines).

Note, however, that most JATS input that contains any citations at all will benefit from being passed through one of the citation preprocessors, even if all the citations in the input are mixed-citation and have the appropriate punctuation: the main preview stylesheets work best if the only elements within citations in the input are presentation-oriented elements; the preprocessors strip out all other elements inside of citations, and replace them with appropriate presentation-oriented markup.

CSS stylesheet

HTML results are generated with a link to jats-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 jats-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 and generated text) may be customized in this way.

Enabling autonumbering in the XSLT

As described in the Users' 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 variables that can be used as switches to turn on autonumbering, along with templates that can be modified (or overridden, in a customization layer) in order to control the formats of the numbers. See the stylesheets, especially the templates in mode label-text.