DITA Open Toolkit Developer Reference
The Developer Reference is designed to provide more advanced information about the DITA-OT. It is geared to an audience that needs information about the DITA-OT architecture, extending the DITA-OT, and creating DITA-OT plug-ins.
Architecture of the DITA Open Toolkit
The DITA Open Toolkit is an open-source implementation of the OASIS specification for the Darwin Information Typing Architecture. The toolkit uses Ant, XSLT, and Java to transform DITA content (maps and topics) into different deliverable formats.
Processing structure
The DITA-OT implements a multi-stage, map-driven architecture to process DITA content. Each stage in the process examines some or all of the content; some stages result in temporary files that are used by later steps, while others stages result in updated copies of the DITA content. Most of the processing takes place in a temporary working directory; the source files themselves are never modified.
The DITA-OT is designed as a pipeline. Most of the pipeline is common to all output formats; it is known as the pre-processing stage. In general, any DITA process begins with this common set of pre-processing routines. Once the pre-processing is completed, the pipeline diverges based on the requested output format. Some processing is still common to multiple output formats; for example, Eclipse Help and HTML Help both use the same routines to generate XHTML topics, after which the two pipelines branch to create different sets of navigation files.
The following image illustrates how the pipeline works for some common output types: DocBook, PDF, Eclipse Help, XHTML, JavaHelp, and HTML Help.
Processing modules
The DITA-OT processing pipeline is implemented using Ant. Individual modules within the Ant script are implemented in either Java or XSLT, depending on such factors as performance or requirements for customization. Virtually all Ant and XSLT modules can be extended by adding a plug-in to the toolkit; new Ant targets may be inserted before or after common processing, and new rules may be imported into common XSLT modules to override default processing.
XSLT modules
The XSLT modules use shell files. Typically, each shell file begins by importing common rules that apply to all topics. This set of common processing rules may in turn import additional common modules, such as those used for reporting errors or determining the document locale. After the common rules are imported, additional imports can be included in order to support processing for DITA specializations.
For example, XHTML processing is controlled by the xsl/dita2xhtml.xsl file. The shell begins by importing common rules that are applicable to all general topics: xslhtml/dita2htmlImpl.xsl. After that, additional XSLT overrides are imported for specializations that require modified processing. For example, an override for reference topics is imported in order to add default headers to property tables. Additional modules are imported for tasks, for the highlighting domain, and for several other standard specializations. After the standard XSLT overrides occur, plug-ins may add in additional processing rules for local styles or for additional specializations.
Java modules
Java modules are typically used when XSLT is a poor fit, such as for processes that make use of standard Java libraries (like those used for index sorting). Java modules are also used in many cases where a step involves copying files, such as the initial process where source files are parsed and copied to a temporary processing directory.
Processing order
The order of processing is often significant when evaluating DITA content. Although the DITA specification does not mandate a specific order for processing, the DITA-OT has determined that performing filtering before conref resolution best meets user expectations. Switching the order of processing, while legal, may give different results.
<note> element that
both uses conref and contains a
@product
attribute:
<note conref="documentA.dita#doc/note"
product="MyProd"/>If the @conref attribute is evaluated
first, then documentA must be parsed in order to retrieve
the note content. That content is then stored in the current document (or in a representation of
that document
in memory). However, if all content with product="MyProd" is filtered out, then that work is all
discarded later
in the build.
- Time is saved by discarding unused content as early as possible; all future steps can load the document without this extra content.
- Additional time is saved case by not evaluating the
@conrefattribute; in fact, documentA does not even need to be parsed. - Any user reproducing this build does not need documentA. If the content is sent to a translation team, that team can reproduce an error-free build without documentA; this means documentA can be kept back from translation, preventing accidental translation and increased costs.
@product
attribute on the reference
target will override the product setting on the referencing note. Assume that the referenced
<note> element in documentA is defined
as follows:
<note id="note" product="SomeOtherProduct">This is an
important note!</note>A process that filters out product="SomeOtherProduct" will remove the target of the original conref before that conref is ever evaluated, which will result in a broken reference. Evaluating conref first would resolve the reference, and only later filter out the target of the conref. While some use cases can be found where this is the desired behavior, benefits such as those described above resulted in the current processing order used by the DITA-OT.
Pre-processing modules
The pre-processing operation is a set of steps that typically runs at the beginning of every DITA-OT transformation. Each step or stage corresponds to an Ant target in the build pipeline; the preprocess target calls the entire set of steps.
Generate lists (gen-list)
The gen-list step examines
the input files and creates lists of topics, images, document
properties, or other content. These lists are used by later steps in the pipeline. For example, one
list includes
all topics that make use of the conref attribute; only those files are processed during the conref
stage of the
build. This step is implemented in Java.
The result of this list is a set of several list files in the temporary directory, including dita.list and dita.xml.properties.
| List file property | List file | List property | Usage |
|---|---|---|---|
| canditopicsfile | canditopics.list |
canditopicslist | |
| codereffile | coderef.list |
codereflist | topics with coderef |
| conreffile | conref.list |
conreflist | Documents that contains conref attribute that need to be resolved in preprocess. |
| conrefpushfile | conrefpush.list |
conrefpushlist | |
| conreftargetsfile | conreftargets.list |
conreftargetslist | |
| copytosourcefile | copytosource.list |
copytosourcelist | |
| copytotarget2sourcemapfile | copytotarget2sourcemap.list
|
copytotarget2sourcemaplist | |
| flagimagefile | flagimage.list |
flagimagelist | |
| fullditamapandtopicfile | fullditamapandtopic.list |
fullditamapandtopiclist | All of the ditamap and topic files that are referenced during the transformation. These may be referenced by href or conref attributes. |
| fullditamapfile | fullditamap.list |
fullditamaplist | All of the ditamap files in dita.list |
| fullditatopicfile | fullditatopic.list |
fullditatopiclist | All of the topic files in dita.list |
| hrefditatopicfile | hrefditatopic.list |
hrefditatopiclist | All of the topic files that are referenced with an href attribute |
| hreftargetsfile | hreftargets.list |
hreftargetslist | link targets |
| htmlfile | html.list |
htmllist | resource files |
| imagefile | image.list |
imagelist | Images files that are referenced in the content |
| outditafilesfile | outditafiles.list |
outditafileslist | |
| relflagimagefile | relflagimage.list |
relflagimagelist | |
| resourceonlyfile | resourceonly.list |
resourceonlylist | |
| skipchunkfile | skipchunk.list |
skipchunklist | |
| subjectschemefile | subjectscheme.list |
subjectschemelist | |
| subtargetsfile | subtargets.list |
subtargetslist | |
| tempdirToinputmapdir.relative.value | |||
| uplevels | |||
| user.input.dir | Absolute input directory path | ||
| user.input.file.listfile | Input file list file | ||
| user.input.file | Input file path, relative to input directory |
Debug and filter (debug-filter)
The debug-filter step
processes all referenced DITA content and creates copies in a
temporary directory. As the DITA content is copied, filtering is performed, debugging information is
inserted, and
table column names are adjusted. This step is implemented in Java.
The following modifications are made to the DITA source:
- If a DITAVAL file is specified, the DITA source is filtered according to the entries in the DITAVAL file.
- Debug information is inserted into each element using the
@xtrfand@xtrcattributes. The values of these attributes enable messages later in the build to reliably indicate the original source of the error. For example, a message might trace back to the fifth<ph>element in a specific DITA topic. Without these attributes, that count might no longer be available due to filtering and other processing. - The table column names are adjusted to use a common naming scheme. This is done only to simplify later conref processing. For example, if a table row is pulled into another table, this ensures that a reference to "column 5 properties" will continue to work in the fifth column of the new table.
Resolve map references (mapref)
The mapref step resolves
references from one DITA map to another. This step is implemented
in XSLT.
<topicref href="other.ditamap" format="ditamap"/>
...
<mapref href="other.ditamap"/>As a result of the mapref step, the element that references another map is replaced
by the topic references
from the other map. Relationship tables are pulled into the referencing map as a child of
the root element
(<map> or a specialization of <map>).
Copy related files (copy-files)
The copy-files step copies non-DITA resources to the
output directory, such as HTML files
that are referenced in a map or images that are referenced by a DITAVAL file.
Resolve keyref (keyref)
The keyref step examines all the keys that are
defined in the DITA source and resolves the
key references. Links that make use of keys are updated so that any @href value is replaced by the
appropriate target; key-based text replacement is also performed, and the key definition list file
is written to the
temporary directory. This step is implemented in Java.
Conref push (conrefpush)
The conrefpush step resolves "conref push"
references. This step only processes documents
that use conref push or that are updated due to the push action. This step is implemented in Java.
Conref (conref)
The conref step resolves
conref attributes, processing only the DITA maps or topics that
use the @conref attribute. This step is implemented in XSLT.
The values of the @id attribute on
referenced content are changed as the elements are pulled
into the new locations. This ensures that the values of the @id attribute within the referencing
topic remain unique.
@id and @xref attributes are updated so that they
remain valid in
the new location. For example, a referenced topic might include a section as in the
following example:
<topic id="referenced_topic">
<title>...</title>
<body>
<section id="sect"><title>Sample section</title>
<p>Figure <xref href="#referenced_topic/fig"/> contains an code sample that demonstrates ... .</p>
<fig id="fig"><title>Code sample</title>
<codeblock>....</codeblock>
</fig>
</section>
</body>
</topic>@conref
attribute, the value of the @id
attribute on the <fig>
element is modified to ensure that it remains unique in
the new context. At the same time, the <xref>
element is also modified so that it
remains valid as a local reference. For example, if the referencing topic has an @id set to
"new_topic", then the conrefed element may look like this in the intermediate
document.<section>
<section id="sect"><title>Sample section</title>
<p>Figure <xref href="#new_topic/d1e25"/> contains an code sample that demonstrates ... .</p>
<fig id="d1e25"><title>Code sample</title>
<codeblock>....</codeblock>
</fig>
</section>In this case, the value of the @id
attribute on the <fig> element has
been changed to a generated value of "d1e25". At the same time, the <xref> element has
been updated to use that new generated ID, so that the cross reference remains valid.
Resolve code references (coderef)
The coderef step resolves
references made with the <coderef>
element. This step is implemented in Java.
The <coderef> element is
used to reference code stored externally in non-XML documents.
During the pre-processing step, the referenced content is pulled into the containing
<codeblock> element.
Chunk topics (chunk)
The chunk step breaks
apart and assembles referenced DITA content based on the @chunk
attribute in maps. This step is implemented in Java.
@chunk attribute:
- select-topic
- select-document
- select-branch
- by-topic
- by-document
- to-content
- to-navigation
Move metadata (move-meta-entries) and pull content into maps (mappull)
The move-meta-entries step
pushes metadata back and forth between maps and topics. For
example, index entries and copyrights in the map are pushed into affected topics, so that the topics
can be
processed later in isolation while retaining all relevant metadata. This step is implemented in
Java.
move-meta-entries and mappull steps
have been merged.
The mappull step has been moved into move-meta-entries.
The mappull step pulls content from referenced
topics into maps, and then cascades data within
maps. This step is implemented in XSLT.
mappull step makes the following changes to
the DITA map:
- Titles are pulled from referenced DITA topics. Unless the
@locktitleattribute is set to "yes", the pulled titles replace the navigation titles specified on the<topicref>elements. - The
<linktext>element is set based on the title of the referenced topic, unless it is already specified locally. - The
<shortdesc>element is set based on the short description of the referenced topic, unless it is already specified locally. - The
@typeattribute is set on<topicref>elements that reference local DITA topics. The value of the@typeattribute is set to value of the root element of the topic; for example, a<topicref>element that references a task topic is given a@typeattribute set to "task"". - Attributes that cascade, such as
@tocand@print, are made explicit on any child<topicref>elements. This allows future steps to work with the attributes directly, without reevaluating the cascading behavior.
Map based linking (maplink)
This step collects links based on a map and moves those
links into the referenced topics. The links are
created based on hierarchy in the DITA map, the @collection-type
attribute, and relationship tables.
This step is implemented in XSLT and Java.
The maplink module runs an XSLT stylesheet that
evaluates the map; it places all the generated
links into a single file in memory. The module then runs a Java program that pushes the
generated links into the
applicable topics.
Pull content into topics (topicpull)
The topicpull step pulls
content into <xref> and
<link> elements. This step is implemented
in XSLT.
If an
<xref> element does not contain link text, the target is examined and the link text
is
pulled. For example, a reference to a topic pulls the title of the topic; a reference to a list
item pulls the
number of the item. If the <xref>
element references a topic that has a short
description, and the <xref> element
does not already contain a child
<desc> element, a <desc> element is created that
contains the
text from the topic short description.
The process is similar for
<link> elements. If the <link>
element does
not have a child <linktext>
element, one is created with the appropriate link text.
Similarly, if the <link> element
does not have a child <desc>
element, and the short description of the target can be determined, a <desc> element is
created that contains the text from the topic short description.
Flagging in the toolkit
Beginning with DITA-OT 1.7, flagging support is implemented as a common preprocess module. The module evaluates the DITAVAL against all flagging attributes, and adds DITA-OT–specific hints to the topic when flags are active. Any extended transformation type may use these hints to support flagging without adding logic to interpret the DITAVAL.
Evaluating the DITAVAL flags
Flagging is implemented as a reusable module during the preprocess stage. If a DITAVAL file is not used with a build, this step is skipped with no change to the file.
When a flag is active, relevant sections of the DITAVAL itself are copied into the
topic as a sub-element of
the current topic. The active flags are enclosed in a pseudo-specialization of the
<foreign> element (referred to as a
pseudo-specialization because it is used only under
the covers, with all topic types; it is not integrated into any shipped document types).
<ditaval-startprop>-
When any flag is active on an element, a
<ditaval-startprop>element will be created as the first child of the flagged element:<ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop ">The<ditaval-startprop>element will contain the following:- If the active flags should create a new style, that style is
included using standard CSS markup on
the
@outputclassattribute. Output types that make use of CSS, such as XHTML, can use this value as-is. - If styles conflict, and a
<style-conflict>element exists in the DITAVAL, it will be copied as a child of<ditaval-startprop>. - Any
<prop>or<revprop>elements that define active flags will be copied in as children of the<ditaval-startprop>element. Any<startflag>children of the properties will be included, but<endflag>children will not.
- If the active flags should create a new style, that style is
included using standard CSS markup on
the
<ditaval-endprop>-
When any flag is active on an element, a
<ditaval-endprop>element will be created as the last child of the flagged element:<ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop ">CSS values and
<style-conflict>elements are not included on this element.Any
<prop>or<revprop>elements that define active flags will be copied in as children of<ditaval-prop>. Any<startflag>children of the properties will be included, but<endflag>children will not.
Supporting flags in overrides or custom transformation types
For most transformation types, the <foreign>
element should be ignored by default,
because arbitrary non-DITA content may not mix well unless coded for ahead of time. If the
<foreign> element is ignored by
default, or if a rule is added to specifically ignore
<ditaval-startprop> and <ditaval-endprop>, then the added
elements will have no impact on a transform. If desired, flagging support may be integrated
at any time in the
future.
The processing described above runs as part of the common preprocess, so any
transform that uses the default
preprocess will get the topic updates. To support generating flags as images, XSLT based
transforms can use
default fallthrough processing in most cases. For example, if a paragraph is flagged, the
first child of
<p> will contain the start flag
information; adding a rule to handle images in
<ditaval-startprop> will cause the
image to appear at the start of the paragraph
content.
In some cases fallthrough processing will not result in valid output; for those
cases, the flags must be
explicitly processed. This is done in the XHTML transform for elements like <ol>, because
fallthrough processing would place images in between <ol> and
<li>. To handle this, the code
processes <ditaval-startprop>
before starting the element, and <ditaval-endprop>
at the end. Fallthrough processing is
then disabled for those elements as children of
<ol>.
Example DITAVAL
Assume the following DITAVAL file is in use during a build. This DITAVAL will be used for each of the following content examples.
<?xml version="1.0" encoding="UTF-8"?>
<val>
<!-- Define what happens in the case of conflicting styles -->
<style-conflict background-conflict-color="red"/>
<!-- Define two flagging properties that give styles (no image) -->
<prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
<prop action="flag" att="platform" style="overline" val="win" backcolor="blue"/>
<!-- Define a property that includes start and end image flags -->
<prop action="flag" att="platform" val="linux" style="overline" backcolor="blue">
<startflag imageref="startlin.png"><alt-text>Start linux</alt-text></startflag>
<endflag imageref="endlin.png"><alt-text>End linux</alt-text></endflag>
</prop>
<!-- Define a revision that includes start and end image flags -->
<revprop action="flag" style="double-underline" val="rev2">
<startflag imageref="start_rev.gif"><alt-text>ssssssssssstart</alt-text></startflag>
<endflag imageref="end_rev.gif"><alt-text>eeeeeeeeeeeeeend</alt-text></endflag>
</revprop>
</val>Content example 1: Adding style
Now assume the following paragraph exists in a topic. Class attributes are
included, as they would normally be
in the middle of the preprocess routine; @xtrf and @xtrc are left off for
clarity.
<p audience="user">Simple user; includes style but no images</p>
Based on the DITAVAL above, audience="user" results in a style with underlining and
with a green background.
The interpreted CSS value is added to @outputclass on
<ditaval-startprop>, and the actual
property definition is included at the start and end
of the element. The output from the flagging step looks like this (with newlines added for
clarity, and class
attributes added as they would appear in the temporary file):
The resulting file after the flagging step looks like this; for clarity, newlines
are added, while
@xtrf and @xtrc are removed:
<p audience="user" class="- topic/p ">
<ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop "
outputclass="background-color:green;text-decoration:underline;">
<prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
</ditaval-startprop>
Simple user; includes style but no images
<ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop ">
<prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
</ditaval-endprop>
</p>Content example 2: Conflicting styles
This example includes a paragraph with conflicting styles. When the audience and
platform attributes are both
evaluated, the DITAVAL indicates that the background color is both green and blue. In this
situation, the
<style-conflict> element is
evaluated to determine how to style the content.
<p audience="user" platform="win">Conflicting styles
(still no images)</p>The <style-conflict>
element results in a background color of red, so this value is
added to @outputclass on <ditaval-startprop>. As above,
active properties
are copied into the generated elements; the <style-conflict>
element itself is also
copied into the generated <ditaval-startprop>
element.
The resulting file after the flagging step looks like this; for clarity, newlines
are added, while
@xtrf and @xtrc are removed:
<p audience="user" platform="win" class="- topic/p ">
<ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop "
outputclass="background-color:red;">
<style-conflict background-conflict-color="red"/>
<prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
<prop action="flag" att="platform" style="overline" val="win" backcolor="blue"/>
</ditaval-startprop>
Conflicting styles (still no images)
<ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop ">
<prop action="flag" att="platform" style="overline" val="win" backcolor="blue"/>
<prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
</ditaval-endprop>
</p>Content example 3: Adding image flags
This example includes image flags for both @platform
and @rev, which are
defined in DITAVAL <prop> and <revprop> elements.
<ol platform="linux" rev="rev2">
<li>Generate images for platform="linux" and rev="2"</li>
</ol>As above, the
<ditaval-startprop> and <ditaval-endprop>
nest the
active property definitions, with the calculated CSS value on @outputclass. The
<ditaval-startprop> drops the
ending image, and
<ditaval-endprop> drops the
starting image. To make document-order processing more
consistent, property flags are always included before revisions in <ditaval-startprop>,
and the order is reversed for <ditaval-endprop>.
The resulting file after the flagging step looks like this; for clarity, newlines
are added, while
@xtrf and @xtrc are removed:
<ol platform="linux" rev="rev2" class="- topic/ol ">
<ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop "
outputclass="background-color:blue;text-decoration:underline;text-decoration:overline;">
<prop action="flag" att="platform" val="linux" style="overline" backcolor="blue">
<startflag imageref="startlin.png"><alt-text>Start linux</alt-text></startflag>
</prop>
<revprop action="flag" style="double-underline" val="rev2">
<startflag imageref="start_rev.gif"><alt-text>ssssssssssstart</alt-text></startflag>
</revprop>
</ditaval-startprop>
<li class="- topic/li ">Generate images for platform="linux" and rev="2"</li>
<ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop ">
<revprop action="flag" style="double-underline" val="rev2">
<endflag imageref="end_rev.gif"><alt-text>eeeeeeeeeeeeeend</alt-text></endflag>
</revprop>
<prop action="flag" att="platform" val="linux" style="overline" backcolor="blue">
<endflag imageref="endlin.png"><alt-text>End linux</alt-text></endflag>
</prop>
</ditaval-endprop>
</ol>HTML-based processing modules
The DITA-OT ships with several varieties of HTML output, each of which follows roughly the same path through the processing pipeline. All HTML-based transformation begin with the same call to the pre-processing module, after which they generate HTML files and then branch to create the transformation-specific navigation files.
Common HTML-based processing
After the pre-processing operation runs, HTML-based builds each run a common series of Ant targets to generate HTML file. Navigation may be created before or after this set of common routines.
- If the args.css parameter is passed to
the build to add a CSS file, the
copy-csstarget copies the CSS file from its source location to the relative location in the output directory. - If a DITAVAL file is used, the
copy-revflagtarget copies the default start- and end-revision flags into the output directory. - The DITA topics are converted to HTML files. Unless the
@chunkattribute was specified, each DITA topic in the temporary directory now corresponds to one HTML file. Thedita.inner.topics.xhtmltarget is used to process documents that are in the map directory (or subdirectories of the map directory). Thedita.outer.topics.xhtmltarget is used to process documents that are outside of the scope of the map, and thus might end up outside of the designated output directory. Various DITA-OT parameters control how documents processed by thedita.outer.topics.xhtmltarget are handled.
XHTML processing
After the XHTML files are generated by the common routine, the dita.map.xhtml target is
called by the xhtml transformation. This target generates a TOC
file called
index.html, which can be loaded into a frameset.
HTML5 processing
After the HTML5 files are generated by the common routine, the dita.map.xhtml target is
called by the html5 transformation. This target generates a TOC
file called
index.html, which can be loaded into a frameset.
Eclipse help processing
The eclipsehelp
transformation generates XHTML-based output and files that are needed to
create an Eclipse Help system plug-in. Once the normal XHTML process has run, the dita.map.eclipse
target is used to create a set of control files and navigation files.
dita.map.eclipse.init- Sets up various default properties
dita.map.eclipse.toc- Creates the XML file that defines an Eclipse table of contents
dita.map.eclipse.index- Creates the sorted XML file that defines an Eclipse index
dita.map.eclipse.plugin- Creates the plugin.xml file that controls the behavior of an Eclipse plug-in
dita.map.eclipse.plugin.properties- Creates a Java properties file that sets properties for the plug-in, such as name and version information
dita.map.eclipse.manifest.file- Creates a MANIFEST.MF file that contains additional information used by Eclipse
copy-plugin-files- Checks for the presence of certain control files in the source directory, and copies those found to the output directory
dita.map.eclipse.fragment.language.init- Works in conjunction with the
dita.map.eclipse.fragment.language.country.initanddita.map.eclipse.fragment.errortargets to control Eclipse fragment files, which are used for versions of a plug-in created for a new language or locale
Several of the targets listed above have matching templates for processing content
that is located outside of
the scope of the map directory, such as dita.out.map.eclipse.toc.
TocJS processing
The tocjs transformation was originally created as a plug-in that distributed outside of the toolkit, but it now ships bundled in the default packages. This HTML5-based output type creates a JavaScript based frameset with TOC entries that expand and collapse.
tocjsInit- Sets up default properties. This target detects whether builds have already specified a name for JavaScript control file; if not, the default name toctree.js is used.
map2tocjs- Calls the
dita.map.tocjstarget, which generates the contents frame for TocJS output. tocjsDefaultOutput- Ensures that the HTML5 processing module is run. If scripts are missing required information, such as a name for the default frameset, this target copies default style and control files. This target was add to the DITA-OT in version 1.5.4; earlier versions of the TocJS transformation created only the JavaScript control file by default.
HTML Help processing
The htmlhelp transformation created HTML Help control files. If the build runs on a system that has the HTML Help compiler installed, the control files are compiled into a CHM file.
Once the pre-processing and XHTML processes are completed, most of the HTML Help processing is handled by the following targets:
dita.map.htmlhelp- Create the HHP, HHC, and HHK files. The HHK file is sorted based on the language of the map.
dita.htmlhelp.convertlang- Ensures that the content can be processed correctly by the compiler, and that the appropriate code pages and languages are used.
compile.HTML.Help- Attempts to detect the HTML Help compiler. If the compiler is found, the full project is compiled into a single CHM file.
JavaHelp processing
The javahelp transformation runs several additional Ant targets after the XHTML processing is completed in order to create control files for the JavaHelp output.
dita.map.javahelp- Creates all of the files that are needed to compile JavaHelp, including a table of contents, sorted index, and help map file.
compile.Java.Help- Searches for a JavaHelp compiler on the system. If a compiler is found, the help project is compiled.
PDF processing modules
The PDF (formerly known as PDF2) transformation process runs the pre-processing routine and follows it by a series of additional targets. These steps work together to create a merged set of content, convert the merged content to XSL-FO, and then format the XSL-FO file to PDF.
The PDF process includes many Ant targets. During a typical conversion from map to PDF, the following targets are most significant.
map2pdf2- Creates a merged file by calling a common Java merge module. It then calls the
publish.map.pdftarget to do the remainder of the work. publish.map.pdf- Performs some initialization and then calls the
transform.topic2pdftarget to do the remainder of processing. transform.topic2pdf- Converts the merged file to XSL-FO, generates the PDF, and deletes the topic.fo file, unless instructed to keep it.
The transform.topic2pdf target uses the following
targets to perform those tasks:
transform.topic2fo- Convert the merged file to an XSL-FO file. This process is composed of several
Ant targets.
Ant target Description transform.topic2fo.indexRuns a Java process to set up index processing, based on the document language. This step generates the file stage1.xml in the temporary processing directory. transform.topic2fo.flaggingSets up preprocessing for flagging based on a DITAVAL file. This step generates the file stage1a.xml in the temporary processing directory. transform.topic2fo.mainDoes the bulk of the conversion from DITA to XSL-FO. It runs the XSLT based process that creates stage2.fo in the temporary processing directory transform.topic2fo.i18nDoes additional localization processing on the FO file; it runs a Java process that converts stage2.fo into stage3.fo, followed by an XSLT process that converts stage3.fo into topic.fo. transform.fo2pdf- Converts the topic.fo file into PDF using the specified FO processor (Antenna House, XEP, or Apache FOP).
delete.fo2pdf.topic.fo- Deletes the topic.fo file, unless otherwise specified by setting an Ant property or command-line option.
Open Document Format processing modules
The odt transformation creates a binary file using the OASIS Open Document Format.
dita.odt.package.topic or dita.odt.package.map
target, depending on whether
the input to the transformation is a DITA topic or a DITA map. The following description focuses
on the map
process, which is made up of the following targets:
dita.map.odt- Converts the map into a merged XML file using the Java-based
topicmergemodule. Then an XSLT process converts the merged file into the content.xml file. dita.map.odt.stylesfile- Reads the input DITA map, and then uses XSLT to create a styles.xml file in the temporary directory.
dita.out.odt.manifest.file- Creates the manifest.xml file
Once these targets have run, the generated files are zipped up together with other required files to create the output ODT file.
Extending the DITA Open Toolkit
There are several methods that can be used to extend the toolkit; not all of them are recommended or supported. The best way to create most extensions is with a plug-in; extended documentation for creating plug-ins is provided in the next section.
- Creating a plug-in can be very simple to very complex, and is generally the best method for changing or extending the toolkit. Plug-ins can be used to accomplish almost any modification that is needed for toolkit processing, from minor style tweaks to extensive, complicated new output formats.
- The PDF process was initially developed independently of the toolkit, and created its own extension mechanism using customization directories. Many (but not quite all) of the capabilities available through PDF customization directories are now available through plug-ins.
- Using a single XSL file as an override by passing it in as a parameter. For example, when building XHTML content, the XSL parameter allows users to specify a single local XSL file (inside or outside of the toolkit) that is called in place of the default XHTML code. Typically, this code imports the default processing code, and overrides a couple of processing routines. This approach is best when the override is very minimal, or when the style varies from build to build. However, any extension made with this sort of override is also possible with a plug-in.
- Editing DITA-OT code directly may work in some cases, but is not advised. Modifying the code directly significantly increases the work and risk involved with future upgrades. It is also likely that such modifications will break plug-ins provided by others, limiting the function available to the toolkit.
Installing plug-ins
Use the dita command to install a plug-in.
-install plug-in-zipwhere:
Removing plug-ins
Use the dita command to uninstall a plug-in.
-uninstall plug-in-idwhere:
Rebuilding the DITA-OT documentation
The DITA-OT ships with Ant scripts that enable you to rebuild the toolkit documentation. This is especially helpful if your environment contains plug-ins that integrate additional messages into the toolkit.
Creating plug-ins
You can use DITA-OT plug-ins to extend the DITA Open Toolkit.
Overview of plug-ins
Plug-ins enable users to extend the functionality of the DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.
A plug-in consists of a directory, typically stored within the plugins/ directory inside of the DITA-OT. Every plug-in is controlled by a file named plugin.xml, which is located in the root directory of the plug-in.
Benefits of plug-ins
Plug-ins permit users to extend the toolkit in a way that is consistent, easy-to-share, and possible to preserve through toolkit upgrades.
The DITA-OT plug-in mechanism provides the following benefits:
- Plug-ins can easily be shared with other users, teams, or companies. Typically, all users need to do is to unzip and run a single integration step. With many builds, even that integration step is automatic.
- Plug-ins permit overrides or customizations to grow from simple to complex over time, with no increased complexity to the extension mechanism.
- Plug-ins can be moved from version to version of the DITA-OT simply by reinstalling or copying the directory from one installation to another. There is no need to re-integrate code based on updates to the core processing of the DITA-OT.
- Plug-ins can build upon each other. If you like a plug-in, simply install that plug-in, and then create your own plug-in that builds on top of it. The two plug-ins can then be distributed to your team as a unit, or you can share your own extensions with the original provider.
Plug-in descriptor file
The plug-in descriptor file (plugin.xml) controls all aspects of a plug-in, making each extension visible to the rest of the toolkit. The file uses pre-defined extension points to locate changes, and then integrates those changes into the core DITA-OT code.
The root element of the plugin.xml file is <plugin>. The
<plugin> element must specify an
@id attribute. The @id
attribute is used to identify the plug-in; it also is used to identify whether prerequisite
plug-ins are
available. The value of the @id attribute
must take the following form:
- One or more tokens, separated by periods
- A token can be composed of the following characters:
- Numerals (0-9)
- Lower-case letters (a-z)
- Upper-case letters (A-Z)
- Underscores (_)
- Hyphens (-)
The <plugin> element can
contain the following child elements:
<feature>-
An optional element that defines the extension to the DITA-OT.
The following attributes are supported:
Attribute Description Required? extension Name of the DITA-OT extension point Yes value Comma separated string value of the extension Either the @valueor@fileattribute must be specifiedfile File name, relative to the plugin.xml file Either the @valueor@fileattribute must be specifiedtype Type of the @valueattributeNo <extension-point>-
An optional element that defines a new extension point that can be used by other DITA-OT plug-ins.
The following attributes are supported:
Attribute Description Required? id Extension point identifier Yes name Extension point description No <require>-
An optional element that defines plug-in dependencies.
The following attributes are supported:
Attribute Description Required? plugin A vertical-bar separated list of plug-ins that are required Yes importance Identifies whether plug-in is required or optional No <template>-
An optional element that defines files that should be treated as templates.
The following attributes are supported:
Attribute Description Required? file Name and path to the template file, relative to the plugin.xml file Yes <meta>-
An optional element that defines metadata.
The following attributes are supported:
Attribute Description Required? type Metadata name Yes value Metadata value Yes <transtype>-
An optional element that defines a new output format (transformation type).
The following attributes are supported:
Attribute Description Required? name Transformation name Yes desc Transformation type description No abstract Defines an abstract transformation type that cannot be used directly No extends Specifies the name of the transformation type being extended No The
<transtype>element may define additional parameters for the transformation type using<param>child elements.The following parameter attributes are supported:
Attribute Description Required? name Parameter name Yes desc Parameter description No type Parameter type (enum, file, string) Yes Enumeration parameters (
<param>elements of type enum) define enumeration values with<val>child elements.The following attributes are supported:
Attribute Description Required? default Defines an enumeration value as the default value (default="true") Yes
Any extension that is not recognized by the DITA-OT is ignored. Since DITA-OT version 1.5.3, you can combine multiple extension definitions within a single plug-in.xml file; in older versions, only the last extension definition was used.
Plug-in dependencies
A DITA-OT plug-in can be dependent on other plug-ins. Prerequisite plug-ins are integrated first, which ensures that the DITA-OT handles XSLT overrides correctly.
The <require> element in
the plugin.xml file specifies whether the
plug-in has dependencies. Use
<require> elements to specify prerequisite plug-ins, in
order from most general to most specific.
If a prerequisite plug-in is missing, the DITA-OT prints a warning during
integration. To suppress the warning
but keep the integration order if both plug-ins are present, add importance="optional"
to the
<require> element.
If a plug-in can depend on any one of several optional plug-ins, separate the
plug-in IDs with a vertical bar.
This is most useful when combined with importance="optional".
Example: Plug-in with a prerequisite plug-in
The following plug-in will only be installed if the plug-in with the ID com.example.primary is
available. If that plug-in is not available, a warning is generated and the integration
operation fails.
<plugin id="com.example.builds-on-primary">
<!-- ... Extensions here -->
<require plugin="com.example.primary"/>
</plugin>Example: Plug-in that has optional plug-ins
The following plug-in will only be installed if either the plug-in with the ID
pluginA or the
plug-in with the ID pluginB is available. If neither of those
plug-ins are installed, a warning
is generated but the integration operation is completed.
<plugin id="pluginC">
<!-- ...extensions here -->
<require plugin="pluginA|pluginB" importance="optional"/>
</plugin>Extending an XML catalog file
You can update either the main DITA-OT XML catalog or the XML catalog that is used by the PDF plug-in. This enables the DITA-OT to support new specializations and document-type shells.
You can use the dita.specialization.catalog.relative and
org.dita.pdf2.catalog.relative extension points to update the
DITA-OT catalog files.
dita.specialization.catalog
extension is deprecated. Use
dita.specialization.catalog.relative instead.
Example
This example assumes that catalog-dita.xml contains an OASIS catalog for any document-type shells inside this plug-in. The catalog entries in catalog-dita.xml are relative to the catalog itself; when the plug-in is integrated, they are added to the core DITA-OT catalog (with the correct path).
<plugin id="com.example.catalog">
<feature extension="dita.specialization.catalog.relative" file="catalog-dita.xml"/>
</plugin>Adding a new target to the Ant build process
Use the Ant conductor extension point (dita.conductor.target.relative) to make new targets
available to the Ant processing pipeline. This can be done as part of creating a new transformation,
extending
pre-processing, or simply to make new Ant targets available to other plug-ins.
The imports from wrapper file are copied into the build.xml file, using the correct path. This makes the new Ant targets available to other processes.
Adding an Ant target to the pre-processing pipeline
You can add an Ant target to the pre-processing pipeline. This enables you to insert additional processing before or after the pre-processing chain or a specific step in the pre-processing operation.
You can use the depend.preprocess.pre and depend.preprocess.post extension
points to run a target before or after the entire pre-processing operation. In addition, there
are extension
points that enable you ro run an Ant target before specific pre-processing steps.
Example
The following plugin.xml file specifies that the
myAntTargetBeforeChunk target is always run before the
chunk step in the
pre-processing stage.
<plugin id="com.example.extendchunk">
<feature extension="depend.preprocess.chunk.pre" value="myAntTargetBeforeChunk"/>
</plugin>It assumes that the myAntTargetBeforeChunk target has already been defined and integrated.
Adding a new transformation type
Plug-ins can integrate an entirely new transformation type. The new transformation type can be very simple, such as an XHTML build that creates an additional control file; it also can be very complex, adding any number of new processing steps.
You can use the dita.conductor.transtype.check and dita.transtype.print
extension points to define new transformation types.
When a transformation type is defined, the build expects Ant code to be integrated to define the transformation process. The Ant code must define a target based on the name of the transformation type; if the transformation type is "new-transform", the Ant code must define a target named dita2new-transform.
Examples
The following plugin.xml file defines a new transformation type named "newtext"; it also defines the transformation type to be a print type. The build will look for a dita2newtext target.
<plugin id="com.example.newtext">
<feature extension="dita.conductor.transtype.check" value="newtext"/>
<feature extension="dita.transtype.print" value="newtext"/>
<feature extension="dita.conductor.target.relative" file="build-newtext.xml"/>
</plugin>The following example shows how the org.dita.html5
plugin uses the
<transtype> element to extend the
common HTML transformation with a new
html5 transformation type and define a new nav-toc parameter with three
possible values:
<transtype name="html5" extends="common-html"
desc="HTML5">
<param name="nav-toc" type="enum"
desc="Specifies whether to generate a navigation TOC in topic pages.">
<val default="true" desc="No TOC">none</val>
<val desc="Partial TOC that shows the current topic">partial</val>
<val desc="Full TOC">full</val>
</param>
</transtype>Overriding an XSLT-processing step
You can override specific XSLT-processing steps in both the pre-processing pipeline and certain DITA-OT transformations.
Example: Overriding XHTML header processing
The following two files represent a complete, simple style plug-in.
The plugin.xml file declares an XSLT file that extends XHTML processing:
<?xml version="1.0" encoding="UTF-8"?>
<plugin id="com.example.brandheader">
<feature extension="dita.xsl.xhtml" file="xsl/header.xsl"/>
</plugin>The xsl/header.xsl XSLT file referenced in plugin.xml overrides the default header processing to add a banner:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template name="gen-user-header">
<div><img src="http://www.example.com/company_banner.jpg"
alt="Example Company Banner"/></div>
</xsl:template>
</xsl:stylesheet>Modifying or adding generated text
Generated text is the term for strings that are automatically added by the build, such as "Note" before the contents of a <note> element.
- It can be used to add new text for your own processing extensions; for example, it could be used to add localized versions of the string "User response" to aid in rendering troubleshooting information.
- It can be used to override the default strings in the toolkit; for example, it could be used to reset the English string "Figure" to "Fig".
- It can be used to add support for new languages (for non-PDF transforms only; PDF requires more complicated localization support). For example, it could be used to add support for Vietnamese or Gaelic; it could also be used to support a new variant of a previously supported language, such as Australian English.
dita.xsl.strings- Add new strings to generated text file.
Example: adding new strings
First copy the file xsl/common/strings.xml to your plug-in, and edit it to contain the languages that you are providing translations for ("en-US" must be present). For this sample, copy the file into your plug-in as xsl/my-new-strings.xml. The new strings file will look something like this:
<?xml version="1.0" encoding="utf-8"?>
<!-- Provide strings for my plug-in; this plug-in supports
English, Icelandic, and Russian. -->
<langlist>
<lang xml:lang="en" filename="mystring-en-us.xml"/>
<lang xml:lang="en-US" filename="mystring-en-us.xml"/>
<lang xml:lang="is" filename="mystring-is-is.xml"/>
<lang xml:lang="is-IS" filename="mystring-is-is.xml"/>
<lang xml:lang="ru" filename="mystring-ru-ru.xml"/>
<lang xml:lang="ru-RU" filename="mystring-ru-ru.xml"/>
</langlist>Next, copy the file xsl/common/strings-en-us.xml to your plug-in, and replace the content with your own strings (be sure to give them unique name attributes). Do the same for each language that you are providing a translation for. For example, the file mystring-en-us.xml might contain:
<?xml version="1.0" encoding="utf-8"?>
<strings xml:lang="en-US">
<str name="String1">English generated text</str>
<str name="Another String">Another String in English</str>
</strings>Use the following extension code to include your strings in the set of generated text:
<plugin id="com.example.strings">
<feature extension="dita.xsl.strings" file="xsl/my-new-strings.xml"/>
</plugin>The string is now available to the "getString" template used in many DITA-OT XSLT files. For example, if processing in a context where the xml:lang value is "en-US", the following call would return "Another String in English":
<xsl:call-template name="getString">
<xsl:with-param name="stringName" select="'Another String'"/>
</xsl:call-template>
Example: modifying existing strings
The process for modifying existing generated text is exactly the same as for adding new text, except that the strings you provide override values that already exist. To begin, set up the xsl/my-new-strings.xml file in your plug-in as in the previous example.
Next, copy the file xsl/common/strings-en-us.xml to your plug-in, and choose the strings you wish to change (be sure to leave the name attribute unchanged, because this is the key used to look up the string). Create a strings file for each language that needs to modify existing strings. For example, the new file mystring-en-us.xml might contain:
<?xml version="1.0" encoding="utf-8"?>
<strings xml:lang="en-US">
<str name="Figure">Fig</str>
<str name="Draft comment">ADDRESS THIS DRAFT COMMENT</str>
</strings>To integrate the new strings, use the same method as above to add these strings to your plugin.xml file. Once this plug-in is integrated, where XHTML output previously generated the term "Figure", it will now generate "Fig"; where it previously generated "Draft comment", it will now generate "ADDRESS THIS DRAFT COMMENT". The same strings in other languages will not be modified unless you also provide new versions for those languages.
Example: adding a new language
<?xml version="1.0" encoding="utf-8"?>
<!-- Map languages with xml:lang="vi" or xml:lang="vi-vn"
to the translations in this plug-in. -->
<langlist>
<lang xml:lang="vi" filename="strings-vi.xml"/>
<lang xml:lang="vi-VN" filename="strings-vi.xml"/>
</langlist>Next, copy the file xsl/common/strings-en-us.xml to
your plug-in, and rename it to match
the language you wish to add. For example, to support Vietnamese strings you may want to pick a
name like
strings-vi.xml. In that file, change the xml:lang attribute on the root
element to match your new language.
Once the file is ready, translate the contents of each
<str> element (be sure to leave the name attribute
unchanged). Repeat this process for
each new language you wish to add.
To integrate the new languages, use the same method as above to add
these strings to your plugin.xml file. Once this plug-in is
integrated, non-PDF builds will
include support for Vietnamese; instead of generating the English word "Caution", the element
<note
type="caution" xml:lang="vi"> may generate something like "chú
ý".
Adding parameters to existing XSLT steps
You can pass parameters from the Ant build to existing XSLT
steps in both the pre-processing pipeline and
certain DITA-OT transformations. This can be useful if you want to make the parameters available as
global
<xsl:param> values within XSLT overrides.
Example
The following plug-in passes the parameters defined in the insertParameters.xml file as input to the XHTML process. Generally, an additional XSLT override will make use of the parameters to do something new with the generated content.
<plugin id="com.example.newparam">
<feature extension="dita.conductor.xhtml.param" file="insertParameters.xml"/>
</plugin>Adding a Java library to the DITA-OT classpath parameter
You can use the dita.conductor.lib.import
extension point to add an additional Java
library to the DITA-OT classpath parameter.
In the following extended example, the myJavaLibrary.jar file performs a validation step
during processing, and you want it to run immediately before the conref step. To accomplish
this, you will need to use several features:
- The JAR file must be added to the classpath.
- The Ant target must be added to the dependency chain for conref.
- An Ant target must be created that uses this class, and the Ant wrapper integrated into the code.
The files might look like the following:
<?xml version="1.0" encoding="UTF-8"?>
<plugin id="com.example.samplejava">
<!-- Add the JAR file to the DITA-OT CLASSPATH -->
<feature extension="dita.conductor.lib.import"
file="com.example.sampleValidation.jar"/>
<!-- Integrate the Ant code -->
<feature extension="dita.conductor.target.relative" file="antWrapper.xml"/>
<!-- Define the Ant target that is called, and the location (before conref) -->
<feature extension="depend.preprocess.conref.pre" value="validateWithJava"/>
</plugin><?xml version="1.0" encoding="UTF-8"?>
<dummy>
<import file="calljava-antcode.xml"/>
</dummy><?xml version="1.0" encoding="UTF-8"?>
<project default="validateWithJava">
<target name="validateWithJava">
<java classname="com.example.sampleValidation">
<!-- The class was added to dost.class.path (the DITA-OT classpath) -->
<classpath refid="dost.class.path"/>
</java>
</target>
</project>Adding new diagnostic messages
Use the dita.xsl.messages
extension point to add plug-in-specific messages to the
diagnostic messages that are generated by the DITA-OT. These messages then can be used by any XSLT
override.
You now can use the following call in XSLT modules to generate a message when a specific condition occurs:
<xsl:call-template name="output-message">
<xsl:with-param name="msgnum">numberletter</xsl:with-param>
<xsl:with-param name="msgsev">letter</xsl:with-param>
</xsl:call-template>
Creating a new plug-in extension point
If your plug-in needs to define its own extension point in an
XML file, add the string
"_template" to the filename before the file suffix. During integration,
this file will be
processed like the built-in DITA-OT templates.
Template files are used to integrate most DITA-OT extensions. For example, the file dita2xhtml_template.xsl contains all of the default rules for converting DITA topics to XHTML, along with an integration point for plug-in extensions. When the integrator runs, the file dita2xhtml.xsl is recreated, and the integration point is replaced with references to all appropriate plug-ins.
To mark a
new file as a template file, use the <template> element.
The template extension namespace has the URI http://dita-ot.sourceforge.net.
It is used to
identify elements and attributes that have a special meaning in template processing. This
documentation uses a
prefix of dita: for referring to elements in the template
extension namespace. However,
template files are free to use any prefix, provided that there is a namespace declaration that
binds the prefix
to the URI of the template extension namespace.
dita:extension
element
The dita:extension elements are used to insert generated
content during integration process.
There are two required attributes:
- The
idattribute defines the extension point ID which provides the argument data. - The
behaviorattribute defines which processing action is used.
Supported values for behavior attribute:
org.dita.dost.platform.CheckTranstypeAction- Create Ant condition elements to check if the
${transtype}property value equals a supported transformation type value. org.dita.dost.platform.ImportAntLibAction- Create Ant
pathelementelements for library imported extension point. Theidattribute is used to define the extension point ID. org.dita.dost.platform.ImportPluginCatalogAction- Include plug-in metadata catalog content.
org.dita.dost.platform.ImportPluginInfoAction- Create plug-in metadata Ant properties.
org.dita.dost.platform.ImportStringsAction- Include plug-in string file content base on generated
text extension point. The
idattribute is used to define the extension point ID. org.dita.dost.platform.ImportXSLAction- Create
xsl:importelements based on XSLT import extension point. Theidattribute is used to define the extension point ID. org.dita.dost.platform.InsertAction- Include plug-in conductor content based on Ant
import
extension point. The
idattribute is used to define the extension point ID. org.dita.dost.platform.InsertAntActionRelative- Include plug-in conductor content based on relative
Ant
import extension point. The
idattribute is used to define the extension point ID. org.dita.dost.platform.InsertCatalogActionRelative- Include plug-in catalog content based on catalog
import
extension point. The
idattribute is used to define the extension point ID. org.dita.dost.platform.ListTranstypeAction- Create a pipe delimited list of supported transformation types.
dita:extension attribute
The dita:extension attribute is used to process
attributes in elements which are not in
template extension namespace. The value of the attribute is a space delimited tuple, where the
first item is the
name of the attribute to process and the second item is the action ID.
Supported values:
depends org.dita.dost.platform.InsertDependsAction- Ant target dependency list is processed to replace all target names which start with an open curly bracket and end with a close curly bracket. The value of the extension point is the ID between the curly brackets.
Example
The following plug-in defines myBuildFile_template.xml as a new template for extensions, and two new extension points.
<plugin id="com.example.new-extensions">
<extension-point id="com.example.new-extensions.pre"
name="Custom target preprocess"/>
<extension-point id="com.example.new-extensions.content"
name="Custom target content"/>
<template file="myBuildFile_template.xml"/>
</plugin>When the integrator runs, this will be used to recreate myBuildFile.xml, replacing Ant file content based on extension point use.
<project xmlns:dita="http://dita-ot.sourceforge.net">
<target name="dita2custom"
depends="dita2custom.init,
{com.example.new-extensions.pre},
dita2xhtml"
dita:extension="depends org.dita.dost.platform.InsertDependsAction">
<dita:extension id="com.example.new-extensions.content"
behavior="org.dita.dost.platform.InsertAction"/>
<target>
</project>Example plugin.xml file
The following is a sample of a plugin.xml file. This file adds support for a new set of specialized DTDs, and includes an override for the XHTML output processor.
This plugin.xml file would go into a directory such as DITA-OT/plugins/music/ and referenced supporting files would also exist in that directory. A more extensive sample using these values is available in the actual music plug-in, available at the DITA-OT download page at SourceForge.
<plugin id="org.metadita.specialization.music">
<feature extension="dita.specialization.catalog.relative" file="catalog-dita.xml">
<feature extension="dita.xsl.xhtml" file="xsl/music2xhtml.xsl"/>
</plugin>Extension points
The DITA Open Toolkit provides a series of extension points that can be used to integrate changes into the core code. Extension points are defined in the plugin.xml file for each plug-in. The DITA-OT integration process makes each extension visible to the rest of the toolkit.
General extension points
These extension points enable you to extend the DITA-OT. You can add Ant targets or imports; add a Java library to the classpath parameter; add a new transformation type; extend a catalog file; add new diagnostic messages, and more.
- dita.conductor.lib.import
- Adds a Java library to the DITA-OT classpath.
- dita.conductor.target
- Adds an Ant import to the main Ant build file. This extension point is
deprecated; use
dita.conductor.target.relativeinstead. - dita.conductor.target.relative
- Adds an Ant import to the main Ant build file.
- dita.conductor.transtype.check
- Adds a new value to the list of valid transformation types.
- dita.specialization.catalog
- Adds the content of a catalog file to the main DITA-OT catalog file. This
extension
point is deprecated; use
dita.specialization.catalog.relativeinstead. - dita.specialization.catalog.relative
- Adds the content of a catalog file to the main DITA-OT catalog file.
- dita.transtype.print
- Defines a transformation as a print type.
- dita.xsl.messages
- Adds new diagnostic messages to the DITA-OT.
- org.dita.pdf2.catalog.relative
- Adds the content of a catalog file to the main catalog file for the PDF plug-in.
Pre-processing extension points
You can use these extension points to run an Ant target before or after the pre-processing operation; you also run an Ant target before or after a specific step in the pre-processing operation.
- depend.preprocess.chunk.pre
- Runs an Ant target before the
chunkstep in the pre-processing stage. - depend.preprocess.coderef.pre
- Runs an Ant target before the
coderefstep in the pre-processing stage. - depend.preprocess.conref.pre
- Runs an Ant target before the
conrefstep in the pre-processing stage. - depend.preprocess.conrefpush.pre
- Runs an Ant target before the
conrefpushstep in the pre-processing stage. - depend.preprocess.clean-temp.pre
- Runs an Ant target before the
Xstep in the pre-processing stage. - depend.preprocess.copy-files.pre
- Runs an Ant target before the
Xstep in the pre-processing stage. - depend.preprocess.copy-flag.pre
- Runs an Ant target before the
Xstep in the pre-processing stage. - depend.preprocess.copy-generated-files.pre
- Runs an Ant target before the
Xstep in the pre-processing stage. - depend.preprocess.copy-html.pre
- Runs an Ant target before the
Xstep in the pre-processing stage. - depend.preprocess.copy-image.pre
- Runs an Ant target before the
Xstep in the pre-processing stage. - depend.preprocess.copy-subsidiary.pre
- Runs an Ant target before the
Xstep in the pre-processing stage. - depend.preprocess.debug-filter.pre
- Runs an Ant target before the
debug-filterstep in the pre-processing stage. - depend.preprocess.gen-list.pre
- Runs an Ant target before the
gen-liststep in the pre-processing stage. - depend.preprocess.keyref.pre
- Runs an Ant target before the
keyrefstep in the pre-processing stage. - depend.preprocess.maplink.pre
- Runs an Ant target before the
maplinkstep in the pre-processing stage. - depend.preprocess.mappull.pre
- Runs an Ant target before the
mappullstep in the pre-processing stage. - depend.preprocess.mapref.pre
- Runs an Ant target before the
maprefstep in the pre-processing stage. - depend.preprocess.move-links.pre
- Runs an Ant target before the
move-linksstep in the pre-processing stage. - depend.preprocess.move-meta-entries.pre
- Runs an Ant target before the
move-meta-entriesstep in the pre-processing stage. - depend.preprocess.pre
- Runs an Ant target before the pre-processing stage.
- depend.preprocess.post
- Runs an Ant target after the pre-processing stage.
- depend.preprocess.topicpull.pre
- Runs an Ant target before the
topicpullstep in the pre-processing stage.
XSLT-import extension points
You can use these extension points to override XSLT
processing steps in pre-processing and certain
transformation types. The value of the <file>
attribute in the
<feature> element specifies a relative path to
an XSL file in the current plug-in. The
plug-in installer adds a XSL import statement to the default DITA-OT code, so that the XSL override
becomes part of
the normal build.
Pre-processing
You can use the following extension points to add XSLT processing to modules in the pre-processing pipeline:
- dita.xsl.conref
- Overrides the pre-processing step that resolves conref.
- dita.xsl.maplink
- Overrides the
maplinkstep in the pre-processing pipeline. This is the step that generates map-based links. - dita.xsl.mappull
- Overrides the
mappullstep in the pre-processing pipeline. This is the step that updates navigation titles in maps and causes attributes to cascade. - dita.xsl.mapref
- Overrides the
maprefstep in the pre-processing pipeline. This is the step that resolves references to other maps. - dita.xsl.topicpull
- Overrides the
topicpullstep in the pre-processing pipeline. This is the step that pulls text into<xref>elements, as well as performing other tasks.
Transformations
You can use the following extension points to add XSLT processing to modules in DITA-OT transformations:
- dita.xsl.docbook
- Overrides the default DocBook transformation.
- dita.xsl.eclipse.plugin
- Overrides the step that generates the plugin.xml file for Eclipse Help.
- dita.xsl.rtf
- Overrides the default rich-text format (RTF) transformation.
- dita.xsl.troff-ast
- Overrides the intermediate block-and-phrase format that is generated as input to troff processing.
- dita.xsl.troff
- Overrides the XSL that converts block-and-phrase intermediate markup into troff.
- dita.xsl.xhtml
- Overrides the default HTML or XHTML transformation, including HTML Help and Eclipse Help. The referenced file is integrated directly into the XSLT step that generates XHTML.
- dita.xsl.xslfo
- Overrides the default PDF transformation (formerly known as PDF2). The referenced XSL file is integrated directly into the XSLT step that generates the XSL-FO.
Example
The following two files represent a complete (albeit simple) plug-in that adds a company banner to the XHTML output. The plugin.xml file declares an XSLT file that extends the XHTML processing; the xsl/header.xsl file overrides the default header processing to provide a company banner.
<?xml version="1.0" encoding="UTF-8"?>
<plugin id="com.example.brandheader">
<feature extension="dita.xsl.xhtml" file="xsl/header.xsl"/>
</plugin><?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template name="gen-user-header">
<div><img src="http://www.example.com/company_banner.jpg"
alt="Example Company Banner"/></div>
</xsl:template>
</xsl:stylesheet>
</xml>XSLT-parameter extension points
You can use theses extension points to pass parameters into
existing XSLT steps in both the pre-processing
pipeline and DITA-OT transformation. The parameters generally will be available as global
<xsl:param> values with XSLT overrides.
Pre-processing
You can use the following extension points to pass parameters to modules in the pre-processing pipeline:
- dita.preprocess.conref.param
- Pass parameters to the
conrefmodule in the pre-processing pipeline - dita.preprocess.maplink.param
- Pass parameters to the
maplinkmodule in the pre-processing pipeline - dita.preprocess.mappull.param
- Pass parameters to the
mappullmodule in the pre-processing pipeline - dita.preprocess.mapref.param
- Pass parameters to the
maprefmodule in the pre-processing pipeline - dita.preprocess.topicpull.param
- Pass parameters to the
topicpullmodule in the pre-processing pipeline
Transformations
You can use the following extension points to pass parameters to modules in DITA-OT transformations:
- dita.conductor.eclipse.toc.param
- Pass parameters to the XSLT step that generates the Eclipse Help table of contents (TOC).
- dita.conductor.html.param
- Pass parameters to the HTML and HTML Help transformations.
- dita.conductor.pdf2.param
- Pass parameters to the PDF (formerly PDF2) transformation.
- dita.conductor.xhtml.param
- Pass parameters to the XHTML and Eclipse Help transformations.
- dita.conductor.xhtml.toc.param
- Pass parameters to to the XSLT step that generates the XHTML table of contents (TOC).
Example
The following two files represent a complete (albeit simple) plug-in that passes the parameters defined in the insertParameters.xml file to the XHTML transformation process.
<plugin id="com.example.newparam">
<feature extension="dita.conductor.xhtml.param" file="insertParameters.xml"/>
</plugin><dummy>
<!-- Any Ant code allowed in xslt task is possible. Common example: -->
<param name="paramNameinXSLT" expression="${antProperty}" if="antProperty"/>
</dummy>Version and support information
You can use these extension points to define version and support information for a plug-in. Currently, the DITA-OT does not do anything with this information, but it might do so in the future.
- package.support.name
- Specifies the person who provides support for the DITA-OT plug-in
- package.support.email
- Specifies the e-mail address for the person who provides support for the DITA-OT plug-in
- package.version
-
Specifies the version of the DITA-OT plug-in. The value uses the following syntax:
major.minor.micro.qualifierwhere:
- major is a number and is required.
- minor is a number and is optional.
- micro is a number and is optional.
- qualifier is optional and can be composed of numerals, uppercase or lower case letters, underscores, and hyphens.
By default, the package.version value is set to
0.0.0.
Example
<plugin id="com.example.WithSupportInfo">
<feature extension="package.support.name" value="Joe the Author"/>
<feature extension="package.support.email" value="joe@example.com"/>
<feature extension="package.version" value="1.2.3"/>
</plugin>Customizing PDF output
You can build a DITA-OT plug-in that contains a customized PDF transformation.
- Uses A4 paper
- Renders figures with a title at the top and a description at the bottom
- Use em dashes as the symbols for unordered lists
The new plug-in directory has the following layout and files:
com.example.print-pdf/
cfg/
common/
vars/
en.xml
fo/
attrs/
custom.xsl
xsl/
custom.xsl
catalog.xml
integrator.xml
plugin.xmlRun the integration process to install the plug-in and make the print-pdf transformation available.
Migrating customizations
If you have XSL transformation overrides, plugins or other customizations written prior to DITA-OT 2.2, you may need to make changes to ensure your overrides work properly with the latest toolkit versions.
In some cases, you may be able to remove old code that is no longer needed. In other cases, you may need to refactor your code to point to the modified extension points, templates or modes in recent toolkit versions.
Migrating to release 2.2
In DITA-OT 2.2, the HTML5 transformation was refactored as its own plugin and separate plugins were created for each of the rendering engine-specific PDF transformations.
HTML5
The HTML5 transformation introduced in release 2.0 as part of the XHTML plugin has been moved to a separate HTML5 plugin. Customizations that extended the previous HTML5 output under the XHTML plugin will probably need to be refactored on the new HTML5 plugin.
Processing specific to Apache FOP, Antenna House Formatter, and RenderX XEP has been separated into separate plugins for each of those rendering engines. Customizations that extended this processing might need to extend the new org.dita.pdf2.fop, org.dita.pdf2.axf, or org.dita.pdf2.xep plugins.
PDF customizations that are not specific to a rendering engine can continue to extend the org.dita.pdf2 plugin as before.
Migrating to release 2.1
In DITA-OT 2.1, the insertVariable template was deprecated for PDF
transformations.
The following template has been deprecated:
insertVariable
Calls to that template will result in warnings in the build log. To update your plugin, make the following changes:
<xsl:call-template name="insertVariablegetVariable">
<xsl:with-param name="theVariableIDid"
select="var-id"/>
<xsl:with-param name="theParametersparams">
params
</xsl:with-param>
</xsl:call-template>Migrating to release 2.0
In DITA-OT 2.0, XSLT templates were converted to XSLT 2.0, variable typing was implemented, and some older templates were refactored or removed. In addition, the dita command simplifies distribution of plugins by allowing installation from a URL.
All Transformations — Variable Typing
XSLT stylesheets were converted to XSLT 2.0. With that change, variable types were also implemented. Plugins that change template variable values will need to make the following changes:
- Declare the same types defined in the default templates with
@as. - Ensure that the generated values conform to the declared type.
For example:
<xsl:variable name="urltest">
<xsl:variable name="urltest" as="xs:boolean">All Transformations — Refactoring
Much of the toolkit code was refactored for release 2.0. Customization changes that were based on a specific template in a previous version of the toolkit might not work because the modified template is no longer used. If this is the case, the changes will need to be reimplemented based on the new XSLT templates.
HTML5
A new HTML5 transformation type has been added. Customizations that previously modified the XHTML output to generate valid HTML5 should still work, but basing your customization on the new transformation type might simplify the customization and reduce the work required to maintain compatibility with future versions of the toolkit.
Plugin Installation and Distribution
Plugins can now be installed or uninstalled from a ZIP archive using the new dita command. Plugins can also be installed from a referenced URL. See Arguments and options for the dita command.
Migrating to release 1.8
In DITA-OT 1.8, certain stylesheets were moved to plug-in specific folders and various deprecated Ant properties, XSLT stylesheets, parameters and modes were removed from the XHTML, PDF and ODT transformations.
Stylesheets for the following transformation types have moved to plug-in specific folders:
- eclipsehelp
- htmlhelp
- javahelp
- odt
- xhtml
Preprocessing
The following deprecated Ant properties have been removed:
dita.script.dir, use${dita.plugin.id.dir}insteaddita.resource.dir, use${dita.plugin.org.dita.base.dir}/resourceinsteaddita.emptyargs.message.file
XHTML
XSLT Java extension ImgUtils has been removed from
stylesheets and been replaced with
preprocessing module ImageMetadataModule. The old ImgUtils Java classes are
still included in the build.
The following deprecated XSLT stylesheets have been removed:
- artwork-preprocessor.xsl
- otdita2fo_frontend.xsl
The following deprecated XSLT templates have been removed:
insertVariable.old
The following deprecated XSLT modes have been removed:
layout-masters-processingtoc-prefix-text, usetocPrefixmode insteadtoc-topic-text, usetocTextmode instead
Link generation has been simplified by removing deprecated arguments in favor of
args.rellinks. The following deprecated Ant properties have been
removed:
args.fo.include.rellinks
The following XSLT parameters have been removed:
antArgsIncludeRelatedLinksdisableRelatedLinks
A call to a named template pullPrologIndexTerms.end-range has been added to
processTopic* templates to handle topic wide index ranges.
Legacy PDF
The following deprecated XSLT stylesheets have been removed:
- dita2fo-shell_template.xsl
- topic2fo-shell.xsl
ODT
Link generation has been simplified by removing deprecated arguments in favor of
args.rellinks. The following deprecated Ant properties have been
removed:
args.odt.include.rellinks
The following XSLT parameters have been added:
include.rellinks
The following XSLT parameters have been removed:
disableRelatedLinks
Migrating to release 1.7
In DITA-OT 1.7, a new preprocessing step implements flagging
for HTML-based output formats. PDF processing
was corrected with regard to shortdesc handling, and a new XSLT template
mode was introduced for
HTML TOC processing. Several stylesheets were moved to plug-in specific folders and deprecated
properties and XSLT
variables were removed.
A new job status file .job.xml has been introduced and replaces dita.list and dita.xml.properties as the normative source for job status. If you have custom processing which modifies the job properties, you should change your code to modify .job.xml instead.
Support for the following deprecated properties has been removed:
dita.inputdita.input.dirnamedita.extname
Stylesheets for the following transformation types have moved to plug-in specific folders:
- docbook
- eclipsecontent
- troff
- wordrtf
If custom plug-ins have hard coded paths to these stylesheets, update references to use
either
plugin URIs in xsl:import
instructions or use dita.plugin.*
Ant properties.
The integration process has been changed to use strict mode by default. For old plug-ins which are not valid, lax processing mode can still be used.
Plug-ins that use the MessageUtils Java class must use
getInstance method to
access the MessageUtils instance, as getMessage
methods have been changed to
instance methods.
Preprocessing
The preprocessing Ant dependency chain has been cleaned up. Tasks no longer depend on
the previous task in the
default chain, but rather the whole preprocess dependency chain is defined by the preprocess
task.
HTML
Core TOC generation has been moved to a separate XSLT stylesheet
xsl/map2htmtoc/map2htmlImpl.xsl and the new templates use the
mode toc.
Plug-ins which override HTML TOC processing should change the map processing templates to toc
mode.
HTML and extended transformation types
Flagging logic has been pulled out of the core X/HTML code and moved to a preprocess step. This significantly simplifies and optimizes the X/HTML code, while making flagging logic available to any other transformation type. The new preprocess step implements all flagging logic; for each active flag, it adds a DITA-OT specific hint into the intermediate topics (implemented as a specialization of the DITA <foreign> element). As part of this change, all flagging-related templates in the XHTML code (such as start-flagit and gen-style) are deprecated.
If you override the X/HTML transforms, you may need to update your overrides to use the new flagging logic. In most cases this just means deleting calls to the deprecated templates; in some cases, the calls can be replaced with 2 lines to process flags in new places. You should compare your override to the updated XHTML code and update as needed. See XHTML migration for flagging updates in DITA-OT 1.7 for details.
Plug-ins that provide support for new transforms need to ensure that they properly support the DITA <foreign> element, which should be ignored by default; if so, this change will have no immediate impact. Support for flagging new transformation types may be more easily added based on this update, because there is no need to re-implement flagging logic, but this is not required. See Flagging in the toolkit for details on how to add flagging support.
The following deprecated XSLT variables have been removed:
page-margin-leftpage-margin-right
XSLT stylesheets have been split to separate specialization topic code and new xsl:import
instructions have been added to topic2fo.xsl. Plug-ins which
define their own shell
stylesheet should be revised to import all the required stylesheet modules.
PDF processing used to replace topic shortdesc with map
shortdesc, but this
behavior was incorrect and was removed to comply with the DITA specification.
A new #note-separator variable string was added to
facilitate customization.
XHTML migration for flagging updates in DITA-OT 1.7
This topic is primarily of interest to developers with XHTML transform overrides written prior to DITA-OT 1.7. Due to significant changes in the flagging process with the 1.7 release, some changes may be needed to make overrides work properly with DITAVAL based flagging. The new design is significantly simpler than the old design; in many cases, migration will consist of deleting old code that is no longer needed.
Which XHTML overrides need to migrate?
If your override does not contain any code related to DITAVAL flagging, then there is nothing to migrate.
If your builds do not make use of DITAVAL based flagging, but calls the deprecated flagging templates, then you should override but there is little urgency. You will not see any difference in the output, but those templates will be removed in a future release.
- In some cases flags may be doubled. This will be the case if you call
routines such as
"start-flagit". - In some cases flags may be removed. This will be the case if you call
shortcut routines such as
"revtext"or"revblock". - In other cases, flags may still appear properly, in which case migration is less urgent
For any migration that needs migration, please see the instructions that follow.
Deprecated templates in DITA-OT 1.7
All of the old DITAVAL based templates are deprecated in DITA-OT 1.7. If your overrides include any of the following templates, they should be migrated for the new release; in many cases the templates below will not have any effect on your output, but all instances should be migrated.
- The
"gen-style"template used to add CSS styling - The
"start-flagit"and"end-flagit"templates used to generate image flags based on property attributes like @audience - The
"start-revflag"and"end-revflag"templates, used to generate images for active revisions - Shortcut templates that group these templates into a single call, such as:
"start-flags-and-rev"and"end-flags-and-rev", used to combine flags and revisions into one call"revblock"and"revtext", both used to output start revisions, element content, and end revisions- The modes
"outputContentsWithFlags"and"outputContentsWithFlagsAndStyle", both used to combine processing for property/revision flags with content processing
- All other templates that make use of the
$flagrulesvariable, which is no longer used in any of the DITA-OT 1.7 code - All templates within flag.xsl that were called from the templates listed above
- Element processing handled with mode="elementname-fmt", such as
mode="ul-fmt"for processing unordered lists andmode="section-fmt"for sections.
What replaces the templates?
The new flagging design described in the preprocess design section now adds literal copies of relevant DITAVAL elements, along with CSS based flagging information, into the relevant section of the topic. This allows most flags to be processed in document order; in addition, there is never a need to read the DITAVAL, interpret CSS, or evaluate flagging logic. The htmlflag.xsl file contains a few rules to match and process the start/end flags; in most cases, all code to explicitly process flags can be deleted.
Match element
Create "flagrules" variable by reading DITAVAL for
active flags
Output start tag such as <div> or <span>
Call "commonattributes" and ID processing
Call "gen-style" with $flagrules,
to create DITAVAL based CSS
Call "start-flagit" with $flagrules,
to create start flag images
Call "start-revflag" with $flagrules, to create start revision images
Output contents
Call "end-revflag" with $flagrules,
to create end revision images
Call "end-flagit" with $flagrules,
to create end flag images
Output end tag such as </div> or </span>
Match element
Output start tag such as <div> or <span>
Call "commonattributes" and ID processing
Output contents
Output end tag such as </div> or </span>
Migrating "gen-style" named template
Calls to the "gen-style" template should be deleted.
There is no need to replace this call for
most elements.
The "gen-style" template was designed to read a
DITAVAL file, find active style-based flagging
(such as colored or bold text), and add it to the generated @style attribute in HTML.
<ditaval-startprop> sub-element. The
"commonattributes"
template now includes a line to process that value; the result is that for every element
that calls
"commonattributes", DITAVAL style will be processed when
needed. Because virtually every
element includes a call to this common template, there is little chance that your override
needs to explicitly
process the style. The new line in "commonattributes" that
handles the style is:
<xsl:apply-templates select="*[contains(@class,'
ditaot-d/ditaval-startprop ')]/@outputclass" mode="add-ditaval-style"/>Migrating "start-flagit", "start-revflag",
"end-flagit",
and "end-flagit" named templates
Calls to these templates fall into two general groups.
If the flow of your element rule is to create a start tag like <div>,
"start-flagit"/"start-revflag",
process contents,
"end-revflag"/"end-flagit",
end tag - you just need to delete the calls to
these templates. Flags will be generated simply by processing the element contents in
document order.
<ol>, where flags must appear
before the <ol> in order to create valid XHTML. The
second is for elements like
<section>, where start flags are created, followed by
the title or some generated text,
element contents, and finally end flags. In either of these cases, support for processing
flags in document
order is disabled, so they must be explicitly processed out-of-line. This is done with the
following two lines
(one for start flag/revision, one for end
flag/revision):Create starting flag and revision images:
<xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-startprop ')]"
mode="out-of-line"/>
Create ending flag and revision images:
<xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-endprop ')]"
mode="out-of-line"/><ul> element
(replacing the 29 lines used in DITA-OT
1.6):<xsl:template match="*[contains(@class,' topic/ul
')]">
<xsl:apply-templates select="*[contains(@class,'
ditaot-d/ditaval-startprop ')]" mode="out-of-line"/>
<xsl:call-template name="setaname"/>
<ul>
<xsl:call-template name="commonattributes"/>
<xsl:apply-templates select="@compact"/>
<xsl:call-template name="setid"/>
<xsl:apply-templates/>
</ul>
<xsl:apply-templates select="*[contains(@class,'
ditaot-d/ditaval-endprop ')]" mode="out-of-line"/>
<xsl:value-of select="$newline"/>
</xsl:template>Migrating "start-flags-and-rev"
and "end-flags-and-rev"
"start-flags-and-rev"is equivalent to calling"start-flagit"followed by"start-revflag"; it should be migrated as in the previous section."end-flags-and-rev"is equivalent to calling"end-revflag"followed by"end-flagit"; it should be migrated as in the previous section.
Migrating "revblock" and "revtext"
Calls to these two templates can be replaced with a simple call to
<xsl:apply-templates/>.
Migrating modes "outputContentsWithFlags"
and
"outputContentsWithFlagsAndStyle"
Processing an element with either of these modes can be replaced with a simple call
to
<xsl:apply-templates/>.
Migrating mode="elementname-fmt"
Match element
Set variable to determine if revisions are active and $DRAFT is on
If active
create division with rev style
process element with mode="elementname-fmt"
end division
Else
process element with mode="elementname-fmt"
Match element with mode="elementname-fmt"
Process as needed
Beginning with DITA-OT 1.7, styling from revisions is handled automatically with
the
"commonattributes" template. This means there is no need for
the extra testing, or the
indirection to mode="elementname-fmt". These templates are
deprecated, and element processing
will move into the main element rule. Overrides that include this indirection may remove it;
overrides should
also be sure to match the default rule, rather than matching with
mode="elementname-fmt".
Migrating to release 1.6
In DITA-OT 1.6, various demo plugins were removed along with many deprecated properties, targets, templates and modes. The PDF2 transformation no longer supports the beta version of DITA from IBM, the "bkinfo" demo plug-in, or layout-masters.xml configuration.
Support for the old DITAVAL format (used before OASIS added DITAVAL to the standard in 2007) has been removed.
The demo folder has been deprecated and the following plug-ins have been moved to the plugins folder:
| old path | new path |
|---|---|
| demo/dita11 | plugins/org.dita.specialization.dita11 |
| demo/dita132 | plugins/org.dita.specialization.dita132 |
| demo/eclipsemap | plugins/org.dita.specialization.eclipsemap |
| demo/fo | plugins/org.dita.pdf2 |
| demo/tocjs | plugins/com.sophos.tocjs |
| demo/h2d | plugins/h2d |
| demo/legacypdf | plugins/legacypdf |
The remaining plug-ins in the demo folder have been moved to a separate repository at github.com/dita-ot/ext-plugins.
The deprecated property dita.input.valfile should be
replaced with the new argument property
args.filter.
The dita-preprocess target has been removed and
dependencies should be replaced with a target
sequence build-init, preprocess.
Support for the args.message.file argument has been
removed as message configuration has
become static configuration.
The workdir processing instruction has been deprecated
in favor of
workdir-uri. The only difference between the two processing
instructions is that
workdir-uri contains a URI instead of a system path.
Preprocessing
The following deprecated templates and modes have been removed in topic pull stylesheets:
- inherit
- get-stuff
- verify-type-attribute
- classval
- getshortdesc
- getlinktext
- blocktext
- figtext
- tabletext
- litext
- fntext
- dlentrytext
- firstclass
- invalid-list-item
- xref
PDF2
The following deprecated items are no longer supported in the PDF transform:
- Support for the beta version of DITA, available from IBM before the OASIS standard was created in 2005.
- Support for the "bkinfo" demo plug-in, used to support book metadata before OASIS created the BookMap format in 2007.
- Support for layout-masters.xml configuration.
Plug-ins should use the
createDefaultLayoutMasterstemplate instead.
The following extension-points have been added:
dita.conductor.pdf2.paramto add XSLT parameters to XSL FO transformation.
Custom PDF2 shell stylesheets need to be revised to not include separate IBM and OASIS DITA stylesheets. The *_1.0.xsl stylesheets have been removed and their imports must be removed from shell stylesheets.
The following template modes have been deprecated:
- toc-prefix-text
- toc-topic-text
The following named templates have been removed:
- processTopic
- createMiniToc
- processTopicTitle
- createTopicAttrsName
- processConcept
- processReference
- getTitle
- placeNoteContent
- placeImage
- processUnknowType
- insertReferenceTitle
- buildRelationships
- processTask
The main FO generation process now relies on the merging process to rewrite duplicate IDs. The default merging process did this already in previous releases, but now also custom merging processes must fulfill the duplicate ID rewrite requirement.
XHTML
The following named templates have been deprecated:
- make-index-ref
The following deprecated templates have been removed:
- revblock-deprecated
- revstyle-deprecated
- start-revision-flag-deprecated
- end-revision-flag-deprecated
- concept-links
- task-links
- reference-links
- relinfo-links
- sort-links-by-role
- create-links
- add-linking-attributes
- add-link-target-attribute
- add-user-link-attributes
The removed templates have been replaced by other templates in earlier releases and plug-ins should be changed to use the new templates.
ODT
The following deprecated templates have been removed:
- revblock-deprecated
- revstyle-deprecated
- start-revision-flag-deprecated
- end-revision-flag-deprecated
The removed templates have been replaced by other templates in earlier releases and plug-ins should be changed to use the new templates.
Migrating to release 1.5.4
DITA-OT 1.5.4 adds new extension points to configure behavior based on file extensions, declare print transformation types and add mappings to the PDF configuration catalog file. PDF output supports mirrored page layout and uses new font family definitions. Support for several new languages was added for PDF and XHTML output.
Configuration properties file changes
In previous versions, the lib/configuration.properties file was generated by the integration process. Integration has been changed to generate lib/org.dita.dost.platform/plugin.properties and the role of the old lib/configuration.properties has been changed to contain defaults and configuration options, such as default language.
The dita.plugin.org.dita.*.dir properties have been
changed to point to the DITA-OT base
directory.
To allow access to configuration files, the lib directory needs to be added to the Java classpath.
New plug-in extension points
New plug-in extension points have been added allow configuring DITA-OT behavior based on file extensions.
| Extension point | Description | Default values |
|---|---|---|
dita.topic.extension
|
DITA topic | .dita, .xml |
dita.map.extensions
|
DITA map | .ditamap |
dita.html.extensions
|
HTML file | .html, .htm |
dita.resource.extensions
|
Resource file | .pdf, .swf |
Both HTML and resource file extensions are used to determine if a file in source is copied to output.
A new plug-in extension point has been added to declare transformation types as print types.
| Extension point | Description |
|---|---|
dita.transtype.print
|
Declare transformation type as a print type. |
The print_transtypes property in integrator.properties has been
deprecated in favor of dita.transtype.print.
Plugin URI scheme
Support for the plugin URI scheme has been added to XSLT stylesheets. Plug-ins can refer to files in other plug-ins without hard-coding relative paths, for example:
<xsl:import href="plugin:org.dita.pdf2:xsl/fo/topic2fo_1.0.xsl"/>XHTML
Support for the following languages has been added:
- Indonesian
- Kazakh
- Malay
Support for mirrored page layout was added. The default is the unmirrored layout. The following XSLT configuration variables have been deprecated:
page-margin-leftpage-margin-right
The following variables should be used instead to control page margins:
page-margin-outsidepage-margin-inside
The args.bookmap-order property has been added to
control how front and back matter are
processed in bookmaps. The default is to reorder the frontmatter content as in previous
releases.
A new extension point has been added to add mappings to the PDF configuration catalog file.
| Extension point | Description |
|---|---|
org.dita.pdf2.catalog.relative
|
Configuration catalog includes. |
Support for the following languages has been added:
- Finnish
- Hebrew
- Romanian
- Russian
- Swedish
PDF processing no longer copies images or generates XSL FO to output directory.
Instead, the temporary
directory is used for all temporary files and source images are read directly from source
directory. The legacy
processing model can be enabled by setting org.dita.pdf2.use-out-temp to true
in configuration properties; support for the legacy processing model may be removed in future
releases.
Support for FrameMaker index syntax has been disabled by default. To enable FrameMaker
index syntax, set
org.dita.pdf2.index.frame-markup to true in configuration properties.
A configuration option has been added to disable internationalization (I18N) font
processing and use
stylesheet-defined fonts. To disable I18N font processing, set org.dita.pdf2.i18n.enabled
to
false in configuration properties.
The XSLT parameters customizationDir and fileProfilePrefix have been removed
in favor of the customizationDir.url parameter.
A new shell stylesheet has been added for FOP and other shell stylesheets have also been revised. Plug-ins which have their own shell stylesheets for PDF processing should make sure all required stylesheets are imported.
Font family definitions in stylesheets have been changed from Sans, Serif, and Monospaced to sans-serif, serif, and monospace, respectively. The I18N font processing still uses the old logical names and aliases are used to map the new names to old ones.
Implementation dependent features
Chunking
Supported chunking methods:
- select-topic
- select-document
- select-branch
- by-topic
- by-document
- to-content
- to-navigation.
When no chunk attribute values are given, no chunking is performed.
Error recovery:
- When two tokens from the same category are used, no error or warning is thrown.
- When an unrecognized chunking method is used, no error or warning is thrown.
Filtering
Error recovery:
- When there are multiple
revpropelements with the same val attribute, no error or warning is thrown - When multiple prop elements define a duplicate attribute and value combination, attribute default, or fall-back behavior, the DOTJ007E error is thrown.
Debug attributes
The debug attributes are populated as follows:
- xtrf
- absolute system path of the source document
- xtrc
- element counter that uses the
format
element-name ":" integer-counter ";" line-number ":" column-number
Image scaling
If both height and width attributes are given, the image is scaled non-uniformly.
If the scale attribute is not an unsigned integer, no error or warning is thrown during preprocessing.
Map processing
When a topicref element that references a map contains child
topicref
elements, the DOTX068W error is thrown and the child topicref elements are
ignored.
Link processing
When the value of href attribute is not a valid URI
reference, the DOTJ054E
error is thrown. Depending on the
processing-mode
setting, error
recovery may be attempted.
Copy-to processing
When the copy-to attribute is specified on a topicref, the content of the
shortdesc element is not used to override the short description of
the topic.
Coderef processing
When coderef elements are used within codeblocks to
reference external files with literal code
samples, the system default character set is used as the target file encoding unless a different
character set
is explicitly defined via the mechanisms described under
Character set
definition.
Extended functionality
Code reference processing
Character set definition
DITA-OT supports defining the code reference target file encoding using the format
attribute. The supported format is:
format (";" space* "charset=" charset)?If a character set is not defined, the system default character set will be used. If the character set is not recognized or supported, the DOTJ052E error is thrown and the system default character set is used as a fall-back.
<coderef href="unicode.txt" format="txt;
charset=UTF-8"/>Line range extraction
Code references can be limited to extract only a specified line range by defining the
line-range pointer in the URI fragment. The format is:
uri ("#line-range(" start ("," end)? ")" )?Start and end line numbers start from 1 and are inclusive. If the end range is omitted, the range ends on the last line of the file.
<coderef href="Parser.scala#line-range(5, 10)" format="scala"/>Only lines from 5 to 10 will be included in the output.
RFC 5147
DITA-OT implements line position and range from RFC 5147. The format for line range is:
uri ("#line=" start? "," end? )?Start and end line numbers start from 0 and are inclusive and exclusive, respectively. If the start range is omitted, the range starts from the first line; if the end range is omitted, the range ends on the last line of the file. The format for line position is:
uri ("#line=" position )?Position line number starts from 0.
<coderef href="Parser.scala#line=4,10"
format="scala"/>Only lines from 5 to 10 will be included in the output.