Subscribe to Dr. Macro's XML Rants

NOTE TO TOOL OWNERS: In this blog I will occasionally make statements about products that you will take exception to. My intent is to always be factual and accurate. If I have made a statement that you consider to be incorrect or innaccurate, please bring it to my attention and, once I have verified my error, I will post the appropriate correction.

And before you get too exercised, please read the post, date 9 Feb 2006, titled "All Tools Suck".

Saturday, January 09, 2010

PDF2 Transform Now Enabled for Plugin-Based Extension

In the latest 1.5 Toolkit distributions, the PDF2 transform has been enabled for plugin-based extension. This means that you can use normal plugin techniques to provide extensions to the PDF processing that support specializations or global overrides, rather than customizations for specific publication sets or book designs.

As originally implemented, the PDF2 processor could only be extended through its unique Customization facility, whereby you either add things to its built-in Customization directory or create copies of that directory and then specify where the Customization directory is as a parameter to the transform. This is appropriate for customizations that are not global, that is, they are specific to particular publications, sets of publications, products, or whatever.

It is not appropriate, however, for providing general extensions, such as support for new domains where the domain-specific processing would normally be the same in all outputs or where the base processing is the same but can be customized using the normal PDF2 customization facilities.

In the latest DITA 1.5 Toolkit, you can now have both plugin-provided extensions as well as Customization-based extensions. This makes it easy to provide generic PDF2 support for specializations or provide global overrides for existing topic and map types.

A PDF2-extending plugin can provide only overrides, or only a Customization directory or both.

For example, for DITA for Publishers, I've started implementing support for the Publication Map (pubmap) map domain, which is similar to bookmap but tailored for Publishers. To support the PDF2 transform, I've created a plugin that provides both general extensions and a base Customization directory that can be used as a basis for local customizations.

The directory structure of the plugin is:

Where the Customization/ directory follows the rules and conventions for the PDF2 Customization directories and xsl/ holds the plugin-provided XSLTs that extend the base PDF2 processing.

The plugin.xml file looks like this:

<plugin id="">
<require plugin=""/>
<require plugin=""/>
<require plugin=""/>
<feature extension="dita.xsl.xslfo"
value="xsl/pubmap2xslfo.xsl" type="file"/>

The elements are indicating dependencies on other PDF2-extending plugins for the different domains that DITA For Publishers provides.

The line is what integrates the XSLTs into the main PDF2 XSLT transforms and it works just as for the HTML plugins, namely, the integrator.xml Ant tasks adds an xsl:include of the plugin-provided XSLT module into the main PDF2 transform shell XSLT.

One thing that plugin-provided PDF2 transforms can do is define additional customization points: named attribute sets, named variables, and new XSLT modes, which can then be customized using the normal PDF2 customization mechanisms.

In the case of the pubmap extensions, I've extended the XSLT so that publication maps produce the same output as bookmaps (that is, a pubmap-d/chapter topicref goes through the same base processing as a bookmap/chapter topicref) and added support for DITA for Publishers-specific topic types, in particular, sidebar, which gets a box around it by default (XSL-FO 1.1 can't render multi-page floats, which would be the ideal way to render sidebars).

This enhancement to the PDF2 processor, along with the many other improvements made by the Suite Solutions team, makes it much easier to extend and customize the processor and, in particular, support new domains and topic types. The Customization process is as it was, but now you only need to use XSLT in your customization when you need truly customization-specific processing (for example, generating a publication-specific title page or copyright page).


Post a Comment

<< Home