XSLT features supporting customization

Three aspects in particular of the design of XSLT support customization efforts: support for modular stylesheets; organization as templates; and named attribute sets.

Support for modular stylesheets has been part of XSLT since the xsl:include and xsl:import top-level elements in XSLT 1.0. Even if you haven’t come across them before, you would expect from their names that they have something to do with using one stylesheet file as part of another. xsl:include does, indeed, conceptually include the contents of one stylesheet inside another, while xsl:import makes the contents of the imported stylesheet available to the importing stylesheet with well-defined rules about the “import precedence” of the content of importing stylesheets over that of imported stylesheets.

The core JATS Preview stylesheets use only xsl:include, as shown in Fig. 3.

Fig. 3

Imports and includes in JATS Preview stylesheets

The organization of XSLT stylesheets as predominately xsl:template rules that match on particular contexts in the source document makes it easy to write an importing stylesheet containing templates matching specific contexts. For example, the following template is used for processing td elements: the literal fo:table-cell is copied to the result and the xsl:call-tempate, like all elements in the XSLT namespace, is acted on by the XSLT processor.

<xsl:template match="td">
  <fo:table-cell xsl:use-attribute-sets="td">
    <xsl:call-template name="process-table-cell"/>
  </fo:table-cell>
</xsl:template>

The rules on import precedence make it easy for a customization to override the corresponding templates in the core JATS Preview stylesheets. That doesn’t mean that overriding templates is the ideal mechanism – for example, if you want to make a small change to what’s currently a large complex template, you generally have to maintain a copy of the large template with your changes added rather than being able to reach into and override just a small part of the original template – but overriding imported templates works well in the general case.

A named attribute set is a group of attribute definitions that are evaluated afresh each time they are used, and the resulting attributes are added to an element in the result of the XSLT transformation. The rules for combining multiple named attribute sets with the same name and for combining multiple different attribute sets make it easy for an importing stylesheet to augment or override the attribute sets in the core JATS Preview stylesheets.

JATS Preview Stylesheet features supporting customization

Three aspects of the design of the JATS Preview stylesheets particularly support customization efforts: global variables for font-family, etc.; using named attribute sets; and using named templates. Arguably all of these would be present in the JATS Preview stylesheets irrespective of whether the stylesheets were intended to support customization since they embody the “Don’t Repeat Yourself” (DRY) principle [[21]] where “Every piece of knowledge must have a single, unambiguous, authoritative representation within a system”. For example:

• The font family is defined once, in a variable;
• That variable is used multiple places, including in attribute definitions in named attribute sets;
• The named attribute sets are used in one or more contexts within the stylesheet; and
• The named templates encapsulate common processing actions so they aren’t repeated across multiple templates.

As a method for organising a stylesheet, it eases maintenance, but it also eases customization since the authoritative representations can be overridden and/or reused in the customizing stylesheet.

For example, the XSLT 1.0 stylesheet described in the following section includes the following two named attribute set definitions and template:

<xsl:attribute-set name="td">
  <xsl:attribute name="line-stacking-strategy">max-height</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="td-small" use-attribute-sets="td">
  <xsl:attribute name="line-height">10pt</xsl:attribute>
  <xsl:attribute name="border">none</xsl:attribute>
  <xsl:attribute name="padding-top">0pt</xsl:attribute>
  <xsl:attribute name="padding-bottom">0pt</xsl:attribute>
</xsl:attribute-set>

<xsl:template match="td[ancestor::table[@style = 'small']]">
  <fo:table-cell xsl:use-attribute-sets="td-small">
    <xsl:call-template name="process-table-cell"/>
  </fo:table-cell>
</xsl:template>

The “td” named attribute set has a definition in the main JATS Preview stylesheets, so this definition adds to that definition, and the combined attribute set is evaluated whenever the “td” attribute set is used, for example, in the “td-small” named attribute set, which is used with tables that are to be formatted with closer spacing than usual. The template for a td in such a table uses that named attribute set, which adds all the attributes from the “td-small” attribute set and from all definitions of the “td” attribute set to the fo:table-cell in the result of the transformation. The template doesn’t do much else since it is possible to use the “process-table-cell” named template from the core JATS Preview Stylesheet to handle the common aspects of formatting a table cell.

Graphics handling

Graphics at least have an intrinsic size and, in formats such as TIFF, have an intrinsic resolution as well.

The process for determining whether graphics are column-wide or page-wide is:

• Download copies of TIFF images from PLOS ONE article web page
  In production, PLOS will have the graphics available on their servers, so this is only ncessary while developing the stylesheet.
• Run ImageMagick ‘identify’ on each graphic to get its width, height, horizontal resolution, and vertical resolution and write the information to a ‘.identify’ file for each graphic
• In the XSLT stylesheet, when processing a graphic, get the contents of the corresponding ‘.identify’ file using unparsed-text(), tokenize the returned string to get the four values, then calculate the graphic’s width by dividing the width in pixels by the horizontal resolution. When the calculateed width is less than or equal to the width of a column, it is made column-wide, otherwise it is made page-wide.

The PLOS ONE authoring guidelines allow graphics sized up to the height of the page body, but figures may have captions of up to 300 characters, as well as having a label, title, and DOI that also appear in the formatted output. XSL doesn’t allow floated FOs to break across a page, so similarly to as described below for tables, the processing system ‘preformats’ the figure captions at both widths and writes out the area tree to be used as input by the main stylesheeet so the stylesheet reduces the allowed maximum height of the graphic so the graphic won’t push its following caption into the footer area.

