the DITA-to-InDesign XSLT libraries can be used for this purpose but the project does not provide any examples of
Finally, the DITA-to-InDesign process does not use InDesign's built-in XML handling facilities in any way. These
facilities are too limited to allow a general and fully-functional solution to generating best-possible InDesign
documents from XML. Rather, the DITA-to-InDesign framework is predicated on generating complete InDesign
documents directly, which provides full control over all aspects of the final InDesign document except final layout,
which can only be done by InDesign itself.
Note: As of release 0.9.11 of the DITA for Publishers materials there is no general DITA-optimized InDesign
template that would enable generic DITA-to-InDesign transforms. Providing such a general-purpose template
has always been a design goal of the DITA-to-InDesign project but to date the users of the DITA-to-InDesign
technology have not needed it because they have all had pre-existing InDesign templates and paragraph style
sets. Development of such a general-purpose template is on the short-term development plan for DITA-to-
InDesign, such as it is.
The DITA-to-InDesign framework can be used in any one of the following ways:
1. Generate just InCopy articles (text content only) that are then manually placed into InDesign documents.
This process is appropriate for highly-designed and variable publications such as magazines where it would be
impossible or impractical or just not very helpful to generate the InDesign document as well. This is the simplest
use of the DITA-to-InDesign framework as it can involve only the DITA-to-InCopy XSLT transform.
2. Generate InCopy articles and a corresponding InDesign document, based on a template InDesign document, that
links in each InCopy article.
This process is appropriate for documents where the page layout and general arrangement of pages and frames
does not change from title to title, such as less-highly-designed magazines or books with consistent styles. This
process can only provide limited layout automation, essentially limited to the first page or first two pages of each
article. More automation is possible through custom InDesign scripting or when the individual articles have
limited or invariant scope, such as always being exactly one page.
The output of this process is a initial set of InCopy articles and an InDesign document ready for refinement by a
Designer. Because the articles are linked from the InDesign document, they can be updated (regenerated or
modified by hand) without disturbing the page layout defined in InDesign. This can allow authors and designers to
work in parallel as the content is being developed and completed. The main limitation is that any formatting
changes made to InCopy articles by a Designer are unavoidably lost if the article is regenerated.
3. Generate a single InDesign document with all stories included directly (not as separate InCopy articles).
This process is appropriate when the layout is mostly or entirely automated or there is some other reason not to
keep the articles separate. This approach generally presumes that the Designer will touch the InDesign document
once and then be done with it.
Options (2) and (3) require use of the Java INX support library in order to generate the InDesign document. While
INX is nominally an XML format, manipulating it is pretty much beyond what on can do productively with XSLT.
The INX support library provides a full abstract data model for manipulating and creating INX documents, allowing
you to do anything that doesn't require knowledge of how flowing content is formatted. For example, you can create
new spreads, pages, and frames, create or link stories or media files, calculate the relative geometry of frames and so
Note: The Java INX processing is currently not usefully parameterized or configuration driven. Work is being
done on this but to date use of the INX library has been very ad-hoc and client-specific.
Generating InCopy and InDesign effectively requires some understanding of how InDesign works and general
techniques for optimizing your InDesign templates and paragraph and character styles to enable maximum
automation. Many of these optimizations are not things that Designers normally do so you will likely need to work
closely with your Designer to help them understand how to add the necessary enhancements to your InDesign
This section uses the term "Designer" to mean anyone preforming the task of creation or modification of InDesign
documents, and in particular, the design of the visual aspects of documents such as page design, typographic details,
and so on, as well as doing the manual work required to create final-form printed documents uisng InDesign. One of
DITA For Publishers | The DITA For Publishers Word to DITA and DITA to InDesign Tools | 55
the design goals of the DITA-to-InDesign tools is to automate the manual aspects of this job as much as possible,
allowing Designers to focus on the creative design aspects of documents, rather than the non-creative tasks of simply
getting content into InDesign.
DITA-to-InDesign does not change the roll of Designers as Designers, that is, as the implementors of specific visions
for the visual presentation of information because it leaves the design task in the design tools domain rather than
moving it into the data processing domain as in the case of batch formatting systems such as XSL-FO and similar
non-interactive composition software.
Overview of the InDesign and InCopy Products
Adobe InDesign and InCopy are companion products, part of Adobe's Creative Suite set of products. InDesign is a
desktop publishing tool widely used in Publishing and where typographic quality and layout sophistication are
Adobe InDesign is a general-purpose desktop publishing system primarily intended for the interactive creation of
print publications with high typographic quality and arbitrarily complex page layouts. It is not an automatic
composition tool, although it enables a degree of automation through scripting using Adobe ActiveScript (a form
batch processing of InDesign documents. InDesign documents are stored natively as binary files. They may also be
exported and imported in two different XML formats: The InDesign Interchange format (INX) and the InDesign
Markup Language (IDML). The DITA-to-InDesign framework works with the INX format exclusively.
Adobe InCopy is a companion product to InDesign intended for editorial authoring. It provides the "story editor"
component of InDesign, allowing authors to create content without the ability to modify the visual layout or design of
documents. InCopy documents ("articles") are stored natively as XML files (INCX). InCopy articles may be linked
into InDesign documents or they may be copied into InDesign documents, as appropriate. InCopy articles that are
linked can be updated independently from the InDesign documents that use them, whereby the InDesign document
provides the option to use the updated content.
The division between InDesign for design and typography and InCopy for content provides a useful separation of
concerns that the DITA-to-InDesign process takes advantage of. It allows Designers to focus on the design aspects of
documents: the page layouts, paragraph and character style details, etc., while content authors can focus on the
content without fear of disrupting the design. InCopy also provides some simple collaboration features by which
multiple authors can work on the same article from a shared storage area such as a network drive.
An InDesign document consists of a sequence of "spreads", where a spread is one or more pages and some number of
frames. Frames contain either text or graphics and thereby hold the content of the document. Pages have associated
"page masters", which define the static components of the page (headers, footers, etc.) and can also provide template
frames for use in individual page instances.
Frames may be "threaded" together to create a sequence of frames through which content will flow automatically
when placed into the first frame of the sequence.
Text content is organized into "stories", where a story is a sequence of paragraphs. Stories are "placed" into
documents by associating them with text frames. A given text frame can be associated with at most one story.
A story may be stored within the InDesign document or stored externally as an InCopy article and linked into the
InDesign document. Linked stories can be updated outside of InDesign and InDesign will detect the new version and
give the InDeisgn operator the option of updating InDesign's internal copy of the story.
InDesign documents can also link in graphics, which are placed into graphic frames. InDesign supports a wide variety
of graphic formats.
InDesign documents can be rendered to PDF and EPUB among other formats.
Generating InDesign from DITA Using the Toolkit Plugin
How to use the DITA-to-InDesign Toolkit Plugin to generate inDesign and InCopy documents from DITA content.
To use the DITA-to-InDesign transform as a Toolkit plugin simply deploy the DITA for Publishers Toolkit plugins to
your Open Toolkit directory. The DITA-to-InDesign transformation type is "indesign".
DITA For Publishers | The DITA For Publishers Word to DITA and DITA to InDesign Tools | 56
Specifies the absolute path of the directory to contain the generated output.
value to use for topics generated from topic heads.
value to use for the titles of topics generated from topic heads.
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
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.dita2indesign.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
map2indesign.style 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.
Mapping XML Elements to InDesign Paragraph and Character Styles
You define the mapping of elements to specific character and paragraph styles using simple XSLT templates.
Unlike the Word-to-DITA transformation framework, which uses a separate configuration file to define the mapping
of Word paragraphs to DITA elements, the DITA-to-InDesign process uses XSLT modules with very simple XSLT
templates. The reason for this is that the only way to fully support mapping arbitrary elements in context to styles is to
DITA For Publishers | The DITA For Publishers Word to DITA and DITA to InDesign Tools | 57
use XPath or something equivalent to it and it would be harder to define and implement a separate configuration
specification that gave you that power than it would to simply code the XSLT directly.
The base DITA-to-InDesign transform includes a module named elem2styleMapper.xsl, which defines the
default mapping for DITA elements to paragraph and character style names. However, it is unlikely that this mapping
will work for some or even any of your content, since the style names need to match your InDesign templates. Thus
you will likely need to create your own element-to-style mapper module that extends or overrides the base mapping,
either as an extension to the DITA2InDesign plugin or via a custom top-level transform that includes your custom
mapper as well as the base DITA2InDesign transform.
The element-to-style mapper looks like this:
exclude-result-prefixes="xs local df e2s"
<!-- Element-to-style mapper
This module provides the base implementation for
the "style-map" modes, which map elements in context
to InDesign style names (paragraph, character, frame,
Copyright (c) 2009 Really Strategies, Inc.
NOTE: This material is intended to be donated to the RSI-sponsored
DITA2InDesign open-source project.
<xsl:template match="/*[df:class(., 'topic/topic')]/*[df:class(., 'topic/
<xsl:sequence select="'Topic Title 1'"/>
<xsl:template match="/*[df:class(., 'topic/topic')]/*[df:class(., 'topic/
<xsl:sequence select="'Topic Title 2'"/>
<xsl:template match="*[df:class(., 'topic/ph')]"
<xsl:sequence select="'[No character style]'"/>
<xsl:template match="*[df:class(., 'topic/cite')]"
DITA For Publishers | The DITA For Publishers Word to DITA and DITA to InDesign Tools | 58
The module provides templates for two different XSLT modes; style-map-pstyle and style-map-cstyle.
The style-map-pstyle templates map elements in context to paragraph style names. The style-map-cstyle templates
map elements to character style names. Note that the same XML element may map to both paragraphs and character
runs in different contexts.
Each template does nothing other than produce a literal string that is the InDesign style name.
Looking at the first highlighted template above, the parts are:
The match statement that matches a specific context. The
value of the
attribute is an XPath expression.
Here it uses the DITA Support Library "df:class"
function to match on elements based on their DITA
values rather than their tagnames, e.g., title
within a topic that is the root of the document (as
indicated by the leading "/" in the XPath expression).
The XSLT mode this template is used in, in this case
"style-map-pstyle", indicating a template that maps to a
paragraph style name. The other possible mode is "style-
<xsl:sequence select="'Topic Title
An XSLT 2 sequence constructor used to produce the
literal string "Topic Title 1" per the value of the
attribute. Note the single quotes within the
double quotes of the attribute specification. The style
name string is the style display name as it appears in the
InDesign user interface.
The second highlighted example follows exactly the same pattern, differing only in the name of the mode ("style-
Your custom element-to-style mappings should follow the same pattern, differing only in the details of the
expression and the style name produced.
The only otther thing you may need to add is a
attribute when you need to have templates for more-
specialized elements that would otherwise match on a template for the specialization's ancestor types. In that case,
you must specify a
attribute on the
element with a value greater than 1, e.g.,
<xsl:template priority="10" ... or whatever number ensures the template will match before other
templates the element might have matched on.
For example, say your vocabulary includes a specialization of
named "foo" and a specialization of "foo" named
"bar". You want
to map to the paragraph style "Foo" but
to map to the paragraph style "Bar". You start
by creating these two match templates:
<xsl:template match="*[df:class(., 'foodomain-d/foo')]"
<xsl:template match="*[df:class(., 'bardomain-d/bar')]"
If you used these templates as is you would get "ambiguous rule match" messages for
is a specialization of
and thus matches both on a check for foo as well as bar (that is, the
would be something like "+ topic/ph foodomain-d/foo bardomain-d/bar ").
DITA For Publishers | The DITA For Publishers Word to DITA and DITA to InDesign Tools | 59
To remove the ambiguity you would add a
attribute to the template for
, forcing it to match first:
<xsl:template match="*[df:class(., 'bardomain-d/bar')]"
Now when you run the transform all the
elements will map to the style 'Bar' as you intended.
value of "0.75" for the template for the
element in the example above puts it's priority below
the default priority of "1", ensuring that the template for
will not interfere with any templates for specializations
To create your own mapping module, simply copy the base elem2styleMap.xsl file to a new location, normally
a Toolkit plugin for your extensions, remove all the templates you don't want to override, modify the ones you do,
and add any additional mappings you need.
If these mappings should be global to all InCopy generations in your environment you can use the module as an
Toolkit-provided extension to the base DITA2InDesign transformation type.
If, as is more likely, your mappings are for a specific use and not global to all InCopy transforms, then you must
create a new plugin with a new top-level transform that includes your mapping module and the base dita2indesign.xsl
Preparing InDesign Templates for DITA-to-InDesign Use
By taking advantage of InDesign features you can maximize the automation provided by the DITA-to-InDesign
The main optimization techniques are:
• Using threaded frames with frame break characters to automate layout of complex page designs such as chapter
• Defining separate page masters for each distinct page layout (meaning unique arrangement of frames)
• Defining paragraph styles for each distinct structural component that needs a distinct presentation, especially the
parts of lists (first, last, middle items, etc.).
• Using script labels on frames to enable automated placement and generation of frames based on rules applied to
the XML content.
Thread Frames for Complex Page Layouts
The most important automation enabler is the use of threaded frames coupled with the use of "frame break" characters
in the generated content.
For example, a chapter opener might use several frames to lay out the chapter number, chapter title, the opening
paragraph, an epigraph or epigram, and so on. When Designers are creating such pages by hand they typically created
disconnected (unthreaded) frames for each part and simply place the content in the frames manually.
However, the same layout can be automated by threading all the frames in the appropriate order and using Adobe-
specific frame break characters in the input to force text to start in the appropriate frame. As long as the generated text
doesn't overflow a frame before the frame break is reached, all the text will be layed out correctly.
You should always be able to take an existing page design with unthreaded frames and simply thread the frames
together to create the appropriate page master.
The generation of frame break characters is defined in the XSLT transform that generates the InCopy articles.
Use Page Masters for All Distinct Page Layouts
Designers will often not bother to set up distinct page masters for different pages where the variations are minor or
where it's easier for them to simply do it manually. However, for automation there needs to be a distinct page master
DITA For Publishers | The DITA For Publishers Word to DITA and DITA to InDesign Tools | 60
Documents you may be interested
Documents you may be interested