Configuring the DITA-to-InDesign Transformation

You can generate InCopy articles from single topics or from maps using XSLT.

An InCopy article contains a single sequence of paragraphs to be placed within an InDesign frame sequence. The native format for InCopy articles is INCX, an XML format, which makes it possible to generate InCopy articles using XSLT.

The DITA-to-InDesign framework provides a general XSLT library and base transforms for generating InCopy articles from DITA source (although the library itself is not particularly DITA-specific, meaning it can be applied to sort of XML without too much effort).

The base transforms are packaged in the org.dita4publishers.dita2indesign Open Toolkit plugin. The dita2indesign transformation type provides the extendable XSLT transform dita2indesign.xsl. You can use normal Toolkit extension facilities to extend this transformation using extension point ID "xsl.transtype-indesign'.

You can also create a custom top-level XSLT transform that imports the transform dita2indesignImpl.xsl and either define a new transformation type or simply specify the transformation file as the value of the Ant property.

The basic purpose of the transformation is to map XML elements to InDesign paragraphs and character runs with the appropriate paragraph and character styles applied. All of the visual aspects of the rendition, with the exception of explicit frame breaks, are provided by InDesign through the style definitions and other layout aspects, which are defined either manually by a Designer or generated through a separate, Java-based InDesign generation process.

Thus the primary configuration task is to map elements in context to style names. This is done through an XSLT module that uses very simple XSLT templates to do the mapping. You do not need to have any knowledge of XSLT details in order to define this mapping. However, you must know at least enough XPath to be able to specify the match expressions needed by your data. However, this is a pretty small subset of XPath in most cases. The examples provided in this section should be sufficient for most tasks.

Another configuration task that may be required is emitting frame, column, or page break characters as required by your content to trigger the appropriate flowing of text through sequences of threaded frames. This is done through XSLT templates that override the base processing for paragraphs. Again, no prior XSLT knowledge is required, you simply need to copy the examples in this section and adapt them as appropriate to your content.

For more involved requirements you may need to perform more complex processing, such as using metadata values to generate paragraphs in the output, reorder elements from the input to the output, or generate multiple InCopy articles from a single topic. This requires more general knowledge of XSLT but examples of these types of processing are available to use as guides and starting points.