Table handling

Tables, as noted above, are presented one of three ways – column-wide, page-wide, or page-high – depending on which best fits the content of the table. Deciding which to do is entirely up to the processing system since the source XML, converted from other sources as it was, does not include even the few presentation-oriented attributes defined by the DTD.

The NLM/JATS DTDs support [[26]] specifying the orientation of a combined table and caption but do not provide a way to indicate the width of a table. The NISO JATS table model does allow a ‘style’ attribute on table and caption, but not on the table-wrap that contains them both.

The sample files provided at the start of the project included TIFF images of each of the tables in the samples as well as TIFF files for the graphics, and it wasn’t until the project was underway that it was made clear that the images of the tables were artifacts of the existing processing system and, not only were they not going to be available for new documents, the new system was expected to produce those as well.

The implemented approach makes a temporary ‘sizer’ formatted document containing each table at each width, saves the area tree from that document as XML, and provides the area tree as a parameter to the stylesheet that produces the FO for the final formatted output.

The ‘sizer’ document comprises three page sequences that each have a different fixed width and a large height (since the formatter doesn’t support fo:root media-usage="bounded-in-one-dimension">). Every table in the source XML has an ID, so the tables on each page are given a ID unique in their FO document by prefixing a page-specific prefix to each table’s original ID. Fig. 9 shows tables from an article formatted at page-wide, column-wide, and page-high widths. The first two tables fit within a column, but the third overflows a column but not the width of a page.

Fig. 9

‘sizer’ document

The stylesheet that produces the ‘sizer’ document is very simple. A template matching the document node does all the work, and the stylesheet imports the ‘main’ stylesheet so the tables are formatted exactly as they would be in the final output. Since there are only three page types, the stylesheet does not even define any page-sequence masters, so each fo:page-sequence refers directly to a fo:simple-page-master.

  <fo:root>
    <fo:layout-master-set>
      <xsl:call-template name="define-sizer-simple-page-masters"/>
    </fo:layout-master-set>
    <fo:page-sequence master-reference="page-wide">
      <fo:flow flow-name="body" xsl:use-attribute-sets="fo:flow">
        <xsl:apply-templates select="//table-wrap">
          <xsl:with-param name="prefix" select="'page-wide-'" as="xs:string" tunnel="yes" />
        </xsl:apply-templates>
      </fo:flow>
    </fo:page-sequence>
    <fo:page-sequence master-reference="column-wide">
      <fo:flow flow-name="body" xsl:use-attribute-sets="fo:flow">
        <xsl:apply-templates select="//table-wrap">
          <xsl:with-param name="prefix" select="'column-wide-'" as="xs:string" tunnel="yes" />
        </xsl:apply-templates>
      </fo:flow>
    </fo:page-sequence>
    <fo:page-sequence master-reference="page-high">
      <fo:flow flow-name="body" xsl:use-attribute-sets="fo:flow">
        <xsl:apply-templates select="//table-wrap">
          <xsl:with-param name="prefix" select="'page-high-'" as="xs:string" tunnel="yes" />
        </xsl:apply-templates>
      </fo:flow>
    </fo:page-sequence>
  </fo:root>
</xsl:template>

The only template needed to override the default processing just stops bibliographic cross-references or references to supplemantary material generating a fo:basic-link just so there’s no warnings from the XSL formatter about unresolved cross-references:

<xsl:template match="xref[@ref-type = ('bibr', 'supplementary-material')]">
  <xsl:apply-templates />
</xsl:template>

The main stylesheet declares variables for the page width, margins, etc., so the same values are used in the main stylesheet to produce the final output and to work out whether graphics should be page-wide or column-wide and used in the ‘sizer’ stylesheet to set the pages’ dimensions.

As stated previously, the area tree for the ‘sizer’ document is saved as XML, and the filename of the area tree XML passed in to the main stylesheet, when run separately, as a parameter value. When the stylesheet comes to process a table-wrap, it looks up the dimensions of the table variants in the ‘sizer’ area tree and, based on the dimensions, decides which format of the table to use. Fig. 10 shows two of the tables from the previous ‘sizer’ document in the final formatted output.

Fig. 10

Formatted pages

Current capabilities include automatic sizing of tables to be column-wide, page-wide, or page-high (either column-width or page-width), with manual overrides available to force a table to be page-wide or page high, plus automatic breaking of tables that are too high (or, for page-high tables, too wide) for the available space. When tables are broken into multiple subtables, each subtable gets its column widths from the ‘sizer’ table both so the subtables use the same widths and to avoid the automatic table algorithm optimising each subtable and leaving space at the bottom of a page.

A final ‘splitter’ stylesheets checks the area tree from the previous pass to ensure that all the floated figures and tables appear before the supplementary material, acknowledgments, and references. If the floats do overlap with this back-matter, the stylesheet splits the back-matter into a separate fo:page-sequence to prevent the overlap.

It wasn’t necessary to produce TIFF images of each table, but if it were required, the main stylesheet would output a separate FO document with individually-sized page dimensions for each table. Those FO documents would then be formatted to PDF or PostScript and then converted to TIFF using ImageMagick.