Packager XSLT Support

Parameters

td.online and td.offline

Boolean parameters passed by the <@package.docContents> directive. td.online will always be false and td.offline will always be true. These parameters will also be passed to templates used by the online <td.content> tag, where the reverse values will be used. This will allow the use of common XSLT modules for both online and offline.

td.packageLocation

The package folder path containing the file being written in the package from the primary output of the stylesheet. Any secondary result documents will be written to the package relative to this location.

td.packager

The name of the packager.

Functions

The following functions are all in the http://www.titaniasoftware.com/xmlns/td-packager name space.

package:relativeUri(to[,secondaryFromLocation]) function

Essentially the same as package.relativeUri() in the Freemarker Functions list. Determines a relative URI to the specified location, except to is always a string. The optional secondaryFromLocation argument specifies the location of the current secondary result document relative to the primary output (given by the td.packageLocation parameter). An empty secondaryFromLocation argument will be ignored.

When TD processes an XML document, it normalizes all references into URIs of the form harp://stuffIdentifyingTheDocument or puckditaxref:referenceId. If the specified target is one of those formats, this function will determine the location of the specified document in the package, and use the package configuration to determine the target URI. Otherwise, the path should be an absolute location within the archive.

<xsl:template match="xref[@scope='local' and @format='dita']">
  <a href="{package:relativeUri(@href)}">
	<xsl:apply-templates/>
  </a>
</xsl:template>

The following example illustrates how package:relativeUri() can be used while creating a secondary result document.

<xsl:variable name="result-doc" select="concat('sub/doc',position(),'.html')"/>
<xsl:result-document href="{$result-doc}" method="html">
  <xsl:apply-templates>
    <xsl:with-param name="doc-href" tunnel="yes" select="$result-doc"/>
  </xsl:apply-templates/>
</xsl:result-document>
<xsl:template match="xref[@scope='local' and @format='dita']">
  <xsl:param name="doc-href" tunnel="yes"/>
  <a href="{package:relativeUri(@href,$doc-href)}">
    <xsl:apply-templates/>
  </a>
</xsl:template>

package:mediaReference(href[,secondaryFromLocation]) function

This will determine the packaged location of the referenced media object, add the media object to the archive if necessary, and return a relative path to the media object. The optional secondaryFromLocation argument specifies the location of the current secondary result document relative to the primary output (given by the td.packageLocation parameter). An empty secondaryFromLocation argument will be ignored.

<xsl:template match="image">
  <img src="{package:mediaReference(@href)}"/>
</xsl:template>

Important: Stylesheets making use of this function should always be called by passing storeOutput=false and/or ignoreCache=true on the <@package.docContents> directive. Otherwise subsequent renderings for the same input will not add the media to the archive.

Other XSLT Processing Details

The following XSLT constructs behave slightly differently when being used in the context of <@package.docContents>.

document() function

The document() function is a built-in XSLT function for reading an XML document. In the context of the packager, attempts to open a harp:// or puckditaxref: URL will attempt to read the referenced TD document.

<xsl:result-document>

The <xsl:result-document> element will write its contents to some location other than the default XSLT output. When used within a packager, the result will be an entry in the package. In this way, package developers can "burst" a single XML document into multiple package artifacts.