DITA Open Toolkit, version 1.8.M2

Chapter 1: Getting Started with the DITA Open Toolkit

The Getting Started Guide is designed to provide a guided exploration of the DITA Open Toolkit. It is geared for an audience that has little or no knowledge of build scripts or DITA-OT parameters. It walks the novice user through installing the full-easy-install version of the toolkit and running a prompted build.

1.1.1: Installing the full-easy-install package

For the simplest installation experience, install the full-easy-install package. This package can be installed on Linux, Mac OSX, and Windows. It contains everything that you need to run the DITA-OT except for Java.

Ensure that you have Java JRE or JDK, version 6 or later installed.
Ensure that you have HTML Help Workshop installed, if you want to generate HTML Help.

Download the full-easy package from SourceForge.

Operating system	File name
Linux or Mac OSX	`DITA-OT1.8.M2_full_easy_install_bin.tar.gz`
Windows	`DITA-OT1.8.M2_full_easy_install_bin.zip`

Extract the contents of the package to the directory where you want to install the DITA-OT.
Run the startcmd file that is applicable for your operating system.
This defines the necessary environment variables and opens a DOS prompt or terminal window in which you can invoke the toolkit. You can use the window to run as many builds as you want; if you close the window, you will need to run the applicable startcmd file again.

1.1.2: Running the demo build

After you install the full-easy-install package, run the demo build to see the type of output that is produced by the DITA Open Toolkit.

Run the startcmd file that is applicable for your operating system.
The startcmd.bat and startcmd.sh files are in the directory where you installed the DITA-OT.

From the DITA-OT shell, enter the following command:

ant -f build_demo.xml

You receive the following prompt:

[echo] Please enter the filename for the DITA map that you 
[echo] want to build including the directory path (if any). 
[echo] The filename must have the .ditamap extension. 
[echo] Note that relative paths that climb (..) are not supported yet. 
[echo] To build the sample, press return without entering anything. 
[input] The DITA map filename: [C:\DITA-OT1.6.M5\samples\hierarchy.ditamap]

Press Enter.

You receive the following prompt:

[echo] 
[echo] Please enter the name of the output directory or press return 
[echo] to accept the default. 
[input] The output directory (out): [out]

Press Enter.

You receive the following prompt:

[echo] Please enter the type of output to generate. 
[echo] Options include: eclipse, tocjs, htmlhelp, javahelp, pdf, or web 
[echo] Use lowercase letters. 
[echo] 
[input] The output type: (eclipse, tocjs, htmlhelp, javahelp, pdf, [web], docbook)

Press Enter to accept the default transformation type: web.
This will build XHTML files from the DITA source.
You receive the following prompt:
```
[echo] Ready to build C:\DITA-OT1.6.M5\samples\hierarchy.ditamap 
[echo] for web in out 
[echo] 
[input] Continue? (Y, [y], N, n)
```
Press Y or y to start the DITA-OT transformation.
The DITA-OT logs information to the command-prompt or terminal window. At the end, you see the following information:
```
prompt.output: 
[echo] 
[echo] output in the out directory 
[echo] 
[echo] Before rebuilding, please delete the output or the directory. 
BUILD SUCCESSFUL Total time: X minutes X seconds
```
Go to the out/ directory and open the toc.html file in a Web browser.

XHTML output for the sample files

The DITA-OT transformed the hierarchy.ditamap file (located in the samples directory) to XHTML; it wrote the output to the out/ directory.

1.1.3: Building your own content using the demo build

You can use the demo build to generate output for your own DITA content.

If necessary, run the startcmd file that is applicable for your operating system.
You do not need to run the startcmd file if you already have a command-prompt or terminal window that was invoked by the startcmd file open.
From the DITA-OT shell, enter the following command:
```
ant -f build_demo.xml
```
When prompted, type the name of a map.
You must specify the path for the DITA map. You either can specify a fully qualified file name, for example, C:\DITA-OT1.6.M5\doc\userguide.ditamap, or you can specify a relative path, for example, doc\userguide.ditamap
When prompted, type the name of the output directory.

When prompted, type the value for the transformation type.

Ouput format	Value
Docbook	docbook
Eclipse help	eclipse
HTML help	htmlhelp
PDF	pdf
XHTML	web
XHTML with a JavaScript frame set	tocjs

When prompted, press Enter to start the transformation.

The DITA-OT generates output for the specified DITA content. It runs the transformation that you specified, and writes the output to the directory that you specified.

Explore invoking the DITA-OT from either Ant or the command-line tool. This enables you to specify a wider array of parameters than those supported by the demo build.

Using Ant or the command-line tool, you can perform the following tasks (and more):

Add a custom CSS file to the transformation
Generate labels for the sections of task topics
Specify that draft comments are included in the output
Turn on "Related link" sections in a PDF file

Chapter 2: DITA Open Toolkit User Guide

The DITA Open Toolkit User Guide is designed to provide basic information about the DITA-OT. It is geared for an audience that needs information about installing, running, and troubleshooting the toolkit. It contains documentation of the DITA-OT parameters; it also contains release notes and information about what components have been tested.

2.2.1: Overview of the DITA Open Toolkit

The DITA Open Toolkit (DITA-OT) is an open-source implementation of the OASIS DITA specification, which is developed by the OASIS DITA Technical Committee. The DITA-OT is a set of Java-based, open-source tools and Ant scripts that transform DITA content (maps and topics) into deliverable formats, including Eclipse Help, HTML Help, JavaHelp, PDF, and XHTML.

While the DITA standard is owned and developed by OASIS, the DITA-OT project is governed separately; the DITA-OT is an independent, open-source implementation of the DITA standard. The DITA-OT is available without charge and is licensed under the CPL 1.0 and Apache 2.0 open-source licenses.

2.2.1.1: DITA Open Toolkit Release 1.8

General Enhancements and Changes

Preprocessing

Additional validation has been added to check e.g. element ID uniqueness, and xml:lang and URI syntax.

PDF

Bundled FOP has been updated from 1.0 to 1.1.

Migration from previous releases

Stylesheets for the following transtypes 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} instead
dita.resource.dir, use ${dita.plugin.org.dita.base.dir}/resource instead
dita.empty
args.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.

PDF

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-processing
toc-prefix-text, use tocPrefix mode instead
toc-topic-text, use tocText mode instead

Link generation has been simplified by removing deprecated arguments in favour of args.rellinks. The following deprecated Ant properties have been removed:

args.fo.include.rellinks

The following XSLT parameters have been removed:

antArgsIncludeRelatedLinks
disableRelatedLinks

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 favour 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

Issues

The following items are included in DITA Open Toolkit Release 1.8. Issue numbers correspond to the tracking number in the GitHub issues tracker .

Feature requests

#1406 Bundle FOP 1.1 (milestone 1)
#1447 Move stylesheets and resource files to plug-in folder (milestone 1)
#1449 Add support for Slovenian (milestone 1)
#1453 Add image metadata filter (milestone 1)
#1455 Remove deprecated features

Bugs

#1425 XHTML flagging included before imports (milestone 1)
#1428 Topic level calculated incorrectly for appendices (milestone 1)
#1427 Fix text overflow issue in lot/lof entries with long titles (milestone 1)
#1430 PDF transformation: Problems with index in OT 1.7 (milestone 1)
#1432 startcmd.sh broken in 1.7 (milestone 1)
#1433 Profiling filter included multiple times (milestone 1)
#1437 Fatal UTF-8 error in .job.xml (milestone 1)
#1456 XHTML Build failed when referencing subject scheme in different file path (milestone 1)
#1080 Index page range issues (milestone 2)
#1423 Formatting glitch in PDF index (maintenance 2)
#1468 Reference to remote image does not appear in PDF (maintenance 2)
#1469 @outputclass and @class values not passed from <chhead> to <tr> in XHTML output (maintenance 2)
#1472 PDF output: whitespace not preserved in msgblock element (maintenance 2)
#1475 Error received in console does not point correctly to location of published DITA Map (maintenance 2)
#1477 Tables: using percentage in colwidth values [PDF2 plugin] (maintenance 2)

2.2.1.2: DITA 1.2 Specification Support

DITA Open Toolkit 1.8.M2 supports the DITA 1.2 specification. Initial support for this specification was added in version 1.5 of the toolkit; versions 1.5.1 and 1.5.2 contain minor modifications to keep up with the latest drafts. The specification itself was approved at approximately the same time as DITA-OT 1.5.2, which contained the final versions of the DTD and Schemas. DITA-OT 1.6 updated the DITA 1.2 XSDs to address minor errata in the standard; the DTDs remain up to date.

Earlier versions of the DITA Open Toolkit contained a subset of the specification material, including descriptions of each DITA element. This material was shipped in source, CHM and PDF format. This was possible in part because versions 1.0 and 1.1 of the DITA Specification contained two separate specification documents: one for the architectural specification, and one for the language specification.

In DITA 1.2, each of these has been considerably expanded, and the two have been combined into a single document. The overall document is much larger, and including the same set of material would double the size of the DITA-OT package. Rather than include that material in the package, we’ve provided the links below to the latest specification material.

Highlights of DITA 1.2 support in the toolkit include:

Processing support for all new elements and attributes
Link redirection and text replacement using keyref
New processing-role attribute in maps to allow references to topics that will not produce output artifacts
New conref extensions, including the ability to reference a range of elements, to push content into another topic, and to use keys for resolving a conref attribute.
The ability to filter content with controlled values and taxonomies, using the new Subject Scheme Map
Processing support for both default versions of task (original, limited task, and the general task with fewer constraints on element order)
Acronym and abbreviation support with the new <abbreviated-form> element
New link grouping abilities available with headers in relationship tables
OASIS Subcommittee specializations from the learning and machine industry domains (note that the core toolkit contains only basic processing support for these, but can be extended to produce related artifacts such as SCORM modules)

To find detailed information about any of these features, see the specification documents at OASIS. The DITA Adoption Technical Committee has also produced several papers to describe individual new features. In general, the white papers are geared more towards DITA users and authors, while the specification is geared more towards tool implementors, though both may be useful for either audience. The DITA Adoption papers can be found from that TC’s main web page.

2.2.1.3: Tested platforms and tools

The DITA Open Toolkit (DITA-OT) has been tested against certain versions of Ant, ICU for Java, JDK, operating systems, XML parsers, and XSLT processors.

Application	Tested version
Ant	Ant 1.7.1 Ant 1.8.2, 1.8.3, 1.8.4
ICU for Java	ICU4J 3.4.4 ICU4J 49.1
JDK	IBM 1.6 OpenJDK 1.7 Oracle 1.6
Operating system	Mac OS X 10.6 Mac OS X 10.7 SLES 10 Windows XP Windows 7
XML parser	Xerces 2.9.0 Xerces 2.11.0
XSLT processor	Saxon 6.5 Saxon 9 Saxon-B 9.1 Saxon-PE/EE 9.3 Xalan-J 2.6 Xalan-J 2.7 Xalan-J 2.7.1 Note The DITA-OT does not officially require XSLT 2.0, since some users are reliant on Xalan.

2.2.2: Installing the DITA Open Toolkit

You can install the DITA Open Toolkit (DITA-OT) on Linux, Mac OSX, and Windows. The process for installing and setting up the DITA-OT depends on the type of distribution package that you select.

2.2.2.1: Distribution packages

The DITA Open Toolkit is distributed in three packages: minimal, standard, and full-easy-install. The source code is available both as a Git repository and a ZIP file.

Minimal package

This package is designed for vendors that embed the toolkit within a product. It contains all of the core processing code: CSS and XSLT files, Ant build scripts, Java code (dost.jar), resource files, and the OASIS DITA DTDs and Schemas. Users need to have their own versions of Ant and other libraries; they also need to set up environment variables for each library. The only external files that are included are the DTDs and Schemas, along with the following open-source libraries:

Apache Catalog Resolver, version 1.1
Apache Commons Codec, version 1.4
Apache Xerces, version 2.11.0

The minimal package has the following file names:

DITA-OT1.8.M2_minimal_bin.zip
DITA-OT1.8.M2_minimal_bin.tar.gz

Standard package

This package is designed for people who want the core toolkit functionality, but who already have locally-installed copies of Ant and other required tools. It contains everything in the minimal package, plus documentation, demo code (for example, legacy support for the old bookmap), sample Ant scripts, and sample DITA files. The standard package includes the following open-source libraries:

Regarding the statement above that the standard package includes demo code -- Is this still true and is the example still correct?

Apache Catalog Resolver, version 1.1
Apache Commons Codec, version 1.4
Apache Xerces, version 2.11.0

The standard package has the following file names:

DITA-OT1.8.M2_standard_bin.zip
DITA-OT1.8.M2_standard_bin.tar.gz

Full-easy-install package

his package is designed for users who want the simplest installation experience. In addition to the core DITA-OT code and the external libraries that are in the minimal and standard packages, it contains Apache Ant and FOP. The full-easy-install package also contains batch files designed to set up a build environment using those tools, as well as a scripts for a guided demo of the DITA-OT. The full-easy-install package includes the following external libraries:

Apache Ant, version 1.8.4
Apache Catalog Resolver, version 1.1
Apache Commons Codec, version 1.4
Apache FOP, version 1.0
ICU for Java, version 49.1
Apache Xerces, version 2.11.0
Saxon, version 9.1

The full-easy-install package has the following file names:

DITA-OT1.8.M2_full_easy_install_bin.zip
DITA-OT1.8.M2_full_easy_install_bin.tar.gz

2.2.2.2: Prerequisite software

The prerequisite software that the DITA-OT requires depends on the type of distribution package that you intend to install and the types of transformations that you want to use.

Software required for core DITA-OT processing

The DITA-OT requires the following software applications:

JRE or JDK, version 6 or later: Provides the basic environment for the DITA-OT. You can download the Oracle JRE or JDK from http://www.oracle.com/technetwork/java/javase/overview/index.html. If you opt to use the full-easy-install package, this is the only prerequisite software that you need to install.
Ant, version 1.7.1 or later: Provides the standard setup and sequencing of processing steps. You can download Ant from http://ant.apache.org/.
XSLT processor: Provides the main transformation services. It must be compliant with XSLT 1.0. The DITA-OT is tested with both Saxon and Xalan-J. You can download Saxon, version 9.1 from http://saxon.sourceforge.net/ and Xalan-J, version 2.7.1 or later from http://xml.apache.org/xalan-j/downloads.html.

Software required for specific transformations

Depending on the type of output that you want to generate, you might need the following applications:

ICU for Java: Does the DITA-OT only use ICU for Java for index processing? Index processing is what is explicitly mentioned in the installing topics.
ICU for Java is a cross-platform, Unicode-based, globalization library. It includes support for comparing locale-sensitive strings; formatting dates, times, numbers, currencies, and messages; detecting text boundaries; and converting character sets. You can download ICU for Java from http://www.icu-project.org/download/.
Microsoft Help Workshop: Required for generating HTML help. You can download the Help Workshop from http://msdn.microsoft.com/en-us/library/windows/desktop/ms669985(v=vs.85).aspx.
XSL-FO processor: Required for generating PDF output. You can download FOP from http://xmlgraphics.apache.org/fop/download.html; you also can use Antenna House Formatter or RenderX.

See Tested platforms and tools for detailed information about versions of the prerequisite applications that have been tested with the current DITA-OT release.

2.2.2.3: Installing the full-easy-install package

Ensure that you have Java JRE or JDK, version 6 or later installed.
Ensure that you have HTML Help Workshop installed, if you want to generate HTML Help.

Download the full-easy package from SourceForge.

Operating system	File name
Linux or Mac OSX	`DITA-OT1.8.M2_full_easy_install_bin.tar.gz`
Windows	`DITA-OT1.8.M2_full_easy_install_bin.zip`

Extract the contents of the package to the directory where you want to install the DITA-OT.
Run the startcmd file that is applicable for your operating system.
This defines the necessary environment variables and opens a DOS prompt or terminal window in which you can invoke the toolkit. You can use the window to run as many builds as you want; if you close the window, you will need to run the applicable startcmd file again.

2.2.2.4: Installing the minimal or standard package on Linux or Mac OSX

If you already have locally-installed copies of Ant and the other required tools, install either the minimal or standard package.

Ensure that you have the following prerequisite software installed:

Ant, version 1.7.1 or later
Java runtime environment or development kit, version 6 or later
XSLT processor. You can use either Saxon, version 9.1 or later, or Xalan-J, version 2.7.1 or later.

In addition, determine the specific DITA-OT transformations that you intend to support and ensure that you have the prerequisite software installed for them.

For more information, see Prerequisite software and Tested platforms and tools.

Download the minimal or standard package from SourceForge.

Package	File name
Minimal	`DITA-OT1.8.M2_minimal_bin.tar.gz`
Standard	`DITA-OT1.8.M2_standard_bin.tar.gz`

For production use, we recommend that you use the latest stable release.

Extract the contents of the package into an installation directory.

Note

You can extract the files either to your private home directory for your exclusive use or to the /usr/local/share/ directory, if you want to share the DITA-OT with other users.
Verify that the JAVA_HOME environment variable is set.
```
export JAVA_HOME=<JRE_dir>
```
Verify that the ANT_HOME environment variable is been set.
```
export ANT_HOME=<Ant_dir>
```
Verify that the PATH environment variable includes the Java and Ant executable files.
```
export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
```
Set the DITA_HOME environment variable to point to the DITA-OT installation directory.
```
export DITA_HOME=<DITA-OT_dir>
```

Set up the CLASSPATH environment variable.

export CLASSPATH=$DITA_HOME/lib/dost.jar:$CLASSPATH
export CLASSPATH=$DITA_HOME/lib:$CLASSPATH
export CLASSPATH=$DITA_HOME/lib/resolver.jar:$CLASSPATH
export CLASSPATH=$DITA_HOME/lib/commons-codec-1.4.jar:$CLASSPATH

If you use Ant, version 1.8 or later, set up the CLASSPATH environment variable to include Apache Xerces.
```
export CLASSPATH=<xerces_dir>/xercesImpl.jar:<xerces_dir>/xml-apis.jar:$CLASSPATH
```

Set up the XSLT processor:

Processor Action

Saxon

Processor	Action
Saxon	Set up the CLASSPATH environment variable to include the Saxon JAR files, for example: export CLASSPATH=<saxon_dir>/saxon9.jar:<saxon_dir>/saxon9-dom.jar:$CLASSPATH Set up the `ANT_OPTS` environment variable, for example: export ANT_OPTS=$ANT_OPTS -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl
Xalan	Set up the CLASSPATH environment variable to include the Xalan JAR files, for example: export CLASSPATH=<xalan_dir>/xalan.jar:$CLASSPATH

Set up the CLASSPATH environment variable to include the Saxon JAR files, for example:

export CLASSPATH=<saxon_dir>/saxon9.jar:<saxon_dir>/saxon9-dom.jar:$CLASSPATH

Set up the ANT_OPTS environment variable, for example:

export ANT_OPTS=$ANT_OPTS -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl

Xalan

Set up the CLASSPATH environment variable to include the Xalan JAR files, for example:

export CLASSPATH=<xalan_dir>/xalan.jar:$CLASSPATH

For index processing, set up ICU for Java.

export CLASSPATH=<icu4j_dir>/icu4j.jar:$CLASSPATH

For JavaHelp, set the JHHOME environment variable.
```
export JHHOME=<javahelp_dir>
```

For PDF output, set up the XSL-FO processor:

Processor Action

FOP

Processor	Action
FOP	Add the FOP installation directory to the `local.properties` file as the fop.home property, for example: fop.home=/usr/share/java/fop
RenderX	Add the RenderX installation directory to the `local.properties` file as the xep.dir property, for example: xep.dir=/usr/share/java/xep
Antenna House	Add the AH Formatter installation directory to the `local.properties` file as the axf.path property, for example: axf.path=/usr/share/java/AHFormatterV6

Add the FOP installation directory to the local.properties file as the fop.home property, for example:

fop.home=/usr/share/java/fop

RenderX

Add the RenderX installation directory to the local.properties file as the xep.dir property, for example:

xep.dir=/usr/share/java/xep

Antenna House

Add the AH Formatter installation directory to the local.properties file as the axf.path property, for example:

axf.path=/usr/share/java/AHFormatterV6

Test the DITA-OT installation by transforming the sample files.
The samples\ant_sample directory contains Ant scripts designed to build various output formats.
```
/usr/local/share/DITA-OT1.8.M2$ ant -f samples/ant_sample/sample_all.xml
```
The generated output is written to the DITA-dir\out\samples directory. The following output formats are generated:
- Docbook
- Eclipse help
- HTML Help
- ODT
- JavaHelp
- PDF
- TocJS
- TROFF
- XHTML

2.2.2.5: Installing the minimal or standard package on Windows

If you already have locally-installed copies of Ant and the other required tools, install either the minimal or standard package.

Ensure that you have the following prerequisite software installed:

Ant, version 1.7.1 or later
Java runtime environment or development kit, version 6 or later
XSLT processor. You can use either Saxon, version 9.1 or later, or Xalan-J, version 2.7.1 or later.

In addition, determine the specific DITA-OT transformations that you intend to support and ensure that you have the prerequisite software installed for them.

For more information, see Prerequisite software and Tested platforms and tools.

Download the minimal or standard package from SourceForge.

Package	File name
Minimal	`DITA-OT1.8.M2_minimal_bin.zip`
Standard	`DITA-OT1.8.M2_standard_bin.zip`

For production use, we recommend that you use the latest stable release.

Extract the contents of the package into an installation directory.
For example, C:\pkg\DITA-OT1.8.M2.
Verify that the JAVA_HOME environment variable is set.
```
set JAVA_HOME=<JRE_dir>
```
Verify that the ANT_HOME environment variable is set.
```
set ANT_HOME=<Ant_dir>
```
Verify that the PATH environment variable includes the Java and Ant executable files.
```
set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%
```
Set the DITA_HOME environment variable to point to the DITA-OT installation directory.
```
set DITA_HOME=<DITA-OT_dir>
```

Set up the CLASSPATH environment variable.

set CLASSPATH=%DITA_HOME%\lib\dost.jar;%CLASSPATH%
set CLASSPATH=%DITA_HOME%\lib;%CLASSPATH%
set CLASSPATH=%DITA_HOME%\lib\resolver.jar;%CLASSPATH%
set CLASSPATH=%DITA_HOME%\lib\commons-codec-1.4.jar;%CLASSPATH%

If you use Ant, version 1.8 or later, set up the CLASSPATH environment variable to include Apache Xerces.
```
set CLASSPATH=<xerces_dir>\xercesImpl.jar;<xerces_dir>\xml-apis.jar;%CLASSPATH%
```

Set up the XSLT processor:

Processor Action

Saxon

Processor	Action
Saxon	Set up the CLASSPATH environment variable to include the Saxon JAR files, for example: set CLASSPATH=<saxon_dir>\saxon9.jar;<saxon_dir>\saxon9-dom.jar;%CLASSPATH% Set up the `ANT_OPTS` environment variable, for example: set ANT_OPTS=%ANT_OPTS% -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl
Xalan	Set up the CLASSPATH environment variable to include the Xalan JAR files, for example: set CLASSPATH=<xalan_dir>\xalan.jar;%CLASSPATH%

Set up the CLASSPATH environment variable to include the Saxon JAR files, for example:

set CLASSPATH=<saxon_dir>\saxon9.jar;<saxon_dir>\saxon9-dom.jar;%CLASSPATH%

Set up the ANT_OPTS environment variable, for example:

set ANT_OPTS=%ANT_OPTS% -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl

Xalan

Set up the CLASSPATH environment variable to include the Xalan JAR files, for example:

set CLASSPATH=<xalan_dir>\xalan.jar;%CLASSPATH%

For index processing, set up ICU for Java.

set CLASSPATH=<icu4j_dir>\icu4j.jar;%CLASSPATH%

For JavaHelp, set the JHHOME environment variable.
```
set JHHOME=<javahelp_dir>
```
For HTML Help, add the installation directory for the HTML Help Workshop to the local.properties file as the hhc.dir property.
```
hhc.dir=C:\\Program Files (x86)\\HTML Help Workshop
```

For PDF output, set up the XSL-FO processor:

Processor Action

FOP

Processor	Action
FOP	Add the FOP installation directory to the `local.properties` file as the fop.home property, for example: fop.home=C:\\Program Files\\fop
RenderX	Add the RenderX installation directory to the `local.properties` file as the xep.dir property, for example: xep.dir=C:\\Program Files\\xep
Antenna House	Add the AH Formatter installation directory to the `local.properties` file as the axf.path property, for example: axf.path=C:\\Program Files\\AHFormatterV6

Add the FOP installation directory to the local.properties file as the fop.home property, for example:

fop.home=C:\\Program Files\\fop

RenderX

Add the RenderX installation directory to the local.properties file as the xep.dir property, for example:

xep.dir=C:\\Program Files\\xep

Antenna House

Add the AH Formatter installation directory to the local.properties file as the axf.path property, for example:

axf.path=C:\\Program Files\\AHFormatterV6

Test the DITA-OT installation by transforming the sample files.
The samples\ant_sample directory contains Ant scripts designed to build various output formats.
```
C:\DITA-OT1.8.M2>ant -f samples\ant_sample\sample_all.xml
```
The generated output is written to the DITA-dir\out\samples directory. The following output formats are generated:
- Docbook
- Eclipse help
- HTML Help
- ODT
- JavaHelp
- PDF
- TocJS
- TROFF
- XHTML

2.2.3: Publishing DITA content

You can use either Ant or the command-line tool to transform DITA content to the various output formats that are supported by the DITA Open Toolkit (DITA-OT).

2.2.3.1: DITA-OT transformations

The DITA Open Toolkit (DITA-OT) ships with several core transformations. Each core transformation represents an implementation of all processing that is defined by OASIS in the DITA specification.

2.2.3.1.1: DITA to Docbook

The docbook transformation converts DITA maps and topics into a Docbook output file. Complex DITA markup might not be supported, but the transformation supports most common DITA structures.

2.2.3.1.2: DITA to Eclipse Content

The eclipsecontent transformation generates normalized DITA files and Eclipse control files. It originally was designed for an Eclipse plug-in that dynamically rendered DITA content, but the output from the transformation can be used by other applications that work with DITA.

Normalized DITA files have been through the DITA Open Toolkit pre-processing operation. In comparison to the source DITA files, the normalized DITA file are modified in the following ways:

Map-based links, such as those generated by map hierarchy and relationship tables, are added to the topics.
Link text is resolved.
Any DTD or Schema reference is removed.
Class attributes that are defaulted in the DTD or Schema are made explicit in the topics.
Map attributes that cascade are made explicit on child elements.

The normalized DITA files have an extension of .xml.

2.2.3.1.3: DITA to Eclipse help

The eclipsehelp transformation generates XHTML output, CSS files, and the control files that are needed for Eclipse help.

In addition to the XHTML output and CSS files, this transformation returns the following files, where mapname is the name of the master DITA map.

File name	Description
`plugin.xml`	Control file for the Eclipse plug-in
`mapname.xml`	Table of contents
`index.xml`	Index file
`plugin.properties`
`META-INF/MANIFEST.MF`

RDA> The following paragraph correctly describes the Eclipse Help specialization, but I'm keeping it out until we have more complete documentation. I'd like to get more complete docs on this into an upcoming milestone.

For more complex plug-ins, the plugins directory in the DITA-OT contains an "Eclipse Map" specialization that gives more control over the generated plugin.xml file. The specialization provides additional control over metadata, as well as the ability to reference multiple TOC files, index files, and other Eclipse extensions.

2.2.3.1.4: DITA to HTML Help (CHM)

The htmlhelp transformation generates HTML output, CSS files, and the control files that are needed to produce a Microsoft HTML Help file.

In addition to the HTML output and CSS files, this transformation returns the following files, where mapname is the name of the master DITA map.

File name	Description
`mapname.hhc`	Table of contents
`mapname.hhk`	Sorted index
`mapname.hhp`	HTML Help project file
`mapname.chm`	Compiled HTML Help Note This file is generated only if the HTML Help Workshop is installed on the build system.

2.2.3.1.5: DITA to legacy PDF transformation

The legacypdf transformation produces a PDF using the demo PDF build. This transformation is deprecated.

The first versions of the toolkit came with the demo PDF build, which was replaced by the more robust PDF plug-in (also known as PDF2) in release 1.4.3. The demo PDF build is no longer maintained by the DITA-OT developers, although the toolkit includes it in order to support older customizations and build scripts that extended the code.

2.2.3.1.6: DITA to Open Document Type

The odt transformation produces output files that use the Open Document format, which is used by tools such as Open Office.

This transform returns an ODT document, which is a zip file that contains the ODF XML file (content.xml), referenced images, and default styling (in the file styles.xml).

2.2.3.1.7: DITA to PDF (PDF2)

The pdf (or pdf2) transformation generates PDF output.

This transformation was originally created as a plug-in and maintained outside of the main toolkit code. It was created as a more robust alternative to the demo PDF transformation in the original toolkit, and thus was known as PDF2. The plug-in was bundled into the default toolkit distribution with release 1.4.3.

2.2.3.1.8: DITA to Rich Text Format

The wordrtf transformation produces an RTF file for use by Microsoft Word.

The structure of the generated RTF file is the same as the navigation structure in the DITA map. To avoid losing files in the final output, make sure the DITA map contains all topics that are referenced from any individual topics.

The wordrtf transformation has the following limitations:

Flagging, filtering, and revision bars are not supported.
Style attributes for tables are not supported.
Tables within list items are not supported.
Output styles supported by other DITA-OT transformations, for example, X and Y, are not supported.

What can we replace X and Y with? The original text read "There may be no output style applied on contents of some tags in Word RTF output compared with other output." Also, what does "Style attributes for tables are not supported" mean?

2.2.3.1.9: DITA to TocJS

The tocjs transformation generates XHTML output, a frameset, and a JavaScript-based table of contents with expandable and collapsible entries. The transformation was originally created by Shawn McKenzie as a plug-in and was added to the default distribution in DITA OT, release 1.5.4.

The tocjs transformation was updated so that it produces XHTML output and uses a default frameset. This transformation also was added to the build_demo.xml script as a transformation-type option.

2.2.3.1.10: DITA to Troff

The troff transformation produces output for use with the Troff viewer on Unix-style platforms, particularly for programs such as the Man page viewer.

Each DITA topic generally produces one troff output file. The troff transformation supports most common DITA structures, but it does not support <table> or <simpletable> elements. Most testing of troff output was performed using the Cygwin Linux emulator.

2.2.3.1.11: DITA to XHTML

The xhtml transformation generates XHTML output and a table of contents (TOC) file. This was the first transformation created for the DITA Open Toolkit, and it is the basis for all the HTML-based transformations.

The XHTML output is always associated with the default DITA-OT CSS file (commonltr.css or commonrtl.css for right-to-left languages). You can use toolkit parameters to add a custom style sheets to override the default styles.

To run the XHTML transformation, set the transtype parameter to xhtml. If you are running the demo build, specify web rather than xhtml.

2.2.3.2: Publishing DITA content from Ant

You can use Ant to invoke the DITA Open Toolkit (DITA-OT) and generate output. This is the most robust method of transforming DITA content; you can use the complete set of parameters that are supported by the toolkit.

2.2.3.2.1: Ant

Ant is a Java-based, open-source tool that is provided by the Apache Foundation. It can be used to declare a sequence of build actions. It is well suited for both development and document builds. The full-easy-install version of the toolkit ships with a copy of Ant.

The DITA-OT uses Ant to manage the XSLT scripts that are used to perform the various transformation; it also uses Ant to manage intermediate steps that are written in Java.

The most important Ant script is the build.xml file. This script defines and combines common pre-processing and output transformation routines; it also defines the DITA-OT extension points.

2.2.3.2.2: Building output using Ant

You can build output by running the ant command and specifying the DITA-OT parameters at the command prompt. You also can use an Ant build script to provide the DITA-OT parameters

Run the startcmd file that is applicable for your operating system.
The startcmd.bat and startcmd.sh files are in the directory where you installed the DITA-OT.
To provide the DITA-OT parameters from the command prompt, issue the following command:
```
ant -Dargs.input=input-file -Dtranstype=transformation-type -Dparameter-name=value
```
where:
- input-file is the DITA map or DITA file that you want to process.
- transformation-type is the transformation type.
- parameter-name is the name of an optional parameter.
- value is an applicable value for the optional parameter.
If you do not specify an output directory, by default, the DITA-OT writes the output to the installation-directory\out directory.
If you use a build script, issue the following command:
```
ant -f build-script target
```
where:
- build-script is name of the Ant build script.
- target is an optional switch that specifies the name of the Ant target that you want to run. If you do not specify a target, the value of the @default attribute for the Ant project is used.

2.2.3.2.3: Creating an Ant build script

Instead of typing the DITA-OT parameters at the command prompt, you might want to create an Ant build script that contains all of the parameters.

Create an XML file that contains the following content:

<?xml version="1.0" encoding="UTF-8" ?>
<project name="@project-name@" default="@default-target@" basedir=".">

  <property name="dita.dir" location="@path-to-DITA-OT@"/>
 
  <target name="@target-name@">
    <ant antfile="${dita.dir}${file.separator}build.xml">
      <property name="args.input" value="@DITA-input@"/>
      <property name="transtype" value="xhtml"/>
    </ant>
  </target>

</project>

You will replace the placeholder content (indicated by the @ signs) with content applicable to your environment.

Specify project information:
1. Set the value of the @name attribute to X.
  What does X need to be? Does it really matter? I tend to set this attribute to the string that I use for the name of the Ant script.
2. Set the value of the @default attribute to the name of a target in the build script.
  If the build script is invoked without specifying a target, this target will be run.
Set the value of the dita.dir property to the location of the DITA-OT.
This can be a fully qualified path, or you can specify it relative to the location of the Ant build script that you are writing.
Create the Ant target:
1. Set the value of the @name attribute.
2. Specify the value for the args.input property.
3. Specify the value of the transtype property.
Save the build script.

The following Ant build script generates CHM and PDF output for the userguide.ditamap file.

<?xml version="1.0" encoding="UTF-8" ?>
<project name="Toolkit-documentation" default="all" basedir=".">
    
    <property name="dita.dir" location="C:\DITA-OT1.6.M5"/>
    
    <target name="all" description="build CHM and PDF" depends="chm,pdf"/>
    
    <target name="chm" description="build CHM">
        <ant antfile="${dita.dir}\build.xml">
            <property name="args.input" value="C:\dita-ot\src\main\doc\userguide.ditamap"/>
            <property name="args.gen.task.lbl" value="YES"/>   
            <property name="output.dir" value="C:\kje\temp\out"/>
            <property name="transtype" value="htmlhelp"/>
        </ant>
    </target>
    
    <target name="pdf" description="build PDF">
        <ant antfile="${dita.dir}\build.xml">
            <property name="args.input" value="C:\dita-ot\src\main\doc\userguide.ditamap"/>
            <property name="args.gen.task.lbl" value="YES"/>   
            <property name="args.rellinks" value="nofamily"/>   
            <property name="output.dir" value="C:\kje\temp\out"/>
            <property name="transtype" value="pdf"/>
        </ant>
    </target>
    
</project>

In addition to the mandatory parameters (args.input and transtype), the chm and pdf targets each specify some optional parameters:

The args.gen.task.lbl property is set to YES, which ensures that headings are automatically generated for the sections of task topics.
The output.dir property specifies where the DITA OT writes the output of the transformations.

The pdf target also specifies that related links should be generated in the PDF, but only those links that are created by relationship tables and <link> elements.

Finally, the all target simply specifies that both the chm and pdf target should be run.

Another resource for learning about Ant scripts are the files in the samples/ant_samples directory. This directory contains the Ant build files used by the demo build, as well as templates that you can use to create Ant scripts.

2.2.3.3: Publishing DITA content from the command-line tool

The DITA Open Toolkit (DITA-OT) includes a command-line tool designed for users who are unfamiliar with Ant. You can invoke the DITA-OT from the command-line tool and generate output. This method is less robust than Ant.

2.2.3.3.1: Command-line tool

The DITA Open Toolkit (DITA-OT) provides a command-line tool for users with little knowledge of Ant. The command-line tool supports a subset of the parameters that are available to the Ant builds.

The command-line tool is a wrapper around the Ant interface; it takes the simplified parameters as input, converts them to Ant parameters, and then runs an Ant build. The Ant parameters that are passed to the DITA-OT are saved to the property.temp file that is written to the output directory.

For individual builds, the additional Java overhead is minimal, but for repeated or server-based builds, the extra memory usage might become an issue. Applications that embed the toolkit should invoke Ant directly.

2.2.3.3.2: Building output using the command-line tool

If you are unfamiliar with Ant, you can invoke the DITA Open Toolkit (DITA-OT) and build output from the command-line tool.

Run the startcmd file that is applicable for your operating system.
The startcmd.bat and startcmd.sh files are in the directory where you installed the DITA-OT.
From the command prompt, issue the following command:
```
    java -jar lib/dost.jar /i:input-file /transtype:transformation-type /parameter-name:value
```
where:
- input-file is the DITA map or DITA file that you want to process.
- transformation-type is the transformation type.
- parameter-name is the name of an optional parameter.
- value is an applicable value for the optional parameter.
If you do not specify an output directory, by default, the DITA-OT writes the output to the installation-directory\out directory.

The following command generates XHTML output for the sequence.ditamap file and specifies the output is written to the test directory

java -jar lib/dost.jar /i:samples/sequence.ditamap /outdir:test /transtype:xhtml

2.2.4: Globalizing DITA content

The DITA standard supports content that is written in or translated to any language. In general, the DITA Open Toolkit (DITA-OT) passes content through to the output format unchanged. The DITA-OT uses the values for the @xml:lang, @translate, and @dir attributes that are set in the source content to provides globalization support.

2.2.4.1: Globalization support offered by the DITA-OT

The DITA Open Toolkit (DITA-OT) offers globalization support in the following areas: Generated text, index sorting, and bi-directional text.

Generated text

Generated text is text that is rendered automatically in the output that is generated by the DITA-OT; this text is not located in the DITA source files. The following are examples of generated text:

The word "Chapter in a PDF file.
The phrases "Related concepts," "Related tasks," and "Related reference" in XHTML output.

Index sorting

The DITA-OT can use only a single language to sort indexes.

What does the ICU for Java provide? Does index sorting occur if ICU for Java is NOT installed?

Bi-directional text

The DITA-OT contains style sheets (CSS files) that support both left-to-right (LTR) and right-to-left (RTL) languages.

What support is offered by the legacypdf and pdf2 transformations?

When the DITA-OT generates output, it takes the first value for the @xml:lang attribute that it encounters, and then it uses that value to create generated text, perform index sorting, and determine which default CSS file is used. If no value for the @xml:lang attribute is found, the toolkit defaults to US English.

Does the DITA-OT also use the values for the @dir attribute?

2.2.4.2: Supported languages: HTML-based transformations

The DITA Open Toolkit (DITA-OT) supports over 50 languages and language variants for the HTML- and XHTML-based transformations, for example, Eclipse Help, HTML Help, and TocJS.

Supported languages: HTML- and XHTML-based transformations

Language	Language code
Arabic	ar or ar-eg
Belarusian	be or be-by
Brazilian Portuguese	pt-br
Bulgarian	bg or bg-bg
Catalan	ca-es
Chinese (simplified)	zh-cn or zh-hans
Chinese (traditional)	zh-tw or zh-hant
Croatian	hr or hr-hr
Czech	cs or cs-cz
Danish	da or da-dk
Dutch	nl or nl-nl
Dutch (Belgian)	nl-be
English (US)	en or en-us
English (British)	en-gb
English (Canadian)	en-ca
Estonian	et or et-ee
Finnish	fi or fi-fi
French	fr or fr-fr
French (Belgian)	fr-be
French (Canadian)	fr-ca
French (Swiss)	fr-ch
German	de or de-de
German (Swiss)	de-ch
Greek	el or el-gr
Hebrew	he or he-il
Hindi	hi or hi-hi
Hungarian	hu or hu-hu
Icelandic	is or is-is
Indonesian	id or id-id
Italian	it or it-it
Italian(Swiss)	it-ch
Japanese	ja or ja-jp
Kazakh	kk or kk-kz
Korean	ko or ko-kr
Latvian	lv or lv-lv
Lithuanian	lt or lt-lt
Macedonian	mk or mk-mk
Malay	ms or ms-my
Norwegian	no or no-no
Polish	pl or pl-pl
Portuguese	pt or pt-pt
Romanian	ro or ro-ro
Russian	ru or ru-ru
Serbian (Cyrillic script)	sr, sr-rs, or sr-sp
Serbian (Latin script)	sr-latn-rs
Slovak	sk or sk-sk
Slovenian	sl or sl-si
Spanish	es or es-es
Spanish (Latin American)	es-419
Swedish	sv or sv-se
Thai	th or th-th
Turkish	tr or tr-tr
Ukrainian	uk or uk-ua
Urdu	ur or ur-pk

2.2.4.3: Supported languages: PDF transformations

The DITA Open Toolkit (DITA-OT) supports a smaller set of languages for the PDF (pdf2) transformation. This transformation was donated to the DITA-OT project after the project inception, and it uses a different and larger set of generated text than the HTML-based transformations.

I've added the language codes for the languages; they were not included in the original DITA-OT doc.

Are these languages supported only for the PDF2 transformation, or are they also supported for the Legacy PDF transformation?
Can someone confirm that the PDF2 transformation actually supports these language codes?

Supported languages: PDF transformation

Language	Language code
Chinese (simplified)	zh-cn or zh-hans
Dutch	nl or nl-nl
English (US)	en or en-us
Finnish	fi or fi-fi
French	fr or fr-fr
German	de or de-de
Hebrew	he or he-il
Italian	it or it-it
Japanese	ja or ja-jp
Romanian	ro or ro-ro
Russian	ru or ru-ru
Slovenian	sl or sl-SI
Spanish	es or es-es
Swedish	sv or sv-se

2.2.5: Error messages and troubleshooting

This section contains information about problems that you might encounter and how to resolve them.

2.2.5.1: Error messages

This topic defines all error messages generated by the DITA-OT.

Plug-ins may be used to add additional error messages into the toolkit; for more information, see the Developer reference section of the User Guide.

Message ID	Severity	Message text
DOTA001F	Fatal	"%1" is not a recognized transformation type. Supported transformation types are docbook, eclipsecontent, eclipsehelp, htmlhelp, javahelp, net.sourceforge.dita-ot.html, odt, pdf, pdf2, tocjs, troff, wordrtf, xhtml.
DOTA002F	Fatal	Input file is not specified, or is specified using the wrong parameter.
DOTA003F	Fatal	Cannot find the user specified XSLT stylesheet '%1'.
DOTA004F	Fatal	Invalid DITA topic extension '%1'. Supported values are '.dita' and '.xml'.
DOTA006W	Warning	Absolute paths on the local file system are not supported for the CSSPATH parameter. Please use a relative path or full URI instead.
DOTA007E	Error	Cannot find the running-footer file "%1". Please double check the value to ensure it is specified correctly.
DOTA008E	Error	Cannot find the running-header file "%1". Please double check the value to ensure it is specified correctly.
DOTA009E	Error	Cannot find the specified heading file "%1". Please double check the value to ensure it is specified correctly.
DOTA010E	Error	The Apache FOP program cannot be found in the default location. Please place FOP into the default directory demo/fo/fop/ or update the build file to support your local configuration.
DOTA011W	Warning	Argument "%1" is deprecated. This argument is no longer supported in the toolkit.
DOTA012W	Warning	Argument "%1" is deprecated. Please use the argument "%2" instead.
DOTA066F	Fatal	Cannot find the user specified XSLT stylesheet '%1'.
DOTA067W	Warning	Ignoring index-see '%1' inside parent index entry '%2' because the parent indexterm contains indexterm children. According to the DITA Specification, the index-see element should be ignored if the parent indexterm contains other indexterm children.
DOTA068W	Warning	Ignoring index-see-also '%1' inside parent index entry '%2' because the parent indexterm contains indexterm children. According to the DITA Specification, the index-see-also element should be ignored if the parent indexterm contains other indexterm children.
DOTA069F	Fatal	Input file '%1' cannot be located or read. Ensure that file was specified properly and that you have permission to access it.
DOTA069W	Warning	Target "%1" is deprecated. Remove references to this target from your custom XSLT or plug-ins.
DOTJ001F	Fatal	Invalid command line syntax for the parameter '%1'. Parameters to the command line tool should use the syntax /parameter:value.
DOTJ002F	Fatal	Unsupported parameter '%1'. Please refer to the DITA-OT User Guide for supported parameters.
DOTJ003F	Fatal	Parameter '%1' was specified without a value. Parameters to the command line tool should use the syntax /parameter:value.
DOTJ004F	Fatal	Cannot create temporary processing directory '%1'. Please ensure that you have permission to create the directory '%1'.
DOTJ005F	Fatal	Failed to create new instance for '%1'. Please ensure that '%1' exists and that you have permission to access it.
DOTJ006F	Fatal	An Ant build file used the following illegal syntax when calling AntInvoker: extparam='%1'. Please correct the call to AntInvoker when directly calling DITA-OT Java code from Ant; for example, extparam="maplinks=XXXX;other=YYYY".
DOTJ007E	Error	Duplicate condition in filter file for rule '%1'. The first encountered condition will be used.
DOTJ009E	Error	Cannot overwrite file '%1' with file '%2'. The modified result may not be consumed by the following steps in the transform pipeline. Check to see whether the file is locked by some other application during the transformation process.
DOTJ012F	Fatal	Failed to parse the input file '%1'. The XML parser reported the following error:
DOTJ013E	Error	Failed to parse the referenced file '%1'. The XML parser reported the following error:
DOTJ014W	Warning	Found an indexterm element with no content. Setting the term to ***.
DOTJ015F	Fatal	Log directory cannot be null. Please specify a valid directory for the build log.
DOTJ016F	Fatal	Failed to create log directory '%1'. Please specify a valid directory for the build log.
DOTJ017F	Fatal	No input file was specified; failed to initialize log name based on input file.
DOTJ018I	Informational	Log file '%1' was generated successfully in directory '%2'. Any messages from the transformation process are available in the log file; additional details about each message are available in the DITA-OT user guide.
DOTJ020W	Warning	At least one plug-in in '%1' is required by plug-in '%2'. Plug-in '%2' cannot be loaded. Check and see whether all prerequisite plug-ins are installed in toolkit.
DOTJ021W	Warning	File '%1' will not generate output since it is invalid or all of its content has been filtered out by the ditaval file. Please check the file '%1' and the ditaval file to see if this is the intended result.
DOTJ022F	Fatal	Failed to parse the input file '%1' because all of its content has been filtered out. This will happen if the input file has filter conditions on the root element, and a ditaval excludes all content based on those conditions.
DOTJ023E	Error	Failed to get the specified image file '%1', so it will not be included with your output.
DOTJ025E	Error	The input to the "topic merge" transform process could not be found. Correct any earlier transform errors and try the build again, or see the DITA-OT User Guide for additional causes.
DOTJ026E	Error	The "topic merge" did not generate any output. Correct any earlier transform errors and try the build again, or see the DITA-OT User Guide for additional causes.
DOTJ028E	Error	No format attribute was found on a reference to file '%1', which does not appear to be a DITA file. If this is not a DITA file, set the format attribute to an appropriate value, otherwise set the format attribute to "dita".
DOTJ029I	Informational	No 'domains' attribute was found for element '<%1>'. This generally indicates that your DTD or Schema was not developed properly according to the DITA specification.
DOTJ030I	Informational	No 'class' attribute for was found for element '<%1>'. This generally indicates that your DTD or Schema was not developed properly according to the DITA specification.
DOTJ031I	Informational	No specified rule for '%1' was found in the ditaval file. This value will use the default action, or a parent prop action if specified. To remove this message, you can specify a rule for '%1' in the ditaval file.
DOTJ033E	Error	No valid content is found in topicref '%1' during chunk processing. Please specify an existing and valid topic for the topicref.
DOTJ034F	Fatal	Failed to parse the input file '%1' (the content of the file is not valid). If the input file '%1' does not have a DOCTYPE declaration, please make sure that all class attributes are present in the file.
DOTJ035F	Fatal	The file "%1" referenced by "%2" is outside the scope of the input dita/map directory. If you want to lower the severity level, please use the Ant parameter 'outer.control', and set the value to "warn" or "quiet". Otherwise, move the referenced file "%1" into the input dita/map directory.
DOTJ036W	Warning	The file "%1" referenced by "%2" is outside the scope of the input dita/map directory. If you do not want to see the warning message, please use the Ant parameter 'outer.control', and set the value to "quiet". Otherwise, move the referenced file "%1" into the input dita/map directory.
DOTJ037W	Warning	The XML schema and DTD validation function of the parser is turned off. Please make sure the input is normalized DITA with class attributes included, otherwise it will not be processed correctly.
DOTJ038E	Error	The tag "%1" is specialized from unrecognized metadata. Please make sure that tag "%1" is specialized from an existing metadata tag in the core DITA vocabulary.
DOTJ039E	Error	There is no target specified for conref push action "pushafter". Found in file="%1", element="%2". Please add <elementname conref="pushtarget" conaction="mark"> before current element.
DOTJ040E	Error	An element uses the attribute conaction="replace", but a conref attribute is not found in the expected location. Found in file="%1", element="%2".
DOTJ041E	Error	The attribute conref="%1" uses invalid syntax. The value should contain '#' followed by a topic or map ID, optionally followed by '/elemID' for a sub-topic element.
DOTJ042E	Error	Two elements both use conref push to replace the target "%1". Please delete one of the duplicate "replace" actions.
DOTJ043W	Warning	The conref push function is trying to replace an element that does not exist (element "%1" in file "%2").
DOTJ044W	Warning	There is a redundant conref action "pushbefore". Found in file="%1", element="%2". Please make sure that "mark" and "pushbefore" occur in pairs.
DOTJ045I	Informational	The key "%1" is defined more than once in the same map file. The reference href="%2" is ignored.
DOTJ046E	Error	Conkeyref="%1" can not be resolved because it does not contain a key or the key is not defined. The build will use the conref attribute for fallback, if one exists.
DOTJ047I	Informational	Unable to find key definition for keyref="%1", href may be used as fallback if it exists.
DOTJ049W	Warning	The attribute value %1="%3" on element "%2" does not comply with the specified subject scheme. According to the subject scheme map, the following values are valid for the %1 attribute: %4
DOTJ050W	Warning	Found an <index-see> or <index-see-also> reference to the term '%1', but that term is not defined in the index.
DOTJ051E	Error	Unable to load target for coderef "%1".
DOTJ052E	Error	Code reference charset "%1" not supported. See the DITA-OT User guide for supported charset values on the format attribute.
DOTJ053W	Warning	Input file '%1' is not valid DITA file name. Please check '%1' to see if it is correct. The extensions ".dita" or ".xml" are supported for DITA topics.
DOTJ054E	Error	Unable to parse invalid %1 attribute value "%2"
DOTJ055E	Error	Invalid key name "%1".
DOTJ056E	Error	Invalid xml:lang "%1".
DOTJ057E	Error	The id attribute value "%1" is not unique within the topic that contains it.
DOTX001W	Warning	No string named '%1' was found for language '%2'. Using the default language '%3'. Add a mapping between default language and desired language for the string '%1'.
DOTX002W	Warning	The title element or attribute in the ditamap is required for Eclipse output.
DOTX003I	Informational	The anchorref attribute should either reference another dita map or an Eclipse XML TOC file. The value '%1' does not appear to reference either.
DOTX004I	Informational	Found a navref element that does not reference anything. The navref element should either reference another dita map or an Eclipse XML file.
DOTX005E	Error	Unable to find navigation title for reference to '%1'. The build will use '%1' as the title in the Eclipse Table of Contents.
DOTX006E	Error	Unknown file extension in href="%1". References to non-DITA resources should set the format attribute to match the resource (for example, 'txt', 'pdf', or 'html').
DOTX007I	Informational	Only DITA topics, HTML files, and images may be included in your compiled CHM file. The reference to "%1" will be ignored. To remove this message, you can set the toc="no" or processing-role="resource-only" attribute on your topicref.
DOTX008E	Error	File '%1' does not exist or cannot be loaded.
DOTX008W	Warning	File '%1' cannot be loaded, and no navigation title is specified for the table of contents.
DOTX009W	Warning	Could not retrieve a title from '%1'. Using '%2' instead.
DOTX010E	Error	Unable to find target for conref="%1".
DOTX011W	Warning	There is more than one possible target for the reference conref="%1". Only the first will be used. Remove the duplicate id in the referenced file.
DOTX012W	Warning	When you conref another topic or an item in another topic, the domains attribute of the target topic must be equal to or a subset of the current topic's domains attribute. Put your target under an appropriate domain. You can see the messages guide for more help.
DOTX013E	Error	A element with attribute conref="%1" indirectly includes itself, which results in an infinite loop.
DOTX014E	Error	The attribute conref="%1" uses invalid syntax. Conref references to a map element should contain '#' followed by an ID, such as mymap.ditamap#mytopicrefid.
DOTX015E	Error	The attribute conref="%1" uses invalid syntax. The value should contain '#' followed by a topic or map ID, optionally followed by '/elemID' for a sub-topic element.
DOTX016W	Warning	A reference to "%2" appears to reference a DITA document, but the format attribute has inherited a value of "%1". The document will not be processed as DITA.
DOTX017E	Error	Found a link or cross reference with an empty href attribute (href=""). Remove the empty href attribute or provide a value.
DOTX018I	Informational	The type attribute on a topicref was set to '%1', but the topicref references a more specific '%2' topic. Note that the type attribute cascades in maps, so the value '%1' may come from an ancestor topicref.
DOTX019W	Warning	The type attribute on a topicref was set to '%1', but the topicref references a '%2' topic. This may cause your links to sort incorrectly in the output. Note that the type attribute cascades in maps, so the value '%1' may come from an ancestor topicref.
DOTX020E	Error	Missing navtitle attribute or element for peer topic "%1". References must provide a local navigation title when the target is not a local DITA resource.
DOTX021E	Error	Missing navtitle attribute or element for non-DITA resource "%1". References must provide a local navigation title when the target is not a local DITA resource.
DOTX022W	Warning	Unable to retrieve navtitle from target: '%1'. Using linktext (specified in topicmeta) as the navigation title.
DOTX023W	Warning	Unable to retrieve navtitle from target: '%1'.
DOTX024E	Error	Missing linktext and navtitle for peer topic "%1". References must provide a local navigation title when the target is not a local DITA resource.
DOTX025E	Error	Missing linktext and navtitle for non-DITA resource "%1". References must provide a local navigation title when the target is not a local DITA resource.
DOTX026W	Warning	Unable to retrieve linktext from target: '%1'. Using navigation title as fallback.
DOTX027W	Warning	Unable to retrieve linktext from target: '%1'.
DOTX028E	Error	Link or cross reference must contain a valid href or keyref attribute; no link target is specified.
DOTX029I	Informational	The type attribute on a %1 element was set to %3, but the reference is to a more specific %4 %2. This may cause your links to sort incorrectly in the output.
DOTX030W	Warning	The type attribute on a %1 element was set to %3, but the reference is to a %4 %2. This may cause your links to sort incorrectly in the output.
DOTX031E	Error	The file %1 is not available to resolve link information.
DOTX032E	Error	Unable to retrieve link text from target: '%1'. If the target is not accessible at build time, or does not have a title, provide the link text inside the reference.
DOTX033E	Error	Unable to generate link text for a cross reference to a list item: '%1'
DOTX034E	Error	Unable to generate link text for a cross reference to an undered list item: '%1'
DOTX035E	Error	Unable to generate the correct number for a cross reference to a footnote: '%1'
DOTX036E	Error	Unable to generate link text for a cross reference to a dlentry (the dlentry or term could not be found): '%1'
DOTX037W	Warning	No title found for this document; using "***" in XHTML title bar.
DOTX038I	Informational	The longdescref attribute on tag '%1' will be ignored. Accessibility for object elements needs to be handled another way.
DOTX039W	Warning	Required cleanup area found. To remove this message and hide the content, build your content without using the DRAFT parameter.
DOTX040I	Informational	Draft comment area found. To remove this message and hide the comments, build your content without using the DRAFT parameter.
DOTX041W	Warning	Found more than one title element in a section. Using the first one for the section's title.
DOTX042I	Informational	DITAVAL based flagging is not currently supported for inline phrases in XHTML; ignoring flag value on '%1' attribute.
DOTX043I	Informational	The link to '%1' may appear more than once in '%2'.
DOTX044E	Error	The area element in an image map does not specify a link target. Please add an xref element with a link target to the area element.
DOTX045W	Warning	The area element in an image map should specify link text for greater accessibility. Link text should be specified directly when the target is not a local DITA resource.
DOTX046W	Warning	Area shape should be: default, rect, circle, poly, or blank (no value). The value '%1' is not recognized.
DOTX047W	Warning	Area coordinates are blank. Coordinate points for the shape need to be specified.
DOTX048I	Informational	In order to include peer or external topic '%1' in your help file, you may need to recompile the CHM file after making the file available.
DOTX049I	Informational	References to non-dita files will be ignored by the PDF, ODT, and RTF output transforms.
DOTX050W	Warning	Default id "org.sample.help.doc" is used for Eclipse plug-in. If you want to use your own plug-in id, please specify it using the id attribute on your map.
DOTX052W	Warning	No string named '%1' was found when creating generated text; using the value '%1' in your output file.
DOTX053E	Error	A element that references another map indirectly includes itself, which results in an infinite loop. The original map reference is to '%1'.
DOTX054W	Warning	Conflict text style is applied on the current element based on DITAVAL flagging rules. Please check ditaval and dita source to make sure there is no style conflict on the element which needs to be flagged.
DOTX055W	Warning	Customized stylesheet uses deprecated template "flagit". Conditional processing is no longer supported using this template. Please update your stylesheet to use template "start-flagit" instead of deprecated template "flagit".
DOTX056W	Warning	The file '%1' is not available to resolve link information.
DOTX057W	Warning	The link or cross reference target '%1' cannot be found, which may cause errors creating links or cross references in your output file.
DOTX058W	Warning	No glossary entry was found associated with key '%1' on %2 element. The build will try to determine the best display text and hover text for terms and abbreviations.
DOTX060W	Warning	Key '%1' was used in an abbreviated-form element, but the key is not associated with a glossary entry. Abbreviated-form should ONLY be used to reference to a glossary entry.
DOTX061W	Warning	ID '%1' was used in topicref tag but did not reference a topic element. The href attribute on a topicref element should only reference topic level elements.
DOTX062I	Informational	It appears that this document uses constraints, but the conref processor cannot validate that the target of a conref is valid. To enable constraint checking, please upgrade to an XSLT 2.0 processor.
DOTX063W	Warning	The dita document '%1' is linked to from your content, but is not referenced by a topicref tag in the ditamap file. Include the topic in your map to avoid a broken link.
DOTX064W	Warning	The copy-to attribute [copy-to="%1"] uses the name of a file that already exists, so this attribute is ignored.
DOTX065W	Warning	Two unique source files each specify copy-to="%2", which results in a collision. The value associated with href="%1" is ignored.
DOTX066W	Warning	Template "%1" is deprecated. Remove references to this template from your custom XSLT or plug-ins.
DOTX067E	Error	No string named '%1' was found for language '%2'. Add a mapping for the string '%1'.
DOTX068W	Warning	A topicref element that references a map contains child topicref elements. Child topicref elements are ignored.
PDFJ001E	Error	Index entry '%1' is dropped, because corresponding group is not found.
PDFJ002E	Error	Build stopped. Problems occured during Index preprocess task. Please check the messages above.
PDFX001W	Warning	There is no index entry found which closing range for ID="%1".
PDFX002W	Warning	There are multiple index entry found which is opening range for ID="%1" but there is only one which close it or ranges are overlapping.
PDFX003W	Warning	There are multiple index entry found which closing range for ID="%1".
PDFX004F	Fatal	Empty href was specified for some topic reference. Please correct your ditamap or bookmap file.
PDFX005F	Fatal	Topic reference (href : %1) not found. Reference may be incorrect. Please correct your ditamap or bookmap file.
PDFX006E	Error	Number of columns must be specified.
PDFX007W	Warning	There is no index entry found which opening range for ID="%1".
PDFX008W	Warning	Font definition not found for the logical name or alias '%1'.
PDFX009E	Error	Attribute set reflection can't handle XSLT element %1.
PDFX010W	Warning	Index generation is not supported in FOP.
PDFX011E	Error	Both index-see and %1 defined for index entry '%2'. Recovering by treating the index-see as an index-see-also.

2.2.5.2: Other error messages

In addition to error messages generated by the DITA Open Toolkit, you might also encounter error messages generated by Java or other tools.

Out of Memory error

In some cases, you might receive a message stating the build has failed due to an Out of Memory error. Try the following approaches to resolve the problem:

(For custom-configured environments, not the DITA-OT Full Easy Install) If you use Xalan as the default XSLT processor, switch to Saxon.
Increase the memory available to Java; see Increasing Java memory allocation.
Reduce memory consumption by setting the generate-debug-attributes option to false. This option is set in the lib/configuration.properties file. This will disable debug attribute generation (used to trace DITA-OT error messages back to source files) and will reduce memory consumption.
Set dita.preprocess.reloadstylesheet Ant property to true. This will allow the XSLT processor to release memory when converting multiple files.
Run the transformation again.

java.io.IOException: Can't store Document

After running a JavaHelp transformation, you may receive a java.io.IOException: Can't store Document message.

This problem occurs when HTML files unrelated to the current transformation are found in the output directory. Delete the content of the output directory and run the transformation again.

Stack Overflow error

If you receive an error about a stack memory overflow, increase the JVM and run the transformation again. See Increasing Java memory allocation.

2.2.5.3: Log files

When you run the DITA-OT, key information is logged on the screen. This information also is written to a log file. If you encounter a problem, you can analyze this information to determine the source of the problem and then take action to resolve it.

The logging behavior varies depending on whether you use the DITA-OT command-line tool or Ant to invoke a toolkit build.

Ant: By default, status information is written to the screen. If you issue the -l parameter, the build runs silently and the information is written to a log file with the name and location that you specified. (You also can use other Ant loggers; see the Ant documentation for more information.)
Command-line tool: Status information is written to the screen and the log file. The log file name contains the input file name and transformation type; by default, it is located in the output directory. If you issue the /logdir parameter, you can specify a different location for where the log file is written.

2.2.5.4: Accessing help from the command-line tool

You can access a list of supported parameters for the command-line tool by issuing the -help parameter.

Run the startcmd file that is applicable for your operating system.
The startcmd.bat and startcmd.sh files are in the directory where you installed the DITA-OT.
From the command prompt, issue the following command:
```
    java -jar lib/dost.jar -help    
```

You can see the brief description of the supported parameters in the command-line window.

2.2.5.5: Determing the version of the DITA Open Toolkit

You can use the command-line tool to determine the version of the DITA OT.

Run the startcmd file that is applicable for your operating system.
The startcmd.bat and startcmd.sh files are in the directory where you installed the DITA-OT.
From the command prompt, issue the following command:
```
java -jar lib/dost.jar -version
```

2.2.5.6: Enabling debug mode

When the debug mode is enabled, additional diagnostic information is written to the log file. This information, which includes environment variables and stack trace data, can help you determine the root cause of a problem.

From the command prompt, add the following parameters:

Application	Parameters
Ant	`-v -Dargs.debug=yes`
Command-line tool	`/d` or `-debug`

You also can add a <property> element to an Ant target in your build file, for example:

<property name="args.debug" value="yes"/>

2.2.5.7: Increasing Java memory allocation

If you are working with large documents with extensive metadata or key references, you will need to increase the memory allocation for the Java process. You can do this from the command-line prompt for a specific session, or you can increase the value of the ANT_OPTS environmental variable.

To change the value for an specific session, from the command prompt, issue the following command:

Platform	Command
Windows	`set ANT_OPTS=%ANT_OPTS% -Xmx1024M`
Linux/OS X	`export ANT_OPTS=$ANT_OPTS -Xmx1024M`

This increases the JVM memory allocation to 1024 megabytes. The amount of memory which can be allocated is limited by available system memory and the operating system.

To persistently change the value, change the value allocated to the ANT_OPTS environment variable on your system. If you use the startcmd file from the Full Easy Install to set up a toolkit session, edit that file to change the value.

2.2.6: Reference

This section is designed to help users to locate information easily and quickly. It includes documentation for the DITA Open Toolkit (DITA-OT) parameters and configuration properties.

2.2.6.1: Ant parameters

Certain parameters apply to all DITA-OT transformations. Other parameters are common to the HTML-based transformations. Finally, some parameters apply only to the specific transformation types.

2.2.6.1.1: Ant parameters: All transformations

Certain parameters apply to all transformations that are supported by the DITA Open Toolkit.

Ant parameters: All transformations

Parameters	Description
args.debug	Specifies whether debugging information is included in the log. The allowed values are yes and no; the default value is no.
args.draft	Specifies whether the content of <draft-comment> and <required-cleanup> elements is included in the output. The allowed values are yes and no; the default value is no. Corresponds to XSLT parameter DRAFT in most XSLT modules. Tip For PDF output, setting the args.draft parameter to yes causes the contents of the <titlealts> element to be rendered below the title.
args.figurelink.style	Specifies how cross references to figures are styled in output. The allowed values are NUMBER and TITLE. Specifying NUMBER results in "Figure 5"; specifying TITLE results in the title of the figure. Corresponds to the XSLT parameter FIGURELINK. Note This parameter is not available for the PDF transformation.
args.filter	Specifies a filter file to be used to include, exclude, or flag content. Filter files must have a .ditaval or .DITAVAL extension.
args.grammar.cache	Specifies whether the grammar-caching feature of the XML parser is used. The allowed values are yes and no; the default value is no. Note This option dramatically speeds up processing time. However, there is a known problem with using this feature for documents that use XML entities. If your build fails with parser errors about entity resolution, set this parameter to no.
args.input	Specifies the master file for your documentation project. Typically this is a DITA map, however it also can be a DITA topic if you want to transform a single DITA file. The path can be absolute, relative to args.input.dir, or relative to the directory where your project's ant build script resides if args.input.dir is not defined.
args.input.dir	Specifies the base directory for your documentation project. The default value is the parent directory of the file specified by args.input.
args.logdir	Specifies the location where the DITA-OT places log files for your project.
args.tablelink.style	Specifies how cross references to tables are styled. Specifying NUMBER results in "Table 5"; specifying TITLE results in the title of the table. Corresponds to the XSLT parameter TABLELINK. Note This parameter is not available for the PDF transformation.
clean.temp	Specifies whether the DITA-OT deletes the files in the temporary directory after it finishes a build. The allowed values are yes and no; the default value is yes.
dita.dir	Specifies where the DITA-OT is installed.
dita.ext	Specifies an extension to use for DITA topics; All DITA topics will use this single extension in the temp directory. The default value is .xml. Corresponds to XSLT parameter DITAEXT.
dita.extname	Specifies the file extension that the DITA-OT uses for files in the temporary directory. The allowed values are xml and dita; the default value is xml. Note This parameter is deprecated in favor of the dita.ext parameter.
dita.temp.dir	Specifies the location of the temporary directory. The temporary directory is where the DITA-OT writes temporary files that are generated during the transformation process.
dita.input.valfile	Specifies a filter file to be used to include, exclude, or flag content. Filter files must have a .ditaval or .DITAVAL extension. Notice Deprecated in favor of the args.filter parameter.
output.dir	Specifies the name and location of the output directory. By default, the output is written to `DITA-dir\out`.
transtype	Specifies the output format. You can create plug-ins to add new values for this parameter; by default, the following values are available: docbook eclipsehelp eclipsecontent htmlhelp javahelp legacypdf odt pdf rtf troff xhtml
validate	Specifies whether the DITA-OT validates the content. The allowed values are true and false; the default value is true.

2.2.6.1.2: Ant parameters: Common HTML-based transformations

Certain parameters apply to all the HTML-based transformation types: Eclipse content, Eclipse help, HTML Help, JavaHelp, TocJS, and XHTML.

Ant parameters: HTML-based transformations

Parameters	Description
args.artlbl	Specifies whether to generate a label for each image; the label will contain the image file name. The allowed values are yes and no; the default value is no.
args.breadcrumbs	Specifies whether to generate breadcrumb links. The allowed values are yes and no; the default value is no. Corresponds to the XSLT parameter BREADCRUMBS.
args.copycss	Specifies whether to copy the custom .css file to the output directory.
args.css	Specifies the name of a custom .css file.
args.csspath	Specifies the location of a copied .css file relative to the output directory. Corresponds to XSLT parameter CSSPATH.
args.cssroot	Specifies the directory that contains the custom .css file. DITA-OT will copy the file from this location.
args.dita.locale	Specifies the language locale file to use for sorting index entries. Note This parameter is not available for the XHTML transformation.
args.ftr	Specifies an XML file that contains content for a running footer. Corresponds to XSLT parameter FTR. Note The XML file must contain valid XML. A common practice is to place all content into a <div> element.
args.gen.default.meta	Specifies whether to generate extra metadata that targets parental control scanners, meta elements with name="security" and name="Robots". The allowed values are yes and no; the default value is no. Corresponds to the XSLT parameter genDefMeta.
args.gen.task.lbl	Specifies whether to generate headings for sections within task topics. The allowed values are YES and NO; the default value is NO. Corresponds to the XSLT parameter GENERATE-TASK-LABELS.
args.hdf	Specifies an XML file that contains content to be placed in the document head.
args.hdr	Specifies an XML file that contains content for a running header. Corresponds to the XSLT parameter HDR. Note The XML file must contain valid XML. A common practice is to place all content into a <div> element.
args.hide.parent.link	Specifies whether to hide links to parent topics in the HTML or XHTML output. The allowed values are yes and no; the default value is no. Corresponds to the XSLT parameter NOPARENTLINK. Notice This parameter is deprecated in favor of the args.rellinks parameter.
args.rellinks	Specifies which links to include in the output. The following values are supported: none (default) – No links are included. all – All links are included. nofamily – Parent, child, next, and previous links are not included.
args.indexshow	Specifies whether the content of <indexterm> elements are rendered in the output. The allowed values are yes and no; the default value is no.
args.outext	Specifies the file extension for HTML or XHTML output. The default value is html. Corresponds to XSLT parameter OUTEXT.
args.xhtml.classattr	Specifies whether to include the DITA class ancestry inside the XHTML elements .For example, the <prereq> element (which is specialized from section) would generate `class="section prereq`. The allowed values are yes and no; the default value is yes. Corresponds to the XSLT parameter PRESERVE-DITA-CLASS. Note Beginning with DITA OT release 1.5.2, the default value is yes. For release 1.5 and 1.5.1, the default value was no.
args.xsl	Specifies a custom XSL file to be used instead of the default XSL transformation (`xsl\dita2xhtml.xsl`). The parameter must specify a fully qualified file name.
generate.copy.outer	Specifies whether to generate output files for content that is not located in or beneath the directory containing the DITA map file. The following values are supported: 1 (default) – Do not generate output for content that is located outside the DITA map directory.. 2 – Generate output for the content that is located outside the DITA map directory. 3 – Shift the output directory so that it contains all output for the publication. See generate.outer.copy parameter for more information.
onlytopic.in.map	Specifies whether files that are linked to, or referenced with a @conref attribute, generate output. If set to yes, only files that are referenced directly from the map will generate output.
outer.control	Specifies how the DITA OT handles content files that are located in or below the directory containing the master DITA map. The following values are supported: fail – Fail quickly if files are going to be generated or copied outside of the directory warn (default) – Complete the operation if files will be generated or copied outside of the directory, but log a warning quiet – Quietly finish with only those files; do not generate warnings or errors. The gen-list-without-flagging Ant task generates a harmless warning for content that is located outside the map directory; you can suppress these warnings by setting the property to quiet. Warning Microsoft HTML Help Compiler cannot produce HTML Help for documentation projects that use outer content. The content files must reside in or below the directory containing the master DITA map file, and the map file cannot specify ".." at the start of the @href attributes for <topicref> elements.

2.2.6.1.2.1: generate.outer.copy parameter

Elaboration on how the generate.outer.copy parameter functions.

Background

This is an issue in the following situations:

The DITA map is in a directory that is a peer to directories that contain referenced objects.
The DITA map is in a directory that is below the directories that contain the referenced objects.

Let's assume that the directory structure for the DITA content looks like the following:

maps
topics
images

The DITA map is in the maps directory, the topics are in the topics directory, and the images are in the images directory.

Setting the generate.outer.copy parameter to 1

Let's assume that you run the XHTML transformation and specify an output directory of C:\A-test. By default, The DITA-OT uses the generate.outer.copy parameter with a value of 1. Output is not built for the topics. You receive only the following output:

A-test
--- dita.list
--- dita.xml.properties
--- index.html
--- commonltr.css
--- commonrtl.css

The index.html file contains the navigation structure, but all the links are broken, since no XHTML files were built for the topics.

How do you fix this? By specifying a value of 2 or 3 for the generate.outer.copy parameter.

Setting the generate.outer.copy parameter to 2

Let's assume that you run the XHTML transformation again and specify the following parameters:

The generate.outer.copy parameter is set to 2.
The output.dir parameter is set to C:\A-test.

This is what your output looks like:

C:\A-test
--- dita.list
--- dita.xml.properties
--- index.html
--- commonltr.css
--- commonrtl.css
...
C:\images
...
C:\topics

The links in the output all work properly. However, depending on how many other directories are located at the same level of your build system as the output directory, it might not be easy gather all the output together if you need to copy it elsewhere.

Setting the generate.outer.copy parameter to 3

Now your output directory structure looks like this:

C:\A-test
--- images\
--- maps\
--- topics\

The index.html file is in the maps directory, and the CSS and other files are located in the output directory, C:\A-test. Copying the output directory is simplified.

2.2.6.1.3: Ant parameters: Eclipse content transformation

Certain parameters are specific to the Eclipse content transformation.

Ant parameters: Eclipse content transformation

Parameters	Description
args.eclipsecontent.toc	Specifies the name of the TOC file

2.2.6.1.4: Ant parameters: Eclipse help transformation

Certain parameters are specific to the Eclipse help transformation.

Ant parameters: Eclipse help transformation

Parameters	Description
args.eclipsehelp.toc	Specifies the name of the TOC file.
args.eclipse.country	Specifies the region for the language that is specified by the args.eclipse.language parameter. For example, us, ca, and gb would clarify a value of en set for the args.eclipse.language parameter. The content will be moved into the appropriate directory structure for an Eclipse fragment. What does "The content will be moved into the appropriate directory structure for an Eclipse fragment" mean?
args.eclipse.language	Specifies the base language for translated content, such as en for English. This parameter is a prerequisite for the args.eclipse.country parameter. The content will be moved into the appropriate directory structure for an Eclipse fragment.
args.eclipse.provider	Specifies the name of the person or organization that provides the Eclipse help. The default value is DITA. Tip The toolkit ignores the value of this parameter when it processes an Eclipse map.
args.eclipse.version	Specifies the version number to include in the output. The default value is 0.0.0. Tip The toolkit ignores the value of this parameter when it processes an Eclipse map.
args.eclipse.symbolic.name	Specifies the symbolic name (aka plugin ID) in the output for an Eclipse Help project. The @id value from the DITA map or the Eclipse map collection (Eclipse help specialization) is the symbolic name for the plugin in Eclipse. The default value is org.sample.help.doc. Tip The toolkit ignores the value of this parameter when it processes an Eclipse map. I'm not clear what this means. Is the default value for the args.eclipse.symbolic.name parameter the value of the @id attribute on the <map> or <plugin> element, if provided, and the org.sample.help.doc if there is not a value for the @id attribute or the args.eclipse.symbolic.name parameter?

2.2.6.1.5: Ant parameters: HTML Help transformation

Certain parameters are specific to the HTML Help transformation.

Ant parameters: HTML Help transformation

Parameters	Description
args.htmlhelp.includefile	Specifies the name of a file that you want included in the HTML Help.

2.2.6.1.6: Ant parameters: JavaHelp transformation

Certain parameters are specific to the JavaHelp transformation.

Ant parameters: JavaHelp transformation

Parameters	Description
args.javahelp.map	Specifies the name of the ditamap file for a JavaHelp project. What does this mean? How does this differ from the args.input parameter? Or should this read "Specifies the name of the JavaHelp map file?
args.javahelp.toc	Specifies the name of the file containing the TOC in your JavaHelp output. Default value is the name of the ditamap file for your project I assume that the first sentence means "Specifies the name of the JavaHelp TOC file." But what does the second sentence mean? That the default value for the args.javahelp.toc parameter is the name of the master DITA map? Or that the default value for the args.javahelp.toc parameter is the value of the args.javahelp.map parameter? .

Parameters

Description

args.javahelp.map

Specifies the name of the ditamap file for a JavaHelp project.

What does this mean? How does this differ from the args.input parameter? Or should this read "Specifies the name of the JavaHelp map file?

args.javahelp.toc

Specifies the name of the file containing the TOC in your JavaHelp output. Default value is the name of the ditamap file for your project

I assume that the first sentence means "Specifies the name of the JavaHelp TOC file." But what does the second sentence mean? That the default value for the args.javahelp.toc parameter is the name of the master DITA map? Or that the default value for the args.javahelp.toc parameter is the value of the args.javahelp.map parameter?

2.2.6.1.7: Ant parameters: Legacy PDF transformation

Certain parameters are specific to the legacy PDF transformation.

Ant parameters: Legacy PDF transformation

Parameters	Description
args.fo.output.rel.links	Specifies whether to render related links in the output. The allowed values are yes and no; the default value is no. If the args.fo.include.rellinks parameter is specified, this parameter is ignored.
args.fo.userconfig	Specifies the user configuration file for FOP.

2.2.6.1.8: Ant parameters: ODT transformation

Certain parameters are specific to the ODT transformation.

Ant parameters: ODT transformation

Parameters	Description
args.odt.img.embed	Determines whether images are embedded as binary objects within the ODT file.

2.2.6.1.9: Ant parameters: Other

I've made no attempt to work with the content in the topic. Here's what I'd like to know:

When would someone want to use the various dita.preprocess parameters? (Other than if they need to reduce Java memory consumption.) The use cases are not clear from the current description.

Ant parameters: Other

Parameter	Description
dita.preprocess.reloadstylesheet	Specifies whether the DITA-OT reloads the XSL style sheets that are used for the transformation. The allowed values are true and false; the default value is false. Tip Set the parameter to true if you want to use more than one set of style sheets to process a collection of topics. The parameter also is useful for large projects that generate Java out-of-memory errors during transformation. Alternatively, you can adjust the size of your Java memory heap if setting `dita.preprocess.reloadstylesheet` for this reason.
dita.preprocess.reloadstylesheet.conref
dita.preprocess.reloadstylesheet.mapref
dita.preprocess.reloadstylesheet.mappull
dita.preprocess.reloadstylesheet.maplink
dita.preprocess.reloadstylesheet.topicpull

2.2.6.1.10: Ant parameters: PDF transformation

Certain parameters are specific to the PDF2 transformation.

Ant parameters: PDF transformation

Parameters	Description
args.bookmap-order	Specifies if the frontmatter and backmatter content order is retained in bookmap. The allowed values are retain and discard; the default value is discard.
args.fo.userconfig	Specifies the user configuration file for FOP.
args.gen.task.lbl	Specifies whether to generate headings for sections within task topics. The allowed values are YES and NO; the default value is NO. Corresponds to the XSLT parameter GENERATE-TASK-LABELS.
args.rellinks	Specifies which links to include in the output. The following values are supported: none (default) – No links are included. all – All links are included. nofamily – Parent, child, next, and previous links are not included.
args.xsl.pdf	Specifies an XSL file that is used to override the default XSL transformation (`plugins\org.dita.pdf2\xsl\fo\topic2fo_shell.xsl`). You must specify the fully qualified file name.
custom.xep.config	Specifies the user configuration file for RenderX.
customization.dir	Specifies the customization directory.
pdf.formatter	Specifies the XSL processor. The following values are supported: ah – Antenna House Formatter fop (default) – Apache FOP xep – RenderX XEP Engine The full-easy-install package comes with Apache FOP; other XSL processors must be separately installed.
publish.required.cleanup	Specifies whether draft-comment and required-cleanup elements are included in the output. The allowed values are yes and no; the default value is the value of the args.draft parameter. Corresponds to XSLT parameter publishRequiredCleanup. Notice This parameter is deprecated in favor of the args.draft parameter.
retain.topic.fo	Specifies whether to retain the generated FO file. The allowed values are yes and no; the default value is no. If the configuration property org.dita.pdf2.use-out-temp is set to false, this parameter is ignored.

2.2.6.1.11: Ant parameters: XHTML transformation

Certain parameters are specific to the XHTML transformation.

Ant parameters: XHTML transformation

Parameters	Description
args.xhtml.contenttarget	Specifies the value of the @target attribute on the <base> element in the TOC file. The default value is contentwin.
args.xhtml.toc	Specifies the base name of the TOC file. The default value is index.
args.xhtml.toc.class	Specifies the value of the @class attribute on the <body> element in the TOC file. Found in `map2htmltoc.xsl`.

2.2.6.2: Command-line tool parameters

Certain parameters apply to all DITA-OT transformations. Other parameters are common to the HTML-based transformations. Finally, some parameters apply only to the specific transformation types.

You must supply the parameters to the command-line tool using the following syntax:

/parameter:value

2.2.6.2.1: Command-line tool parameters: All transformations

Certain parameters apply to all transformations that are supported by the DITA Open Toolkit.

Command-line tool parameters: All transformations

Parameters	Description
basedir	The directory where your project's ant build script resides. The DITA-OT will look for your .dita files relative to this directory. DITA-OT's default build script sets this as an attribute of the project, but you can also define it as a project property.
cleantemp	Specifies whether the DITA-OT deletes the files in the temporary directory after it finishes a build. The allowed values are yes and no; the default value is yes.
debug	Specifies whether debugging information is included in the log. The allowed values are yes and no; the default value is no.
ditadir	Specifies where the DITA-OT is installed.
ditaext	Specifies the file extension that the DITA-OT uses for files in the temporary directory. The allowed values are xml and dita; the default value is xml. Note This parameter is deprecated in favor of the dita.ext parameter.
ditalocale	Specifies the language locale file to use for sorting index entries. Note This parameter is not available for the XHTML transformation.
draft	Specifies whether the content of <draft-comment> and <required-cleanup> elements is included in the output. The allowed values are yes and no; the default value is no. Corresponds to XSLT parameter DRAFT in most XSLT modules. Tip For PDF output, setting the args.draft parameter to yes causes the contents of the <titlealts> element to be rendered below the title.
filter	Specifies a filter file to be used to include, exclude, or flag content. Filter files must have a .ditaval or .DITAVAL extension. Notice Deprecated in favor of the args.filter parameter.
grammarcache	Specifies whether the grammar-caching feature of the XML parser is used. The allowed values are yes and no; the default value is no. Note This option dramatically speeds up processing time. However, there is a known problem with using this feature for documents that use XML entities. If your build fails with parser errors about entity resolution, set this parameter to no.
i	Specifies the master file for your documentation project. Typically this is a DITA map, however it also can be a DITA topic if you want to transform a single DITA file. The path can be absolute, relative to args.input.dir, or relative to the directory where your project's ant build script resides if args.input.dir is not defined.
logdir	Specifies the location where the DITA-OT places log files for your project.
outdir	Specifies the name and location of the output directory. By default, the output is written to `DITA-dir\out`.
outext	Specifies an extension to use for DITA topics; All DITA topics will use this single extension in the temp directory. The default value is .xml. Corresponds to XSLT parameter DITAEXT.
tempdir	Specifies the location of the temporary directory. The temporary directory is where the DITA-OT writes temporary files that are generated during the transformation process.
transtype	Specifies the output format. You can create plug-ins to add new values for this parameter; by default, the following values are available: docbook eclipsehelp eclipsecontent htmlhelp javahelp legacypdf odt pdf rtf troff xhtml
validate	Specifies whether the DITA-OT validates the content. The allowed values are true and false; the default value is true.

2.2.6.2.2: Command-line tool parameters: All HTML-based transformations

Certain parameters apply to all the HTML-based transformation types: Eclipse content, Eclipse help, HTML Help, JavaHelp, TocJS, and XHTML.

Note

You must specify an absolute path as the value for the following parameters:

Command-line tool parameters: All HTML-based transformations

Parameters	Description
args.css	Specifies the name of a custom .css file.
artlbl	Specifies whether to generate a label for each image; the label will contain the image file name. The allowed values are yes and no; the default value is no.
copycss	Specifies whether to copy the custom .css file to the output directory.
csspath	Specifies the location of a copied .css file relative to the output directory. Corresponds to XSLT parameter CSSPATH.
cssroot	Specifies the directory that contains the custom .css file. DITA-OT will copy the file from this location.
ftr	Specifies an XML file that contains content for a running footer. Corresponds to XSLT parameter FTR. Note The XML file must contain valid XML. A common practice is to place all content into a <div> element.
generateouter	Specifies whether to generate output files for content that is not located in or beneath the directory containing the DITA map file. The following values are supported: 1 (default) – Do not generate output for content that is located outside the DITA map directory.. 2 – Generate output for the content that is located outside the DITA map directory. 3 – Shift the output directory so that it contains all output for the publication. See generate.outer.copy parameter for more information.
hdf	Specifies an XML file that contains content to be placed in the document head.
hdr	Specifies an XML file that contains content for a running header. Corresponds to the XSLT parameter HDR. Note The XML file must contain valid XML. A common practice is to place all content into a <div> element.
indexshow	Specifies whether the content of <indexterm> elements are rendered in the output. The allowed values are yes and no; the default value is no.
onlytopicinmap	Specifies whether files that are linked to, or referenced with a @conref attribute, generate output. If set to yes, only files that are referenced directly from the map will generate output.
outercontrol	Specifies how the DITA OT handles content files that are located in or below the directory containing the master DITA map. The following values are supported: fail – Fail quickly if files are going to be generated or copied outside of the directory warn (default) – Complete the operation if files will be generated or copied outside of the directory, but log a warning quiet – Quietly finish with only those files; do not generate warnings or errors. The gen-list-without-flagging Ant task generates a harmless warning for content that is located outside the map directory; you can suppress these warnings by setting the property to quiet. Warning Microsoft HTML Help Compiler cannot produce HTML Help for documentation projects that use outer content. The content files must reside in or below the directory containing the master DITA map file, and the map file cannot specify ".." at the start of the @href attributes for <topicref> elements.
usetasklabels	Specifies whether to generate headings for sections within task topics. The allowed values are YES and NO; the default value is NO. Corresponds to the XSLT parameter GENERATE-TASK-LABELS.
xhtmlclass	Specifies whether to include the DITA class ancestry inside the XHTML elements .For example, the <prereq> element (which is specialized from section) would generate `class="section prereq`. The allowed values are yes and no; the default value is yes. Corresponds to the XSLT parameter PRESERVE-DITA-CLASS. Note Beginning with DITA OT release 1.5.2, the default value is yes. For release 1.5 and 1.5.1, the default value was no.
xsl	Specifies a custom XSL file to be used instead of the default XSL transformation (`xsl\dita2xhtml.xsl`). The parameter must specify a fully qualified file name.

2.2.6.2.3: Command-line tool parameters: Eclipse content transformation

Certain parameters are specific to the Eclipse content transformation.

Command-line tool parameters: Eclipse content transformation

Parameters	Description
eclipsecontenttoc	Specifies the name of the TOC file

2.2.6.2.4: Command-line tool parameters: Eclipse help transformation

Certain parameters are specific to the Eclipse help transformation.

Command-line tool parameters: Eclipse help transformation

Parameters	Description
eclipsehelptoc	Specifies the name of the TOC file.
provider	Specifies the name of the person or organization that provides the Eclipse help. The default value is DITA. Tip The toolkit ignores the value of this parameter when it processes an Eclipse map.
version	Specifies the version number to include in the output. The default value is 0.0.0. Tip The toolkit ignores the value of this parameter when it processes an Eclipse map.

2.2.6.2.5: Command-line tool parameters: HTML help transformation

Certain parameters are specific to the HTML help transformation.

Command-line tool parameters: HTML help transformation

Parameters	Description
htmlhelpincludefile	Specifies the name of a file that you want included in the HTML Help.

2.2.6.2.6: Command-line tool parameters: JavaHelp transformation

Certain parameters are specific to the JavaHelp transformation.

Command-line tool parameters: JavaHelp transformation

Parameters	Description
javahelpmap	Specifies the name of the ditamap file for a JavaHelp project. What does this mean? How does this differ from the args.input parameter? Or should this read "Specifies the name of the JavaHelp map file?
javahelptoc	Specifies the name of the file containing the TOC in your JavaHelp output. Default value is the name of the ditamap file for your project I assume that the first sentence means "Specifies the name of the JavaHelp TOC file." But what does the second sentence mean? That the default value for the args.javahelp.toc parameter is the name of the master DITA map? Or that the default value for the args.javahelp.toc parameter is the value of the args.javahelp.map parameter? .

Parameters

Description

javahelpmap

Specifies the name of the ditamap file for a JavaHelp project.

What does this mean? How does this differ from the args.input parameter? Or should this read "Specifies the name of the JavaHelp map file?

javahelptoc

Specifies the name of the file containing the TOC in your JavaHelp output. Default value is the name of the ditamap file for your project

2.2.6.2.7: Command-line tool parameters: ODT transformation

Certain parameters are specific to the ODT transformation.

Command-line tool parameters: ODT transformation

Parameters	Description
odtimgembed	Determines whether images are embedded as binary objects within the ODT file.
odtincluderellinks

2.2.6.2.8: Command-line tool parameters: PDF transformation

Certain parameters are specific to the PDF2 transformation.

Command-line tool parameters: PDF transformation

Parameters	Description
foincluderellinks
fooutputrellinks	Specifies whether to render related links in the output. The allowed values are yes and no; the default value is no. If the args.fo.include.rellinks parameter is specified, this parameter is ignored.
fouserconfig	Specifies the user configuration file for FOP.
retaintopicfo	Specifies whether to retain the generated FO file. The allowed values are yes and no; the default value is no. If the configuration property org.dita.pdf2.use-out-temp is set to false, this parameter is ignored.
xslpdf	Specifies an XSL file that is used to override the default XSL transformation (`plugins\org.dita.pdf2\xsl\fo\topic2fo_shell.xsl`). You must specify the fully qualified file name.

2.2.6.2.9: Command-line tool parameters: XHTML transformation

Certain parameters are specific to the XHTML transformation.

Command-line tool parameters: XTML transformation

Parameters	Description
xhtmltoc	Specifies the base name of the TOC file. The default value is index.

2.2.6.3: `lib/configuration.properties` file

The lib/configuration.properties file controls certain common properties, as well as some properties that control PDF processing.

Properties set in the `lib/configuration.properties` file

Property	Description
default.language	Specifies the language that is used if the input file does not have the @xml:lang attribute set on the root element. By default, this is set to en. The allowed values are those that are defined in IETF BCP 47, Tags for the Identification of Languages.
generate-debug-attributes	Specifies whether the @xtrf and @xtrc debugging attributes are generated in the temporary files. The following values are allowed: true (default) — Enables generation of debugging attributes false —Disables generation of debugging attributes Note Disabling debugging attributes reduces the size of temporary files and thus reduces memory consumption. However, the log messages no longer have the source information available and thus the ability to debug problems might deteriorate.
processing-mode	Specifies how the DITA-OT handles errors and error recovery. The following values are allowed: strict — When an error is encountered, the DITA-OT stops processing. lax (default) — When an error is encountered, the DITA-OT attempts to recover from it. skip — When an error is encountered, the DITA continues processing but does not attempt error recovery.
org.dita.pdf2.index.frame-markup	(PDF transformation only) Specifies how the DITA-OT handles legacy FrameMaker syntax for <indexterm> elements. The following values are allowed: true— Enables special processing of legacy FrameMaker syntax for <indexterm> elements. Standard DITA <indexterm> elements are processed also. false (default) — Disables special processing of legacy FrameMaker syntax for <indexterm> elements. Note Setting the org.dita.pdf2.index.frame-markup parameter to yes only affects how index entries are generated in PDF output. For example, an `<indexterm>files:topic</index>` element will generate an index entry of "files:topic" in a CHM file.
org.dita.pdf2.i18n.enabled	(PDF transformation only) Enables I18N font processing. The following values are allowed: true (default) — Enables I18N processing false — Disables I18N processing This needs beefing up. Here is info provided by Jarno Elovirta: (IIRC, pre 1.0 versions of FOP didn't correctly implement font selection in XSL FO files, that's the reason for this feature existing). The PDF2 I18N allows you to say define which characters are output with which pseudo-font, and the font mapping files define the actual font. E.g. the configuration for English at src/main/plugins/org.dita.pdf2/cfg/fo/i18n/en.xml is: <alphabet char-set="SymbolsSuperscript"> <character-set> <!-- Copyright --> <character>©</character> <!-- Registered Trademark --> <character>®</character> <!-- Trademark --> <character>™</character> <!-- Service mark --> <character>ࡈ</character> </character-set> </alphabet> <alphabet char-set="SubmenuSymbol"> <character-set> <character>➤</character> </character-set> </alphabet> That is, those specific characters are marked as "SymbolsSuperscript" or "SubmenuSymbol" charset. The font mappings at src/main/plugins/org.dita.pdf2/cfg/fo/font-mappings.xml then define which font to use for them, e.g.: <physical-font char-set="SymbolsSuperscript"> <font-face>Helvetica, Arial Unicode MS</font-face> <baseline-shift>20%</baseline-shift> <override-size>smaller</override-size> </physical-font> The I18N processing is on by default (because it's been on before), but for most users it's just an additional level of complexity which should be turned off and support for multiple languages be handled in XSLT code.
org.dita.pdf2.use-out-temp	(PDF transformation only) Specifies whether the XSL-FO processing writes the intermediate files (for example, the `topic.fo` file) to the output directory. The following values are allowed: true — Write intermediate files to the output directory false (default) — Write intermediate files to the temporary directory

Chapter 3: DITA Open Toolkit Developer Reference

The DITA Open Toolkit 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, configuring and extending the DITA-OT, and creating DITA-OT plug-ins.

3.3.1: DITA Open Toolkit Architecture

The DITA Open Toolkit is an open source implementation of the OASIS DITA Technical Committee's specification for Darwin Information Typing Architecture (DITA) DTDs and schemas. The toolkit uses open source solution of ANT, XSLT (currently 1.0 for most processing, with XSLT 2.0 for PDF) and Java to implement transformation functions from DITA content (maps and topics) into different deliverable formats.

Processing structure

The DITA Open Toolkit implements a multi-stage, map-driven architecture to process DITA content. Each step in the process examines some or all of the content; some steps result in temporary files used by later steps, while others 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).

Transformations in the toolkit are designed like a pipeline. Most of the pipeline is common between all output formats, and is known as the "pre-process" 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 desired 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 a different set of navigation files.

The following image illustrates how the pipeline works for some common output types.

Diagram of some possible paths through the transform pipeline.

3.3.1.1: Processing modules in the DITA-OT

The DITA-OT processing pipeline is implemented using Ant. Individual modules within the Ant script are generally implemented in either Java or XSLT, depending on a variety of factors, such as performance or requirements for customization. Virtually all Ant and XSLT modules are extensible 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 are all set up using shell files. Typically, each shell file begins by importing common rules that apply to all topics. This set of common processing may in turn import additional common modules, such as those used for reporting errors or determining the document locale. After the common files, additional imports may be included in order to support processing for DITA Specializations.

For example, XHTML processing is controlled by the dita2xhtml.xsl file inside the xsl\ directory. The shell begins by importing common rules 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, plug-ins may add in additional processing for local styles or for additional specializations.

Java modules are typically used when XSLT is a poor fit, such as for processes that work directly with the file system to copy files, or which 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.

3.3.1.2: Processing order within the DITA-OT

The order of processing is often significant when evaluating DITA content. Although the DITA specification does not mandate a specific order for processing, the toolkit has over time found that the current order best meets user expectations. Switching the order of processing, while legal, may give different results.

For example, if conref is evaluated before filtering, it is possible to reuse content that will later be filtered out of its original location. However, we have found that filtering first provides several benefits. For example, the following <note> element uses conref, but also 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.

However, if the filtering is done first as in the toolkit, this element is discarded immediately, and documentA is never examined. This provides several important benefits:

Time is saved simply by discarding unused content as early as possible; all future steps can load the document without this extra content.
More significant time is saved in this case by not evaluating the conref attribute; 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.

If the order of these two steps is reversed, so that conref is evaluated first, it is possible that results will differ. For example, on the sample above, the product attribute will override a product setting on the referenced note. Now assume that the note 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 -- resulting 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 desirable, benefits such as those described above resulted in the current processing order.

3.3.1.3: DITA-OT pre-processing architecture

This topic describes the set of steps commonly known as the pre-processing stage of a DITA build. These steps typically run at the start of any build using the DITA-OT, regardless of the final output format.

Each step described corresponds to one Ant target in the build pipeline. The general Ant target "preprocess" will call all of the targets described here.

3.3.1.3.1: 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 Ant and 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
chunkedditamapfile	`chunkedditamap.list`	chunkedditamaplist
chunkedtopicfile	`chunkedtopic.list`	chunkedtopiclist
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
keyreffile	`keyref.list`	keyreflist	Topics and maps which have key references.
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

3.3.1.3.2: Debug and filter (debug-filter)

The debug-filter stage processes all referenced DITA content, and creates copies in a temporary directory for use during the remainder of the build. Several modifications are made during this process.

As the files are copied, the following modifications are made:

The files are filtered according to entries in any specified DITAVAL file.
Debug information is inserted into each element (using the xtrf and xtrc attributes). These values allow messages later in the build to reliably indicate the original source of the error — for example, a message may trace back to the fifth <ph> element in a specific source document. Without these attributes, that count may no longer be available due to filtering and other processing.
Adjust column names in tables 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.

This step is implemented in Java.

3.3.1.3.3: Copy related files (copy-files)

The copy-files step copies related non-DITA resources to the output directory, such as HTML files referenced in a map or images referenced by DITAVAL files.

3.3.1.3.4: Conref push (conrefpush)

The conrefpush step resolves "conref push" references. The conref push feature was added in the DITA 1.2 specification, and the associated processing is available in DITA-OT version 1.5 and later. This step only processes documents that use conref push (or that are updated due to the push action). The step is implemented in Java.

3.3.1.3.5: Conref (conref)

The conref step resolves traditional conref attributes, processing only the documents that use the conref attribute. Each map or topic is processed with XSLT to resolve the attributes.

As part of the process, IDs within referenced content are changed as they are pulled into the new location. This is done in order to ensure that IDs within the original (referencing) topic remain unique.

If an element with an ID is pulled into a new context along with a cross reference that references the target, both the ID and the reference are updated so that they remain valid in the new location. For example, a referenced topic may include a section as in the following example.

<topic id="referenced_topic">
  <title>...</title>
  <body>
    <section id="sect"><title>Sample section</title>
      <p>Look at the next figure <xref href="#referenced_topic/fig">here</xref>.</p>
      <fig id="fig"><title>Sample</title>
        <p>This is a rather useless figure, but it
           illustrates a point.</p>
      </fig>
    </section>
  </body>
</topic>

If the section is referenced with a conref attribute, the ID on the <fig> element will be modified to ensure it remains unique inside the new topic. At the same time, the <xref> element will also be modified so that after the conref is resolved, it remains valid as a local reference. If the topic pulling in a new copy of the section has the id "new_topic", then the pulled copy of the section may look something like this in the intermediate document.

<section><title>Sample section</title>
  <p>Look at the next figure <xref href="#new_topic/d1e25">here</xref>.</p>
  <fig id="d1e25"><title>Sample</title>
    <p>This is a rather useless figure, but it
       illustrates a point.</p>
  </fig>
</section>

In this case, the ID of the figure 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 reference stays local in the updated topic.

3.3.1.3.6: Move metadata (move-meta-entries)

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 topics may be processed later in isolation while retaining all relevant metadata.

This step is implemented in Java.

3.3.1.3.7: Resolve keyref (keyref)

The keyref step examines all keys defined in the source material, and updates key references appropriately. 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 evaluated. The keyref mechanism was defined as part of the DITA 1.2 standard, and is available in DITA-OT 1.5 and later.

This step is implemented in Java.

3.3.1.3.8: Resolve code references (codref)

The coderef module resolves references made with the <coderef> element, which was added in DITA 1.2. This module is available in DITA-OT 1.5 and later.

The <coderef> element is used inside of <codeblock> to reference code stored externally in non-XML documents. During the pre-process step, this Java module pulls the referenced content into the <codeblock> element.

3.3.1.3.9: Resolve map references (mapref)

The mapref module resolves references from one map to another.

Maps may reference other maps using markup similar to the following:

<topicref href="other.ditamap" format="ditamap"/>

The DITA 1.2 standard added a new element that allows this sort of reference without setting the format attribute:

<mapref href="other.ditamap"/>

In either case, the element that references the other 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>).

This step is implemented in XSLT.

3.3.1.3.10: Pull content into maps (mappull)

The mappull step pulls content from referenced topics into maps, and cascades data within maps.

This step uses XSLT to make the following changes to the map:

Pull titles from referenced DITA topics. This step replaces the navigation title specified on the topicref. If the locktitle attribute is set to "yes", the value in the map is not changed.
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.
When a local DITA topic is referenced, the type attribute is set on the topicref based on the type of topic referenced. For example, a reference to a task topic will end up with type="task".
Inheritable attributes, such as toc or print, are made explicit on child topicref elements. This allows any future step to work with the attributes directly, without reevaluating the cascade behavior.

3.3.1.3.11: Chunk topics (chunk)

The chunk step is a Java module that breaks apart and assembles referenced DITA content based on the chunk attribute in maps.

The following values are recognized on the chunk attribute, based on definitions provided in the DITA specification. These values were initially defined in the DITA 1.1 specification, with significant clarifications in the DITA 1.2 specification.

select-topic
select-document
select-branch
by-topic
by-document
to-content
to-navigation.

3.3.1.3.12: Map based linking (maplink and move-links)

These two steps work together to create links based on a map and move those links into referenced topics. The links are created based on hierarchy (parent/child), the collection-type attribute (sequential or family links), and relationship tables.

The maplink module first runs an XSLT program that evaluates the map, and places all generated links into a single file in the temporary processing directory. Once that file is created, the move-links module runs a Java program that pushes the generated links into the proper topics.

3.3.1.3.13: Pull content into topics (topicpull)

The topicpull module pulls content into <xref> and <link> elements (if needed).

For <xref> elements, if the <xref> does not contain link text, the target is examined and link text is pulled. For example, a reference to a topic will pull the title of the topic; a reference to a list item will pull 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 with the short description of the target.

The process is similar for <link> elements. If the <link> 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> is created with the short description of the target.

This step is implemented in XSLT.

3.3.1.3.14: 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 in to the topic when flags are active. Any extended transform 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 @outputclass attribute. 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.

<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 <styleconflict> 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 <endflag> children of the properties will be included, but <startflag> children will not.

Supporting flags in overrides or custom transform types

For most transform 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>

3.3.1.3.14.1: 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.

If you do make use of DITAVAL based flagging, try using your override with 1.7. Check the elements you override:

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 $flagrules variable, 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 and mode="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.

For example, the common logic for most element rules before DITA-OT 1.7 could be boiled down to the following:

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>

In DITA-OT 1.7, style and images are typically handled with XSLT fallthrough processing. This removes virtually all special flag coding from element rules, because flags are already part of the document and processed in document order. The sample above is reduced to:

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.

With DITA-OT 1.7, the style is calculated in the pre-process flagging module. The result is created as @outputclass on a <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.

If the flow of your element rule processes flags outside of the normal document-order. There are generally two reasons this is done. The first case is for elements like <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"/>

For example, the following lines are used in DITA-OT 1.7 to process the <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"`

Prior to DITA-OT 1.7, many elements were processed with the following logic:

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".

3.3.1.3.1: Generate lists (gen-list)

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
chunkedditamapfile	`chunkedditamap.list`	chunkedditamaplist
chunkedtopicfile	`chunkedtopic.list`	chunkedtopiclist
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
keyreffile	`keyref.list`	keyreflist	Topics and maps which have key references.
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

3.3.1.3.2: Debug and filter (debug-filter)

As the files are copied, the following modifications are made:

The files are filtered according to entries in any specified DITAVAL file.
Debug information is inserted into each element (using the xtrf and xtrc attributes). These values allow messages later in the build to reliably indicate the original source of the error — for example, a message may trace back to the fifth <ph> element in a specific source document. Without these attributes, that count may no longer be available due to filtering and other processing.
Adjust column names in tables 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.

This step is implemented in Java.

3.3.1.3.3: Copy related files (copy-files)

The copy-files step copies related non-DITA resources to the output directory, such as HTML files referenced in a map or images referenced by DITAVAL files.

3.3.1.3.4: Conref push (conrefpush)

3.3.1.3.5: Conref (conref)

The conref step resolves traditional conref attributes, processing only the documents that use the conref attribute. Each map or topic is processed with XSLT to resolve the attributes.

<topic id="referenced_topic">
  <title>...</title>
  <body>
    <section id="sect"><title>Sample section</title>
      <p>Look at the next figure <xref href="#referenced_topic/fig">here</xref>.</p>
      <fig id="fig"><title>Sample</title>
        <p>This is a rather useless figure, but it
           illustrates a point.</p>
      </fig>
    </section>
  </body>
</topic>

<section><title>Sample section</title>
  <p>Look at the next figure <xref href="#new_topic/d1e25">here</xref>.</p>
  <fig id="d1e25"><title>Sample</title>
    <p>This is a rather useless figure, but it
       illustrates a point.</p>
  </fig>
</section>

3.3.1.3.6: Move metadata (move-meta-entries)

This step is implemented in Java.

3.3.1.3.7: Resolve keyref (keyref)

This step is implemented in Java.

3.3.1.3.8: Resolve code references (codref)

The coderef module resolves references made with the <coderef> element, which was added in DITA 1.2. This module is available in DITA-OT 1.5 and later.

3.3.1.3.9: Resolve map references (mapref)

The mapref module resolves references from one map to another.

Maps may reference other maps using markup similar to the following:

<topicref href="other.ditamap" format="ditamap"/>

The DITA 1.2 standard added a new element that allows this sort of reference without setting the format attribute:

<mapref href="other.ditamap"/>

This step is implemented in XSLT.

3.3.1.3.10: Pull content into maps (mappull)

The mappull step pulls content from referenced topics into maps, and cascades data within maps.

This step uses XSLT to make the following changes to the map:

Pull titles from referenced DITA topics. This step replaces the navigation title specified on the topicref. If the locktitle attribute is set to "yes", the value in the map is not changed.
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.
When a local DITA topic is referenced, the type attribute is set on the topicref based on the type of topic referenced. For example, a reference to a task topic will end up with type="task".
Inheritable attributes, such as toc or print, are made explicit on child topicref elements. This allows any future step to work with the attributes directly, without reevaluating the cascade behavior.

3.3.1.3.11: Chunk topics (chunk)

The chunk step is a Java module that breaks apart and assembles referenced DITA content based on the chunk attribute in maps.

select-topic
select-document
select-branch
by-topic
by-document
to-content
to-navigation.

3.3.1.3.12: Map based linking (maplink and move-links)

3.3.1.3.13: Pull content into topics (topicpull)

The topicpull module pulls content into <xref> and <link> elements (if needed).

This step is implemented in XSLT.

3.3.1.3.14: Flagging in the toolkit

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.

<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 @outputclass attribute. 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.

<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 <styleconflict> elements are not included on this element.

Supporting flags in overrides or custom transform types

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>

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

<p audience="user" platform="win">Conflicting styles (still no images)</p>

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>

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>

3.3.1.3.14.1: XHTML migration for flagging updates in DITA-OT 1.7

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 you do make use of DITAVAL based flagging, try using your override with 1.7. Check the elements you override:

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

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 $flagrules variable, 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 and mode="section-fmt" for sections.

What replaces the templates?

For example, the common logic for most element rules before DITA-OT 1.7 could be boiled down to the following:

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.

<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.

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"/>

For example, the following lines are used in DITA-OT 1.7 to process the <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"`

Prior to DITA-OT 1.7, many elements were processed with the following logic:

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

3.3.1.4: Generating XHTML with navigation

The toolkit ships with several varieties of XHTML output, each of which follows roughly the same path through the processing pipeline. All XHTML builds begin with the same call to the preprocess routine, after which they generate XHTML files and then branch to create navigation files.

Once the preprocess runs, XHTML based builds each run a common series of Ant targets. Navigation may be created before or after this set of common routines.

When the CSS parameter is passed to the build to add a CSS file, the copy-css target copies that CSS file from its source location to the proper relative location in the output directory.
When a DITAVAL file is used, the copy-revflag target copies the default start and end revision flags into the output directory.
Two targets names dita.inner.topics.xhtml and dita.outer.topics.xhtml are used to convert DITA topics into XHTML documents. At this point after the preprocess has completed, each DITA topic document in the temporary directory corresponds to one XHTML output document. The "inner" template is used to process documents that are in the map directory (or subdirectories of that directory). The "outer" template is used to process documents that are outside of the scope of the map, and may end up outside of the designated output directory. Parameters to the build control how documents processed by the "outer" target are handled.

3.3.1.4.1: Default XHTML output

The dita.map.xhtml target is called by default xhtml builds. This target generates a TOC file called index.html, which may be loaded into an independent frameset.

3.3.1.4.2: Eclipse help output (transform type "eclipsehelp")

Eclipse help is an XHTML based output format intended to create a plug-in for the Eclipse Help system. Once the normal XHTML process has run, the dita.map.eclipse target is used to create a set of several control files and navigation files for Eclipse.

Eclipse relies on several different files to control the plug-in. Some of these are generated by the build, while others may be created by hand. The Ant targets used to control this process are:

dita.map.eclipse.init sets up various default properties for processing Eclipse output.
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 with additional information used by Eclipse.
copy-plugin-files checks for the presence of several control files in the source directory, and copies those found to the output directory.
dita.map.eclipse.fragment.language.init, dita.map.eclipse.fragment.language.country.init, and dita.map.eclipse.fragment.error all work together to control Eclipse fragment files (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).

3.3.1.4.3: TocJS output path

The TocJS transform type was originally created as a plug-in distributed outside of the toolkit, but now ships bundled in the default packages. This XHTML based output type creates a JavaScript based frameset with TOC entries that expand and collapse.

A few Ant targets control most of the TocJS processing:

tocjsInit is used to set up default properties. This template detects whether builds have already set a name for the JavaScript control file; if not, the default name toctree.js is used.
map2tocjs calls dita.map.tocjs, which generates the contents frame for TocJS output.
tocjsDefaultOutput was added to the process in version 1.5.4 of the DITA-OT. If scripts are missing some required information, such as a name for the default frameset, this template will copy default style and control files. It also ensures that the XHTML process runs (earlier versions of TocJS created only the JavaScript control file by default).

3.3.1.4.4: Compiled Help (CHM) output

The transform type "htmlhelp" is used to create HTML Help control files. If the build runs on a system that has the HTML Help compiler installed, the control files will be compiled into a CHM file.

Once the preprocess and XHTML process is complete, most of the HTML Help processing is handled by the dita.map.htmlhelp target. This target creates several files:

The HHP file is the control file for the HTML Help project.
The HHC file contains the HTML Help table of contents.
The HHK file contains the HTML Help index. This file is sorted based on the language of the map.

The dita.htmlhelp.convertlang is a post-processor for the content to ensure that it can be processed correctly by the compiler, and that the appropriate codepages and languages are used.

Finally, compile.HTML.Help attempts to detect the HTML Help compiler; if found, it compiles the full project into a single CHM file.

3.3.1.4.5: Javahelp output

The "javahelp" transform type runs several additional Ant targets after the XHTML process is completed in order to create control files for JavaHelp output.

There are two primary targets in the Ant JavaHelp code.

dita.map.javahelp creates all of the files 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 found, it will compile the help project.

3.3.1.5: PDF output pipeline

The PDF process (formerly known as PDF2) runs the preprocess routine, followed by a series of additional targets. These steps work together to create a merged set of content, convert that to XSL-FO, and then format the FO file to PDF.

The PDF process adds many new 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 publish.map.pdf to do the remainder of the work.
The publish.map.pdf target does some initialization, and then calls transform.topic2pdf to do the remainder of processing. That target runs all of the following steps.
- transform.topic2fo is used to convert the merged file to an XSL-FO file. This process is composed of several Ant targets.
  - transform.topic2fo.index runs 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.flagging sets up preprocessing for flagging based on a DITAVAL file. This step generates the file stage1a.xml in the temporary processing directory.
  - transform.topic2fo.main does 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.i18n does 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 available 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.

3.3.1.6: ODT Transform type (Open Document Format)

The "odt" transform type creates a binary file using the OASIS standard Open Document Format.

The "odt" transform path begins with the preprocess, as with other builds. It then runs the Ant target dita.odt.package.topic (if the input file is a topic) or dita.odt.package.map (if the input file is a map). This description focuses on the map process, which is made up of the following targets.

dita.map.odt creates the content.xml portion of the ODT output file. This is done by converting the map into a merged XML file using the Java topicmerge program. An XSLT process is then used to convert the merged file into content.xml.
dita.map.odt.stylesfile is a target that reads the input map, and uses XSLT to create a styles.xml file in the temporary directory.
dita.out.odt.manifest.file creates the manifest.xml portion of the ODT output file.
Once the three previous targets run, the generated files are zipped up together with other required files to create the output ODT file.

3.3.2: 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.

3.3.2.1: Installing plug-ins

Plug-ins are generally distributed as zip files. There are two steps to installing a plug-in: unzipping and integrating.

It is possible to define a plug-in so that it may be installed anywhere, although most expect to be placed in plugins/ directory inside of the DITA-OT. Most plug-ins do not require a specific install directory and can go in either of the default locations, but some may come with instructions for a particular install directory.

The unzip the plug-in file to plugins subdirectory.
The plug-in directory should be named after plug-in ID and version, for example plugins/com.example.xhtml_1.0.0.
Run plug-in integration process.
- From the toolkit directory, run the following command to integrate all installed plug-ins:
```
ant -f integrator.xml 
```
- Any build that uses the Java command line interface automatically runs the integrator before processing begins.
- Ant based builds may import the integrator.xml file, and add integrate to the start of the dependency chain for the build.
  
  Note
  
  The integration process in considered part of the installation process and running it before each conversion will incur a performance penalty.
The integration process has two modes, lax and strict. In the strict mode the integration process will immediately fail if it encounters errors in plug-in configurations or installation process. In the lax mode, the integration process will continue to finish regardless of errors; the lax mode does not imply error recovery and may leave the DITA-OT installation into a broken state. The default mode is lax due to backwards compatibility, to run the integration in strict mode:
```
ant -f integrator.xml strict
```
To get more information about the integration process, run Ant in verbose mode:
```
ant -f integrator.xml -verbose strict
```

3.3.2.2: Removing plug-ins

Plug-ins can be installed by removing the plug-in and running integration process.

Remove plug-in installation directory.
Run integration process.
```
ant -f integrator.xml
```

3.3.2.3: 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.

Change to the doc directory.
Run the following command:
```
ant -f build.xml target
```
The target parameter is optional and specifies a specific transformation type. It takes the following values:
- build-html
- build-htmlhelp
- build-pdf
If you do not specify target, all three output formats (XHTML, HTML help, and PDF) are generated.

3.3.3: Configuring the DITA Open Toolkit

The DITA OT uses .properties files that store configuration settings for the DITA OT and its plug-ins. The configuration properties are available to both Ant and Java processes, but unlike argument properties, they cannot be set at run time.

3.3.3.1: `integrator.properties` file

The integration process can be configured using the integrator.properties file.

Properties set in the integrator.properties file

Property	Description
plugindirs	A semicolon-separated list of directory paths that the DITA OT searches for plug-ins to integrate; any relative paths are resolved against the DITA-OT base directory. Any immediate subdirectory that contains a `plugin.xml` file is integrated
plugin.ignores	A semicolon-separated list of directory names to be ignored during plug-in integration.

3.3.3.2: `lib/org.dita.dost.platform/plugin.properties` file

The lib/org.dita.dost.platform/plugin.properties file is used to store configuration properties that are set by the integration process. The file is regenerated each time the integration process is run and so should not be edited manually.

3.3.4: Creating DITA-OT plug-ins

The DITA Open Toolkit comes with a built in mechanism for adding in extensions through plug-ins. These plug-ins may do a wide variety of things, such as adding support for specialized DITA DTDs or Schemas, integrating processing overrides, or even providing entirely new output transforms. Plug-ins are the best way to extend the toolkit in a way that is consistent, easily sharable, and easy to preserve through toolkit upgrades.

A plug-in consists of a directory, typically stored directly within the plugins/ directory inside of the DITA-OT. Every plug-in is controlled by a file named plugin.xml, located in the plug-in's root directory.

Benefits of extending the toolkit through plug-ins include:

Plug-ins are easily sharable with other users, teams, or companies; typically, all that is needed is to unzip and run a single integration step. With many builds, even that integration step is automatic.
Allows 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 with an upgraded toolkit simply by unzipping again, or by copying the directory from one install to another; there is no need to re-integrate code based on updates to the core processing.
Plug-ins can build upon each other. If you like a plug-in provided by one user, simply install that plug-in, and then create your own that builds on that extension. The two plug-ins can then be distributed to your team as a unit, or you can even share your own extensions with the original provider.

3.3.4.1: Plug-in configuration file

The 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 integrates those changes into the core code.

The root element of the plugin.xml file is <plugin>, and must specify an id attribute. The id attribute is used to identify the plug-in, as well as to identify whether pre-requisite plug-ins are available. The id attribute should follow the syntax rules:

id    ::= token('.'token)*
token ::= ( [0..9] | [a..zA..Z] | ’_’ | ’-’ )+

The <plugin> element supports the following child elements:

<feature> defines an extension to contribute to a defined extension point. The following attributes are supported:

Attribute	Description	Required
`extension`	extension point identifier	yes
`value`	comma separated string value of the extension	either `value` or `file`
`file`	file path value of the extension, relative to `plugin.xml`	either `value` or `file`
`type`	type of the `value` attribute	no

extension-point defines new a extension point that can be used by other plug-ins. The following attributes are supported:

Attribute	Description	Required
`id`	extension point identifier	yes
`name`	extension point name	no

<require> defines plug-in dependencies. The following attributes are supported:

Attribute	Description	Required
`plugin`	vertical bar separated list of plug-ins that are required	yes
`importance`	flag whether plug-in is required or optional	no

<template> defines files that should be treated as templates. The following attributes are supported:

Attribute	Description	Required
`file`	file path to the template, relative to `plugin.xml`	yes

<meta> defines metadata. The following attributes are supported:

Attribute	Description	Required
`type`	metadata name	yes
`value`	metadata value	yes

Any extension that is not recognized by the DITA-OT is ignored; all elements other than <plugin> are optional. Since version 1.5.3 multiple extension definitions within a plug-in configuration file are combined; in older versions only the last extension definition is used.

3.3.4.2: Extending the XML Catalog

The XML Catalogs extension point is used to update the XML Catalogs used to resolve DTD or Schema document types, or to add URI mappings. This is required in order to support DITA specializations or new DITA document type shells.

To do this, first create a catalog with only your new values, using the OASIS Catalog format, and place that in your plug-in. Local file references in the catalog should be relative to the location of the catalog. The following extension points are available to work with catalogs.

dita.specialization.catalog.relative
dita.specialization.catalog: Adds the content of the catalog file defined in file attribute to main DITA-OT catalog file.

Remember

The dita.specialization.catalog extension is deprecated. Use dita.specialization.catalog.relative instead.
org.dita.pdf2.catalog.relative: Adds the content of the catalog file defined in file attribute to main PDF plug-in catalog file.

Example

This example assumes that "catalog-dita.xml" contains an OASIS catalog for any DTDs or Schemas inside this plug-in. The catalog entries inside of catalog-dita.xml are relative to the catalog itself; when the plug-in is integrated, they will be 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>

3.3.4.3: Adding new targets to the Ant build process

The Ant conductor extension point is used to make new targets available to the Ant processing pipeline. This may be done as part of creating a new transform, extending pre-processing, or simply to provide Ant targets for the use of other plug-ins.

dita.conductor.target.relative
dita.conductor.target: Add Ant import to main Ant build file.

Remember

The dita.conductor.target extension is deprecated. Use dita.conductor.target.relative instead.

Example

To extend And processing, first place your extensions in an Ant project file within your plug-in, such as myAntStuff.xml. Next, create a small wrapper file myAntStuffWrapper.xml in the same directory:

<dummy> <import file="myAntStuff.xml"/> </dummy>

Then create the following feature:

<plugin id="com.example.ant">
  <feature extension="dita.conductor.target.relative" file="myAntStuffWrapper.xml"/>
</plugin>

When the plug-in is integrated, the imports from myAntStuffWrapper.xml will be copied into build.xml (using the correct path). This makes targets in myAntStuff.xml available to any other processing.

3.3.4.4: Adding Ant targets to the pre-process pipeline

Every step in the pre-process pipeline defines an extension point before and after the step, to allow plug-ins to integrate additional processing. This allows a plug-in to insert a new step before any pre-processing step, as well as before or after the entire preprocess pipeline.

The group of preprocessing steps defines extension points before and after the full preprocessing chain.

depend.preprocess.pre: Preprocessing pre-target; extending this target runs your Ant target before the full preprocess routine begins.
depend.preprocess.post: Preprocessing post-target; extending this target runs your Ant target after the full preprocess routine completes.

In addition, there are extension points to execute an Ant target before individual preprocessing steps.

depend.preprocess.clean-temp.pre: Clean temp pre-target
depend.preprocess.gen-list.pre: Generate list pre-target
depend.preprocess.debug-filter.pre: Debug and filter pre-target
depend.preprocess.conrefpush.pre: Content reference push pre-target
depend.preprocess.move-meta-entries.pre: Move meta entries pre-target
depend.preprocess.conref.pre: Content reference pre-target
depend.preprocess.coderef.pre: Code reference pre-target
depend.preprocess.mapref.pre: Map reference pre-target
depend.preprocess.keyref.pre: Resolve key reference pre-target
depend.preprocess.mappull.pre: Map pull pre-target
depend.preprocess.chunk.pre: Chunking pre-target
depend.preprocess.maplink.pre: Map link pre-target
depend.preprocess.move-links.pre: Move links pre-target
depend.preprocess.topicpull.pre: Topic pull pre-target
depend.preprocess.copy-files.pre: Copy files pre-target
depend.preprocess.copy-image.pre: Copy images pre-target
depend.preprocess.copy-html.pre: Copy HTML pre-target
depend.preprocess.copy-flag.pre: Copy flag pre-target
depend.preprocess.copy-subsidiary.pre: Copy subsidiary pre-target
depend.preprocess.copy-generated-files.pre: Copy generated files pre-target

Example

The following feature adds "myAntTargetBeforeChunk" Ant target to be executed before the chunk step in preprocessing. It assumes that an Ant file defining that target has already been integrated.

<plugin id="com.example.extendchunk">
  <feature extension="depend.preprocess.chunk.pre" value="myAntTargetBeforeChunk"/>
</plugin>

When integrated, the Ant target "myAntTargetBeforeChunk" will be added to the Ant dependency list so that it always runs immediately before the Chunk step.

3.3.4.5: Integrating a new transform type

Plug-ins may integrate an entire new transform type. The new transform type can be very simple, such as an XHTML build that creates an additional control file; it can also be very complex, adding any number of new processing steps.

The transtype extension point is used to define a new "transtype", or transform type, which makes use of targets in your Ant extensions. When a transform type is defined, the build expects Ant code to be integrated to define the transform process. The Ant code must define a target based on the name of the transform type; if the transform type is "mystuff", the Ant code must define a target named dita2mystuff.

dita.conductor.transtype.check: Add new value to list of valid transformation type names.
dita.transtype.print: Declare transtype as a print type.

Example

The following feature defines a transform type of "newtext" and declares it as a print type; using this transform type will cause the build to look for a target dita2newtext, defined in a related Ant extension from the third feature:

<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="antWrapper.xml"/>
</plugin>

3.3.4.6: Override styles with XSLT

The XSLT import extension points are used to override various steps of XSLT processing. For this, the extension attribute indicates the step that the override applies to; the file attribute is a relative path to the override within the current plugin. The plugin installer will add an XSL import statement to the default code so that your override becomes a part of the normal build.

The following XSLT steps are available to override in the core toolkit:

dita.xsl.xhtml: Overrides default (X)HTML output (including HTML Help and Eclipse Help). The referenced file is integrated directly into the XSLT step that generates XHTML.
dita.xsl.xslfo: Overrides default PDF output (formerly known as PDF2). The referenced file is integrated directly into the XSLT step that generates XSL-FO for PDF.
dita.xsl.docbook: Overrides default DocBook output.
dita.xsl.rtf: Overrides default RTF output.
dita.xsl.eclipse.plugin: Overrides the step that generates plugin.xml for Eclipse.
dita.xsl.conref: Overrides the preprocess step that resolves conref.
dita.xsl.topicpull: Overrides the preprocess step "topicpull" (the step that pulls text into <xref> elements, among other things).
dita.xsl.mapref: Overrides the preprocess step "mapref" (the step that resolves references to other maps).
dita.xsl.mappull: Overrides the preprocess step "mappull" (the step that updates navtitles in maps and causes attributes to cascade).
dita.xsl.maplink: Overrides the preprocess step "maplink" (the step that generates map-based links).
dita.xsl.fo: Override the (now deprecated) original PDF output, which is still available with the transform type "legacypdf".

Example

The following two files represent a complete, simple style plug-in. The plugin.xml file declares an XSLT file that extends XHTML processing; the XSLT file overrides default header processing to provide a (theoretical) banner.

plugin.xml:
<?xml version="1.0" encoding="UTF-8"?>
<plugin id="com.example.brandheader">
  <feature extension="dita.xsl.xhtml" file="xsl/header.xsl"/>
</plugin>

xsl/header.xsl:
<?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>

3.3.4.7: 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.

The generated text extension point is used to add new strings to the default set of generated text. There are several reasons you may want to use this:

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>

Note

If two plug-ins define the same string, the results will be non-deterministic, so multiple plug-ins should not try to create the same generated text string. One common way to avoid this problem is to ensure the name attributes used to look up the string value are related to the ID or purpose of your plug-in.

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.

Note

If two plug-ins override the same string in the same language, the results will be non-deterministic (either string may be used under different conditions). Multiple plug-ins should not override the same generated text string for a single language.

Example: adding a new language

The process for adding a new language is exactly the same as for adding new text, except you are effectively just translating an existing strings file. To begin, set up the xsl/my-new-strings.xml file in your plug-in as in the previous examples. In this case, the only difference is that you are adding a mapping to new languages; for example, the following file would be used to set up support for Vietnamese:

<?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ú ý".

Note

If two plug-ins add support for the same language using different values, the results will be non-deterministic (translations from either plug-in may be picked up under different conditions).

3.3.4.8: Passing parameters to existing XSLT steps

Plug-ins can define new parameters to be passed from the Ant build into existing XSLT pipeline stages, usually to have those parameters available as global <xsl:param> values within XSLT overrides.

To create new parameters, create a file insertParameters.xml which contains one or more Ant <param> elements. It also needs a <dummy> wrapper element around the parameters. For example, the following parameter will be passed in to the XSLT file with a value of ${antProperty}, but only if that parameter is defined:

<dummy>
  <!-- Any Ant code allowed in xslt task is possible. Common example: -->
  <param name="paramNameinXSLT" expression="${antProperty}" if="antProperty"/>
</dummy>

Pass the value using the following extensions:

dita.conductor.html.param: Pass parameters to HTML and HTML Help XSLT
dita.conductor.xhtml.param: Pass parameters to XHTML and Eclipse Help XSLT
dita.conductor.xhtml.toc.param: Pass parameters to XHTML TOC XSLT
dita.conductor.eclipse.toc.param: Pass parameters to Eclipse Help TOC XSLT
dita.preprocess.conref.param: Pass parameters to conref XSLT
dita.preprocess.mapref.param: Pass parameters to mapref XSLT
dita.preprocess.mappull.param: Pass parameters to mappull XSLT
dita.preprocess.maplink.param: Pass parameters to maplink XSLT
dita.preprocess.topicpull.param: Pass parameters to topicpull XSLT
dita.conductor.pdf2.param: Pass parameters to PDF2 XSLT

Example

The following plug-in will pass the parameters defined inside of insertParameter.xml as input to the XHTML process. Generally, an additional XSLT override will make use of the parameter to do something new with the generated content.

<plugin id="com.example.newparam">
  <feature extension="dita.conductor.xhtml.param" file="insertParameters.xml"/>
</plugin>

3.3.4.9: Adding Java libraries to the classpath

If your Ant or XSLT extensions require additional Java libraries in the classpath, you can add them to the global DITA-OT classpath with the following feature.

dita.conductor.lib.import: Add Java libraries to DITA-OT classpath.

Example

The following plug-in adds the compiled Java code from myJavaLibrary.jar into the global DITA-OT classpath. XSLT or Ant code can then make use of the added code.

<plugin id="com.example.addjar">
  <feature extension="dita.conductor.lib.import" file="myJavaLibrary.jar"/>
</plugin>

Now assume that in this case myJavaLibrary.jar performs some validation step in the middle of processing, and you always want it to run immediately before the conref step. In that case you need to make use of several features in this plug-in

The JAR file must be added to the classpath.
An Ant target must be created that uses this class, and the Ant wrapper integrated into the code.
The Ant target must be added to the dependency chain for conref.

In this extended example, the files might look something like this.

plugin.xml:
<?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>

antWrapper.xml imports the new Ant code:
<?xml version="1.0" encoding="UTF-8"?>
<dummy>
  <import file="calljava-antcode.xml"/>
</dummy>

calljava-antcode.xml:
<?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>

3.3.4.10: Adding diagnostic messages

Plug-in specific warning and error messages can be added to the set of messages supplied by the DITA-OT. These messages can then be used by any XSLT override.

dita.xsl.messages: Add new messages to diagnostic message file.

Example

To add your own messages, create the new messages in an XML file such as myMessages.xml:

<dummy>
  <!-- See resource/messages.xml for the details. -->
  <message id="DOTXmy-msg-numW" type="WARN">
    <reason>Message text</reason>
    <response>How to resolve</response>
  </message>
</dummy>

There are three components to the message ID:

The prefix DOTX is used by all DITA-OT XSLT transforms, and must be part of the ID.
This is followed by the message number ("my-msg-num" in the sample above). By convention, this should be a three digit integer.
Finally, a letter corresponds to the severity. This should be one of:
- I = Informational, used with type="INFO"
- W = Warning, used with type="WARN"
- E = Error, used with type="ERROR"
- F = Fatal, used with type="FATAL"

Once the message file is defined, it is incorporated with this extension:

<plugin id="com.example.newmsg">
  <feature extension="dita.xsl.messages" file="myMessages.xml"/>
</plugin>

XSLT modules can then generate the message using the following call:

<xsl:call-template name="output-message">
  <xsl:with-param name="msgnum">my-msg-num</xsl:with-param>
  <xsl:with-param name="msgsev">W</xsl:with-param>
</xsl:call-template>

3.3.4.11: Managing plug-in dependencies

The <require> element in a plugin.xml file is used to create a dependency on another plug-in. The <require> element requires the plugin attribute in order to reference the dependency.

If the current plug-in requires a plug-in with id="plugin-id" before it can be installed, it would include the following:

<require plugin="plugin-id">

Prerequisite plug-ins are integrated before the current plug-in is integrated. This does the right thing with respect to XSLT overrides. If your plug-in is a specialization of a specialization, it should <require> its base plug-ins, in order from general to specific.

If a prerequisite plug-in is missing, a warning will be printed during integration. To suppress this, but keep the integration order if both plug-ins are present, add importance="optional" to the <require> element.

If your 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

The following plug-in will only be installed if the plug-in with id="com.example.primary" is available. If that one is not available, a warning will be generated during the integration process.

<plugin id="com.example.builds-on-primary">
  <!-- ...extensions here -->
  <require plugin="com.example.primary"/>
</plugin>

The following plug-in will only be installed if either the plug-in with id="pluginA" or the plug-in with id="pluginB" are available. If neither of those are installed, the current plug-in will be ignored.

<plugin id="pluginC">
  <!-- ...extensions here -->
  <require plugin="pluginA|pluginB" importance="optional"/>
</plugin>

3.3.4.12: Version and support information

The following extension points are used by convention to define version and support info within a plug-in.

package.support.name
package.support.email
package.version

Note

The toolkit does not currently do anything with these values, but may do so in the future.

The package.version value should follow the syntax rules:

version   ::= major ( '.' minor ( '.' micro ( '.' qualifier )? )? )?

major     ::= number
minor     ::= number
micro     ::= number
qualifier ::= ( [0..9] | [a..zA..Z] | ’_’ | '-' )+

The default value is 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>

3.3.4.13: 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 id attribute defines the extension point ID which provides the argument data.
The behaviour attribute defines which processing action is used.

Supported values for behavior attribute:

org.dita.dost.platform.CheckTranstypeAction: Create Ant condition elements to check if ${transtype} property value equals a supported transtype value.
org.dita.dost.platform.ImportAntLibAction: Create Ant pathelement elements for library imported extension point. The id attribute 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 id attribute is used to define the extension point ID.
org.dita.dost.platform.ImportXSLAction: Create xsl:import elements based on XSLT import extension point. The id attribute 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 id attribute 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 id attribute 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 id attribute is used to define the extension point ID.
org.dita.dost.platform.ListTranstypeAction: Create a pipe delimited list of supported transtypes.

`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"
                    behaviour="org.dita.dost.platform.InsertAction"/>
  <target>
</project>

3.3.4.14: 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>

3.3.5: Customizing PDF output

Example of PDF output customization with a custom transformation type.

Create a new plug-in directory com.example.print-pdf into DITA-OT plugins directory.

Create a plug-in configuration file plugin.xml, declare the new transformation type print-pdf and dependencies.

<?xml version='1.0' encoding='UTF-8'?>
<plugin id="com.example.print-pdf">
  <require plugin="org.dita.pdf2"/>
  <feature extension="dita.conductor.transtype.check" value="print-pdf"/>
  <feature extension="dita.transtype.print" value="print-pdf"/>
  <feature extension="dita.conductor.target.relative" file="integrator.xml"/>
</plugin>

Add an Ant script integrator.xml to define the transformation type.

<?xml version='1.0' encoding='UTF-8'?>
<project name="com.example.print-pdf">
  <target name="dita2print-pdf.init">
    <property name="customization.dir" location="${dita.plugin.com.example.print-pdf.dir}/cfg"/>
  </target>
  <target name="dita2print-pdf" depends="dita2print-pdf.init, dita2pdf2"/>
</project>

Add a cfg/catalog.xml file to take custom XSLT stylesheets into use.

<?xml version="1.0" encoding="UTF-8"?>
<catalog prefer="system" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/>
  <uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/>
</catalog>

Add attribute and variable overrides to cfg/fo/attrs/custom.xsl

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="2.0">
  <!-- Change page size to A4 -->
  <xsl:variable name="page-width">210mm</xsl:variable>
  <xsl:variable name="page-height">297mm</xsl:variable>
</xsl:stylesheet>

Add XSLT overrides to cfg/fo/xsl/custom.xsl

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version="2.0">
  <!-- Move figure title to top and description to bottom -->
  <xsl:template match="*[contains(@class,' topic/fig ')]">
    <fo:block xsl:use-attribute-sets="fig">
      <xsl:call-template name="commonattributes"/>
      <xsl:if test="not(@id)">
        <xsl:attribute name="id">
          <xsl:call-template name="get-id"/>
        </xsl:attribute>
      </xsl:if>
      <xsl:apply-templates select="*[contains(@class,' topic/title ')]"/>
      <xsl:apply-templates select="*[not(contains(@class,' topic/title ') or contains(@class,' topic/desc '))]"/>
      <xsl:apply-templates select="*[contains(@class,' topic/desc ')]"/>
    </fo:block>
  </xsl:template>
</xsl:stylesheet>

Add variable definition file cfg/common/vars/en.xml for English to override generated text.

<?xml version="1.0" encoding="UTF-8"?>
<vars xmlns="http://www.idiominc.com/opentopic/vars">
  <!-- Remove dot from list number -->
  <variable id="Ordered List Number"><param ref-name="number"/></variable>
  <!-- Change unordered list bullet to an em dash -->
  <variable id="Unordered List bullet">&#x2014;</variable>
</vars>

The plug-in directory should have the layout and files:

com.example.print-pdf/
  cfg/
    common/
      vars/
        en.xml
    fo/
      attrs/
        custom.xsl
      xsl/
        custom.xsl
    catalog.xml
  integrator.xml
  plugin.xml

Run integration process to install the plug-in and take the print-pdf transformation type into use.

3.3.6: Internal Ant properties

Reference list of Ant properties used by DITA-OT internally.

include.rellinks: Space separated list of link roles to be output; value token #default denotes default role value. Property default value depends on transformation type. Defined by args.rellinks, but may be overridden directly.

3.3.7: 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.

Note

In effect, for HTML based transformation types this is equivalent to select-document and by-document defaults.

Error recovery:

When two tokens from the same category are used, no error or warning is thrown.
This violates DITA 1.2 spec.
When an unrecognized chunking method is used, no error or warning is thrown.

Filtering

Error recovery:

When there are multiple revprop elements 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 behaviour, 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, image is scaled non-uniformly.

If 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, 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, DOTJ054E error is thrown. Depending on error recover mode, error recover 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.

3.3.8: Extended functionality

Code reference processing

DITA-OT supports defining the code reference target file encoding using the format attribute. The supported format is:

format (";" space* "charset=" charset)?

If charset is not defined system default charset will be used. If charset is not recognized or supported, DOTJ052E error is thrown and system default charset is used as a fall-back.

<coderef href="unicode.txt" format="txt; charset=UTF-8"/>

3.3.9: Topic merge

The topic merge feature improves the build speed of DITA files and reduces the possibility of meeting the out of memory exception in the build process. As illustrated in the following figure, when you run the build in previous releases of DITA Open Toolkit, the build speed is slow and you are likely to get out of memory exception.

With this enhanced topic merge feature, you will be less likely to meet the out of memory exception error when you build output through DITA files. The intermediate merged file will keep the structure information in the DITA map, and the structured toc will be reflected in the output.

To know more about this topic feature, you can write a script file first. DITA OT 1.3 offers a module, TopicMerge, that helps you implement this feature. You can use this module to generate the merged files. A sample usage of this module is as follows.

sample.xml:

<project name="sample">
  <property name="dita.dir" value="${basedir}"/>
  <import file="${dita.dir}${file.separator}build.xml"/>

  <target name="premerge">  
      <antcall target="preprocess">
      <param name="args.input" value="${input}"/>
    <param name="output.dir" value="${dita.dir}${file.separator}output"/>
    </antcall>
  </target>
  <target name="merge" description="Merge topics" depends="premerge">
    <basename property="temp.base" file="${input}" suffix=".ditamap"/>
    <property name="temp.input" value="${basedir}${file.separator}${dita.temp.dir}${file.separator}${temp.base}"/>
    <dirname property="temp.dir" file="${temp.input}"/>
    <pipeline message="topicmerge" module="TopicMerge" 
      inputmap="${temp.dir}${file.separator}${temp.base}.ditamap" 
      extparam="output=${dita.dir}${file.separator}output${file.separator}${temp.base}_merged.xml;
      style=${dita.dir}${file.separator}xsl${file.separator}pretty.xsl" /> 
  </target>
</project>

Then, you need to type ant -f sample.xml merge -Dinput="C:\DITA-OT1.8.M2\test.ditamap" in the command window.

Note

The path for -Dinput must be an absolute path

3.3.10: Creating Eclipse help from within Eclipse

This topic explains how to create an Eclipse help documentation plug-in from within the Eclipse platform. This process allows you to set up repeatable builds directly within Eclipse, which may already be familiar to many developers working within Eclipse. The topic was originally written based on Eclipse 3.3, but much of the information still applies.

You can use a template to develop documentation plug-in with DITA in Eclipse PDE and use DITA-OT 1.8.M2 to build and pack the final plug-in. When you want to develop a documentation plug-in with DITA in Eclipse, you cannot use the previous releases of DITA-OT in Eclipse to transform DITA to HTML. Though previous releases of DITA-OT support the feature to transform DITA files to Eclipse documentation plug-in, they are not integrated with Eclipse. With DITA-OT 1.8.M2 integrated with WPT, you can develop document plug-ins with DITA in Eclipse PDE and build and pack the final plug-in by taking the following steps.

Create a new PDE project in Eclipse, and apply the DITA template to the project by following the wizard.

Set the source directory, the main ditamap file, the output directory (default value is root directory of project), css storage directory (used to containcommon.css, commonltr.css, and commonrtl.css), user customized .css file name, and conditional processing ditaval file in the wizard. Use root as output directory is selected as the default.
You can also clear Use root as output directory and specify another output directory.
Create DITA files in the source directory and a ditamap to include the topic files that you created.
Import the DITA files into the src directory of the DITA plug-in project you just created.
1. Right-click a directory that you want to put the imported files and select Import ⇒ File system .
2. Select the directory under which you put the DITA files.
3. Click Finish after you selected the DITA files under the specified directory. The DITA files are then imported to your DITA project.
Right click build.xml, select Run As ⇒ Ant Build .

Note

If you're using Oracle JDK, please download and use the latest Xalan. The Xalan shipped with Oracle JDK has some issue that will cause the build failure. You can use the latest Xalan by selecting ANT Build ... and include the all of Xalan's jar files in Classpath.

After the transformation, the output is in the output directory set in build.xml. Refresh the project after the build is successful.
Edit the plug-in description of the property file MANITEST.MF in the plug-in editor after you run the Ant build successfully.
1. Click MANITEST.MF to go to the Overview page.
2. Edit Dependencies to include org.eclipse.help.
3. Edit Extensions to add org.eclipse.help.toc; right click the added org.eclipse.help.toc, and select New ⇒ toc .
4. Edit the Build Configuration to include the out directory or the directory you specified in 2.
5. Save the changes you made to the property file MANITEST.MF.
Export the output to a documentation plug-in.

Note

build.xml can be customized to meet the requirement of headless build.
1. Select File ⇒ Export ; select Deployable plug-ins and fragments and click Next.
2. Select the plug-in you want to export and specify a directory under which you want to put the plug-in package.
3. Click Finish to export the plug-in package.

Appendix A: DITA-OT release history

A.4.1 DITA Open Toolkit Release 1.8

General Enhancements and Changes

Preprocessing

Additional validation has been added to check e.g. element ID uniqueness, and xml:lang and URI syntax.

PDF

Bundled FOP has been updated from 1.0 to 1.1.

Migration from previous releases

Stylesheets for the following transtypes 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} instead
dita.resource.dir, use ${dita.plugin.org.dita.base.dir}/resource instead
dita.empty
args.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.

PDF

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-processing
toc-prefix-text, use tocPrefix mode instead
toc-topic-text, use tocText mode instead

Link generation has been simplified by removing deprecated arguments in favour of args.rellinks. The following deprecated Ant properties have been removed:

args.fo.include.rellinks

The following XSLT parameters have been removed:

antArgsIncludeRelatedLinks
disableRelatedLinks

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 favour 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

Issues

The following items are included in DITA Open Toolkit Release 1.8. Issue numbers correspond to the tracking number in the GitHub issues tracker .

Feature requests

#1406 Bundle FOP 1.1 (milestone 1)
#1447 Move stylesheets and resource files to plug-in folder (milestone 1)
#1449 Add support for Slovenian (milestone 1)
#1453 Add image metadata filter (milestone 1)
#1455 Remove deprecated features

Bugs

#1425 XHTML flagging included before imports (milestone 1)
#1428 Topic level calculated incorrectly for appendices (milestone 1)
#1427 Fix text overflow issue in lot/lof entries with long titles (milestone 1)
#1430 PDF transformation: Problems with index in OT 1.7 (milestone 1)
#1432 startcmd.sh broken in 1.7 (milestone 1)
#1433 Profiling filter included multiple times (milestone 1)
#1437 Fatal UTF-8 error in .job.xml (milestone 1)
#1456 XHTML Build failed when referencing subject scheme in different file path (milestone 1)
#1080 Index page range issues (milestone 2)
#1423 Formatting glitch in PDF index (maintenance 2)
#1468 Reference to remote image does not appear in PDF (maintenance 2)
#1469 @outputclass and @class values not passed from <chhead> to <tr> in XHTML output (maintenance 2)
#1472 PDF output: whitespace not preserved in msgblock element (maintenance 2)
#1475 Error received in console does not point correctly to location of published DITA Map (maintenance 2)
#1477 Tables: using percentage in colwidth values [PDF2 plugin] (maintenance 2)

A.4.2 DITA Open Toolkit Release 1.7

General Enhancements and Changes

The minimum Java version has changed from 5.0 to 6.

Added support for abbreviated-form processing in PDF.

X/HTML processing code has been streamlined to make it faster and easier to read.

Ant proprocessing dependencies have been cleaned up to make tasks easier to use independently.

Numerous internal improvements not directly visible to most end users; see feature and patch list for details.

Preprocessing

By default, DITA-OT no longer normalizes file extensions to .xml. Temporary files will retain the original file extensions, unless dita.ext parameter is used to force file extension normalization to a given value.

Key name validation has been added. If an invalid key name is found, DOTJ055E error is thrown.

Migration from previous releases

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 have been removed:

dita.input
dita.input.dirname
dita.extname

Stylesheets for the following transtypes 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 transform 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 transform 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" in the DITA-OT pre-processing architecture section 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 transform 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" in the DITA-OT pre-processing architecture section for details on how to add flagging support.

PDF

The following deprecated XSLT variables have been removed:

page-margin-left
page-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 behaviour was incorrect and was removed to comply with the DITA specification.

The following variable strings have been added:

#note-separator

Issues

The following items are included in DITA Open Toolkit Release 1.7. Issue numbers correspond to the tracking number in the GitHub issues tracker .

Feature requests

#1144 Produce HTML5 output (milestone 1)
#1319 Remove deprecated code (milestone 1)
#1339 PDF, flagged image : change use-attribute-sets="image" (milestone 1)
#1141 XHTML: ability to include TOC in every topic (milestone 2)
#1331 Possibility to customize <stepresult> in HTML output (milestone 2)
#1366 pdf index entries have too many keep-with-previous (milestone 2)
#1379 Use format attribute to identity DITA topics (milestone 2)
#1384 Validate key names (milestone 2)
#1388 Remove temporary file file-extension normalization (milestone 2)
#1288 Use strict integration by default (milestone 3)
#1327 Change minimum Java version to 6 (milestone 3)
#1391 Add new job status file format (milestone 3)
#1398 Allow defining source input base directory (milestone 3)
#1403 Refactor XEP index processing to extend base index processing (milestone 4)
#1405 Provide catalog URL rewrite for common XSL files (milestone 4)
#1313 Separate flagging logic from XHTML code (milestone 4)
#1312 Refactor preprocessing to use SAX filters (release candidate)
#1317 General XHTML improvements (release candidate)
#1324 Avoid strings where other types are more appropriate (release candidate)
#1338 Add named error messages (release candidate)
#1345 Add source location to error messages (release candidate)
#1389 Move stylesheets and resource files to plug-in folder (release candidate)

Patches

#1350 Move table specializations into separate stylesheets (milestone 1)
#1359 Fix text overflow issue in PDF ToC entries with long titles. (milestone 1)
#1352 Wrap itemgroup task elements into <div> elements #1331 (milestone 2)
#1400 Updates on the build instructions plus a fix in one of the dost classes that made the build fail (milestone 4)
#1401 Disable XSD Grammar caching (milestone 4)

Bugs

#1316 Conref error message missing the @conref value (milestone 1)
#1321 Fix path2project separator clean-up (milestone 1)
#1322 Xref to table cell does not properly navigate to it (milestone 1)
#1323 @relcolwidth attribute not taken into account when transforming <choicetable> to PDF using Apache FOP (milestone 1)
#1325 Variable "Index See Also String" missing from Hebrew (milestone 1)
#1329 PDF2 indexing fails for ranges (milestone 1)
#1330 Spaces in Filenames in 1.6 (milestone 1)
#1332 output-deprecated-msg deleted; still referenced (milestone 1)
#1335 Link to see/see also in index is broken (milestone 1)
#1340 The "DitaWriter" class does not properly resolve entities when catalogs are referenced with <nextCatalog> in the catalog-dita.xml (milestone 1)
#1343 Topics with spaces in file name appear twice (milestone 1)
#1346 Cannot determine the title of a xreffed topic (milestone 1)
#1348 Topics copied using "copy-to" become not wellformed (DITA OT 1.6.1) (milestone 1)
#1349 "Ambiguous rule match" in PDF processing XSLT when <choicetable> is used in topic (milestone 1)
#1351 'Unexpected Text' root-processing_axf.xsl bug (milestone 1)
#1353 dita2htmlImpl.xsl/add-br-for-empty-cmd ... content match (milestone 1)
#1354 xml comment not being stripped correctly in preprocessing (milestone 1)
#1357 NPE when image is incorrectly referenced when publishing to HTML (milestone 1)
#1358 Cannot cross reference definition list items (dlentry, dt, dd) in PDF (milestone 1)
#1365 pdf duplicate see-also entries in Index (milestone 2)
#1369 prodinfo seems to lead to "(file) does not exist", where file has spaces in name (milestone 2)
#1370 Links to files with spaces in name broken (milestone 2)
#1371 build_demo uses deprecated Ant property (milestone 2)
#1377 htmlhelp ampersand (&) entity in indexterm does not convert (milestone 2)
#1378 dita.out.map.htmlhelp.hhk: target doesn't allow topic with empty indexterm (milestone 2)
#1382 Merging uses system path separator when rewriting URIs (milestone 2)
#1393 shortdesc in map overrides topic shortdesc (milestone 5)
#1398 Genlist processes file multiple times (milestone 3)
#1402 Foreign and Unknown elements not ignored in PDF (milestone 4)
#1404 buildsample file in TocJS plug-in hard codes old demo path (milestone 4)
#1237 abbreviated-form is not rendered as link to glossentry (milestone 4)
#1193 abbreviated-form not handled at all in PDF output (release candidate)
#1409 Stylesheet imported multiple times in the hierarchy (reloaded) (release candidate)
#1413 Mapref resolution cascades role (release candidate)
#1416 German translation update (release candidate)
#1197 Handling of @href on a <glossarylist> (final release)
#1362 href attribute in appendices element breaks PDF conversion (final release)
#1411 Files with ".orig" extension missing from distribution (final release)
#1418 PDF2 transtype breaks when bookmap has parts (final release)
#1425 XHTML flagging included before imports (maintenance 1)
#1428 Topic level calculated incorrectly for appendices (maintenance 1)
#1427 Fix text overflow issue in lot/lof entries with long titles (maintenance 1)
#1430 PDF transformation: Problems with index in OT 1.7 (maintenance 1)
#1432 startcmd.sh broken in 1.7 (maintenance 1)
#1433 Profiling filter included multiple times (maintenance 1)
#1437 Fatal UTF-8 error in .job.xml (maintenance 2)
#1456 XHTML Build failed when referencing subject scheme in different file path (maintenance 3)
#1423 Formatting glitch in PDF index (maintenance 4)
#1468 Reference to remote image does not appear in PDF (maintenance 4)
#1469 @outputclass and @class values not passed from <chhead> to <tr> in XHTML output (maintenance 4)
#1472 PDF output: whitespace not preserved in msgblock element (maintenance 4)
#1475 Error received in console does not point correctly to location of published DITA Map (maintenance 4)
#1477 Tables: using percentage in colwidth values [PDF2 plugin] (maintenance 4)

A.4.3 DITA Open Toolkit Release 1.6

Release highlights

Performance improvements

DITA-OT 1.6 contains several updates that combine for significant performance improvements for large documents. For example, building the DITA 1.2 Language Specification to XHTML takes just over 1/3 of the time as with the previous release (tests show an improvement of 288%).

Error message overhaul

In the recent DITA-OT usage survey, we asked for specific problems encountered when running the DITA-OT. The most frequent response was difficulty understanding and responding to error messages. The latest release addresses this in two ways:

Every message has been reviewed, and nearly every message has been revised for clarification.
Messages are now documented in the DITA-OT User Guide. The new documentation contains additional details about nearly every message, including potential remedies and links to helpful information.

Code cleanup

Of particular interest to developers, much of the deprecated code in the toolkit (some of it unused for 5+ years) has been removed. As a result, much of the code is cleaner, faster, and easier to customize. For example, the cleanup of PDF code allowed us to remove the alternate *_1.0.xsl stylesheets.

General Enhancements and Changes

New arguments have been added:

args.rellinks controls which related links will be output.
args.filter defines the filter file to be used.

New configuration options have been added:

generate-debug-attributes controls debug attribute generation and can be used to reduce memory consumption.
processing-mode controls error recovery behavior.

Support for the old DITAVAL format (used before OASIS added DITAVAL to the standard in 2007) has been removed.

Source distribution package has been removed in favor or Git and GitHub source downloads.

The demo folder has been deprecated and the following plug-ins have been moved to 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 following plug-ins in the demo folder have been moved to a separate plug-ins Git repository:

FrameMaker_adapter
apiref
authorinfo
book
elementref
enote
faq
java
javaapiref
music
thesaurus
tutorial
video

The following bundled libraries have been updated:

Ant 1.8.4
ICU4J 49.1
Apache Xerces 2.11.0

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.

The following extension-points have been added:

dita.conductor.pdf2.param to add XSLT parameters to XSL FO transformation.

Migration from previous releases

The deprecated property dita.input.valfile should be replaced with the new argument property args.filter.

Target dita-preprocess has been removed and dependencies should be replaced with a target sequence build-init, preprocess.

Support for argument args.message.file has been removed as message configuration has become static configuration.

Processing instruction workdir has been deprecated in favor of processing instruction 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

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.

PDF2

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

Main FO generation now relies on merging process to rewrite duplicate IDs. The default merging has done this already in previous releses, but now also custom merging needs to fulfill the duplicate ID rewrite requirement.

Support for layout-masters.xml configuration has been removed, plug-ins should use createDefaultLayoutMasters template instead.

Issues

The following items are included in DITA Open Toolkit Release 1.6. Issue numbers correspond to the tracking number in the GitHub issues tracker .

Feature requests

#1057 Deprecate logException and add logError(String, Throwable) (milestone 1)
#1059 PDF2 should fully support core default language (milestone 1)
#1058 Add switch to ignore links in XHTML (milestone 1)
#1158 Refactor log messages and tasks (milestone 1)
#1060 Reduce topic merge memory consumption (milestone 1)
#1062 Remove IBM DITA and BookMap demo support from PDF2 (milestone 1)
#1063 Move OT version number to configuration (milestone 2)
#1061 Remove obsolete dita-preprocess target (milestone 2)
#1065 Add index file to PDF2 variables (milestone 3)
#1067 Move Ant scripts to plug-in folders (milestone 3)
#1066 Run XSLT with Ant task in PDF2 (milestone 3)
#762 bookmap.dtd and map.dtd are out of sync with OASIS (milestone 3)
#1068 Add XSLT param extension point to PDF2 (milestone 4)
#948 For PDF output, xml:lang does not work at the element level (milestone 4)
#1064 Support localization of quotation marks in quote (milestone 4)
#1070 Remove support for args.message.file (milestone 4)
#1071 Add automatic font detection to PDF2 (milestone 4)
#1182 Need extension for determining topic level (milestone 4)
#1236 <span> tags added around step when DRAFT on (milestone 4)
#1262 css support for codeph in HTML output (milestone 4)
#1198 Generate PDF metadata from bookmeta (milestone 5)
#1273 Remove source distribution builds (milestone 5)
#1203 ditaval flag action screws strow rendering (milestone 5)
#1104 DitaWriter workdir PI not a URL (milestone 5)
#1252 Document error messages in user guide (milestone 5)
#1278 Separate core and extra plug-ins (milestone 5)
#1249 Add Files from Distribution Packages to Git Repo (milestone 5)
#1283 xref with desc and no href not handled in XHTML (milestone 5)
#1137 Consistent coding conventions for Java code (final release)
#1153 Remove deprecated Ant files (final release)
#1300 Add a hook to set @summary on table in XHTML (final release)
#1302 Add a way for cross-references to pick up generated text for sections (final release)
#1266 Honor the map top level processing instruction (final release)
#1156 Refactor preprocessing to use SAX filters (final release)
#1159 Remove Content object (final release)
#1155 Use Job to read/write job configuration files (final release)
#1160 Improve filtering (final release)
#1124 Make Java code thread-safe (final release)
#1157 Clean Ant scripts (final release)
#1149 Consistent Ant property names (final release)
#1161 Remove deprecated code (final release)
#1162 Improve title numbering in PDF2 (final release)
#1163 Clean PDF2 ID processing (final release)
#1165 Improve PDF2 table customization (final release)
#1166 Improve pipeline module processing (final release)
#1164 Avoid strings where other types are more appropriate (final release)
#1168 Add ability to disable debug attribute generation (final release)
#1249 Add Files from Distribution Packages to Git Repo (final release)
#1243 Support for some kind of die_on_error property (final release)
#1257 Simplify common XHTML code for flag/revision (final release)

Patches

#849 Map references with root fragment are not processed (milestone 1)
#743 Key-based mapref results in preprocessing error (milestone 1)

Bugs

#732 Temp dir with non-ASCII character crashes (milestone 1)
#729 v 1.5.4 fails to create PDF with external topic ref (milestone 1)
#747 [1.5.4]Glosslist no longer visible in Bookmarks (PDF output) (milestone 1)
#733 Incorrect image reference does not checked (milestone 1)
#725 Deprecated property breaks Plus plugins (milestone 1)
#740 Info message about inline flagging not displayed (milestone 1)
#738 NullPointerException when absolute path to image (milestone 1)
#739 PDF2 image references broken with uplevels (milestone 1)
#734 1.5.4 looks for lib dir at current dir instead a ${dita.dir} (milestone 1)
#735 Apache FOP: TOCs with uneven right margin (milestone 1)
#744 Possible collision in File Extension detection mechanism (milestone 1)
#743 Key-based mapref results in preprocessing error (milestone 1)
#753 Choicetable headings not localized in PDF (milestone 2)
#754 Check all places where output streams are used in dost.jar (milestone 2)
#755 Property noCoderef not declared (milestone 2)
#745 HTML handling of *div does not generate @outputclass (milestone 2)
#750 Stylesheet imported multiple times in the hierarchy (milestone 2)
#752 Warning when using @copy-to in reltable (milestone 2)
#722 Revisions on <plentry> use wrong image for nested <pd> (milestone 2)
#721 Bug in handling of longdescref (milestone 2)
#709 Image files not copied or referenced correctly for eclipse (milestone 2)
#758 Keydefs in non-base folder fails (milestone 3)
#757 Deprecated metadata PICS-Label in XHTML output (milestone 3)
#719 Glossentry makes FO file invalid in PDF output (milestone 3)
#677 Warning given by Saxon EE when processing flag-rules.xsl (milestone 3)
#759 PDF2: preface titles does not pull indexterms. (milestone 3)
#760 startcmd.bat adds dost.jar twice to the CLASSPATH (milestone 3)
#765 XSL for Warning uses wrong attribute set (milestone 4)
#764 steps-unordered doesn't generate heading (milestone 4)
#763 choicetable/@product value output in fo:table (milestone 4)
#1229 Typos in domains_(un)classed.css (in progress)
#1284 Fix broken references in catalog file for PDF publishing (milestone 5)
#1216 Customizing PDF layout-masters in 1.5.3 (milestone 5)
#1177 Extension Point @behavior Not Documented (milestone 5)
#1207 Table colwidth attribute always treated as proportional (milestone 5)
#1101 zh-CN file for PDF puts English strings in output (final release)
#1289 Improve error messages (final release)
#1295 Various errors when using term with keyref in XHTML (final release)
#1294 Use dita.ext instead of dita.extname (final release)
#1297 Mappull doesn't recognize <navtitle> when checking for navtitle for non-DITA resources (final release)
#1191 Text only mode outputs desc content in links (final release)
#1303 Add Java properties file DTD to catalog (final release)
#1308 XHTML flag support missing for linklist, linkinfo, linklist/desc (final release)
#1307 M5 reports "illegal character" for xref that uses space in directory name (final release)
#1152 UNC paths are not supported in input argument (final release)
#1072 URLs not decoded by dost.jar (final release)
#1306 Typo in XSLT mode results in extra fallthrough text for step (final release)
#1321 Fix path2project separator clean-up (maintenance 1)
#1322 Xref to table cell does not properly navigate to it (maintenance 1)
#1323 @relcolwidth attribute not taken into account when transforming <choicetable> to PDF using Apache FOP (maintenance 1)
#1325 Variable "Index See Also String" missing from Hebrew (maintenance 1)
#1329 PDF2 indexing fails for ranges (maintenance 1)
#1330 Spaces in Filenames in 1.6 (maintenance 1)
#1335 Link to see/see also in index is broken (maintenance 2)
#1340 The "DitaWriter" class does not properly resolve entities when catalogs are referenced with <nextCatalog> in the catalog-dita.xml (maintenance 2)
#1343 Topics with spaces in file name appear twice (maintenance 2)
#1346 Cannot determine the title of a xreffed topic (maintenance 2)
#1348 Topics copied using "copy-to" become not wellformed (DITA OT 1.6.1) (maintenance 2)
#1351 'Unexpected Text' root-processing_axf.xsl bug (maintenance 2)
#1353 dita2htmlImpl.xsl/add-br-for-empty-cmd ... content match (maintenance 2)
#1354 xml comment not being stripped correctly in preprocessing (maintenance 2)
#1357 NPE when image is incorrectly referenced when publishing to HTML (maintenance 2)
#1358 Cannot cross reference definition list items (dlentry, dt, dd) in PDF (maintenance 2)
#1365 pdf duplicate see-also entries in Index (maintenance 3)
#1369 prodinfo seems to lead to "(file) does not exist", where file has spaces in name (maintenance 3)
#1370 Links to files with spaces in name broken (maintenance 3)
#1371 build_demo uses deprecated Ant property (maintenance 3)
#1377 htmlhelp ampersand (&) entity in indexterm does not convert (maintenance 3)
#1378 dita.out.map.htmlhelp.hhk: target doesn't allow topic with empty indexterm (maintenance 3)
#1382 Merging uses system path separator when rewriting URIs (maintenance 3)

A.4.4 DITA Open Toolkit Release 1.5.4

General Enhancements and Changes

Configuration file for defaults

In previous versions, lib/configuration.properties was generated by 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.

Plug-in extension point for file extension configuration

New plug-in extension points have been added allow configuring DITA-OT behaviour 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.

New plug-in extension point has been added to allow declaring transtypes as print types.

Extension point	Description
`dita.transtype.print`	Declare transtype as a print type.

Strict integration mode

Two modes have been added to integration process: lax and strict. In strict mode the processing will fail if any errors are encountered. In lax mode an error message may be thrown for an error and the integration process will try to run to the end, even if there are errors that were unrecoverable. The default mode is lax.

Note

In lax mode, even if the process runs to the end and reports a successful result, DITA-OT may not be able to function correctly because of e.g. corrupted plug-in files or unprocessed template files.

Code reference charset support

Encoding of the code reference target file can be set using the format attribute, for example

<coderef href="unicode.txt" format="txt; charset=UTF-8"/>

Plugin URI scheme

Support for 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"/>

PDF

Support for mirrored page layout has been added. The default is the unmirrored layout.

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 I18N font processing and use stylesheet defined fonts. To disable I18N font processing, set org.dita.pdf2.i18n.enabled to false in configuration properties

XHTML

Support for the following languages has been added:

Indonesian
Kazakh
Malay

Migration from previous releases

To allow access to configuration files, the lib directory needs to be added to Java classpath.

The print_transtypes property in integrator.properties has been deprecated in favor of dita.transtype.print plug-in extension point.

The dita.plugin.org.dita.*.dir properties have been changed to point to DITA-OT base directory.

PDF

Support for mirrored page layout was added and the following XSLT configuration variables have been deprecated:

page-margin-left
page-margin-right

The following variables should be used instead to control page margins:

page-margin-outside
page-margin-inside

XSLT Parameters customizationDir and fileProfilePrefix have been removed in favor of 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.

SourceForge trackers

Feature requests

3333697 Add strict mode processing (Milestone 1)
3336630 Add resource file extension configuration (Milestone 1)
3323776 Base HTML stylesheets (Milestone 1)
3355860 Enable defining code ref target encoding (Milestone 1)
3393969 Make default TocJS output more usable (Milestone 3)
3394708 cfg/catalog.xml should be an extension point (Milestone 4)
3411030 Add args.fo.userconfig to PDF2 (Milestone 5)
3411961 Change margin-* to space-* property (Milestone 5)
3412144 Add FOP specific shell to PDF2 (Milestone 5)
3413215 Add schemas for PDF2 configuration files (Milestone 5)
3414416 Support bookmap order in PDF2 front and back matter (Milestone 5)
3413933 Fix inconsistencies in PDF2 page headers (Milestone 5)
3418877 Mechanism to refer to other plug-ins in XSLT (Milestone 5)
3411476 Add extension point for print type declaration (Milestone 6)
3392891 Copy the graphic files to the temporary folder (Milestone 6)
3429290 Remove unused Apache Commons Logging JAR (Milestone 6)
3434640 Add XHTML NLS support for Indonesian, Malay, Kazakh (Milestone 6)
3435528 Add base configuration file (Milestone 7)
3432219 Refector dita.list read and write (Milestone 7)
3401849 PDF2: runtime switch for localization post-processing (Milestone 7)
3438361 Add "tocjs" transform to demo script (Milestone 7)
3341648 Clean HTML and XHTML stylesheets (Milestone 8)
3343562 Java clean-up (Milestone 8)
3346094 Improve test coverage (Milestone 8)
3372147 Improve logging (Milestone 8)
3373416 Refactor PDF attribute sets (Milestone 8)
3376114 Improve PDF page layout configuration (Milestone 8)
3415269 Support for more languages in the PDF transform (Milestone 8)
3412211 Refactor PDF index stylesheet for XSL 1.1 support (Milestone 8)
3425838 General PDF2 improvements (Milestone 8)
3428152 General I18N improvements (Milestone 8)
3429390 General XHTML improvements (Milestone 8)
3438790 Clean up build_demo script (Milestone 8)
3440826 Dutch patch for feature request 3415269 (Milestone 8)
1785391 Make Java code thread-safe (in progress)

Patches

2963037 PDF changes to fix index rendering of colon (bug 2879196) (Milestone 7)

Bugs

2714699 FO plug-in doesn't support specialized index elements (Milestone 1)
2848636 Duplicate key definitions should produce info messages (Milestone 1)
3353955 Frontmatter child order is not retained in PDF2 (Milestone 1)
3354301 XRef with conreffed phrases not properly generate HTML link (Milestone 1)
3281074 Bad attribute being applied to fo:bookmark-title element (Milestone 2)
3344142 Conref Push order of validation (Milestone 2)
3358377 Cryptic error message when DITA Map has "bookmap" extension (Milestone 3)
3384673 ODF transtype no longer embeds images in output (OT 1.5.3) (Milestone 3)
3394000 TocJS needs cleanup for several minor bugs (Milestone 3)
3392718 TOCJS sample should not require ant target (Milestone 3)
3389277 DocBook transform redundantly nests Related Links (Milestone 3)
3105339 '<' and '>' characters in a title cause tocjs trouble (Milestone 3)
3104497 tocjs JavaScripts don't work in Japanese environment (Milestone 3)
3394130 Remove outdated developer documentation (Milestone 3)
3397165 chunk on topichead not honored (Milestone 4)
3397501 Custom reltable column headers are reversed (Milestone 4)
3397495 Relcolspec with <title> does not generate link group headers (Milestone 4)
3399030 <ph> Elements not flagged with alt-text in HTML output (Milestone 4)
3396884 NPE in EclipseIndexWriter.java<Merges,setLogger for AbstractIndexWriters (Milestone 4)
3398004 -d64 flag to JVM not allowed for Windows JVMs (Milestone 4)
3401323 Fix PDF nested variable handling (Milestone 4)
3401721 Processing broken for <topicsetref> elements (Milestone 4)
3404049 Setting of clean_temp is backwards (Milestone 4)
3386590 Product name repeated hundreds of times in PDF (Milestone 4)
3405417 Shortdesc output twice when using abstract (Milestone 4)
3402165 wrong image output dir if using generate.copy.outer=2 (Milestone 4)
2837095 Positions of index and TOC in bookmaps are ignored (Milestone 5)
3414826 DITA OT not handling image path with chunking turned on (Milestone 5)
3411767 Not so meaningful messages given by ImgUtils (Milestone 5)
3405851 Incorrect entry@colname in merged XML with row and colspan (Milestone 5)
3406357 Custom profiling issue (Milestone 5)
3413203 Remove references to OpenTopic in PDF2 (Milestone 5)
3414270 @props specialization not used in map (Milestone 5)
3383618 Attribute 'link-back' cannot occur at element 'fo:index-key (Milestone 5)
3418953 Scale computation for XHTML uncorrectly looks up images (Milestone 6)
3413229 onlytopic.in.map & symlink (Milestone 6)
3423537 Additional line breaks in <menucascade> should be ignored (Milestone 6)
3423672 Problems with refs to images outside the DITA Map directory (Milestone 6)
2879663 indexterm/keyword causees NullPointerException (Milestone 7)
2879196 Colon character in <indexterm> causes nesting in output (Milestone 7)
3179018 Indexterm with only nested subelement results in NPE (Milestone 7)
3432267 Task example title processing incorrect for PDF (Milestone 7)
3430302 Unitless images sizes in throw errors (Milestone 7)
3429845 No variables for Warning (Milestone 7)
3428871 topicmerge gives incomplete topicref when reference or topic (Milestone 7)
3132976 Duplicate index text in index page (Milestone 7)
2795649 Java topicmerge ignores xml:lang (Milestone 7)
3431798 Relative CSS paths incorrectly computed for @copy-of (Milestone 7)
3438421 Remove transtype default (Milestone 7)
2866342 Nested see also is ignored (Milestone 8)
1844429 PDF2: Non-DITA link broken unless marked external (Milestone 8)
3270616 "lcTime" not displayed in PDF output (Milestone 8)
3388668 Data in figure captions not suppressed in xrefs (Milestone 8)
3429824 topicmerge gives wrong topicref with nested topics (Milestone 8)
3414332 PDF2 variable string translations missing (Milestone 8)
3323806 Improve Java logging and exception handling (Milestone 8)
3426920 Image files not copied or referenced correctly for eclipse (Milestone 8)
3445159 entry/@colname has been removed! (Milestone 8)
3447732 Bug in handling of longdescref (Milestone 8)
3452510 Ant parameter customization.dir not documented anywhere (Milestone 8)
3451621 Revisions on <plentry> use wrong image for nested <pd> (Milestone 8)

A.4.5 DITA Open Toolkit Release 1.5.3

Release 1.5.3 is a maintenance release based on the final version of the DITA 1.2 standard.

Version 1.5.3 contains many enhancements, user patches, bug fixes, and significant updates to the documentation.

Release 1.5.3 was developed using a series of test builds released to the community every three weeks. Each item in the list below indicates which test build first contained the update. The eighth public build was the final build, released as the DITA-OT 1.5.3 final stable build.

General Enhancements and Changes

Base plug-ins

In earlier releases of OT, configuration parameters were hardcoded into Ant files and Java code. Starting from version 1.5.3 OT has externalized base configurations into base plug-ins in plugins folder. Base plug-in identifiers and folder names start with org.dita:

org.dita.base
org.dita.docbook
org.dita.eclipsecontent
org.dita.eclipsehelp
org.dita.htmlhelp
org.dita.javahelp
org.dita.odt
org.dita.pdf
org.dita.troff
org.dita.wordrtf
org.dita.xhtml

For backwards compatibility, only configuration files were moved to plug-in folders, the actual code and resource files were left in original locations.

Installations of OT may remove base plug-ins in order to remove funtionality, but the org.dita.base plug-in must be retained as it contains configuration for base functionality such as catalog files and preprocessing.

Plug-ing configuration changes

The plug-in configuration file plugin.xml has support for new syntax, where the old

<feature extension="foo" value="bar.xml" type="file"/>

can be written as

<feature extension="foo" file="bar.xml"/>

The new file attribute only supports a single file, not a comma separated list like the value attribute.

In previous releases multiple feature elements with the same extension ID were not supported. In release 1.5.3 multiple definitions are combined, thus

<feature extension="foo" value="bar,baz"/>

can also be written as

<feature extension="foo" value="bar"/>
<feature extension="foo" value="baz"/>

Plug-in extension points can be added with

<extension-point id="extension-id" name="human readable name"/>

Plug-ins should declare all extension points they support. In version 1.5.3 undeclared extension points are supported, but a warning is thrown when running integration in verbose mode. Support for undeclared extension points may be removed in future releases.

PDF2 changes

Support for the format attribute in PDF2 variable files has been remove as redundant. The same functionality as

<variable id="foo" format="bar">baz</variable>

can be implemented with e.g.

<variable id="foo.bar">baz</variable>

PDF2 no longer logs a warning about PDF2 plug-in replacing the legacy PDF transformation type.

Support for flagging has been added.

Version of FOP that comes with Full Easy Install has been updated from 0.95 to 1.0.

Filtering configuration

List of transtypes which are considered to be print types has been moved to integrator.properties with the property name print_transtypes. In previous releases this list was hardcoded into Java code. Configuring print transtypes is currently not possible in plug-in configuration files.

Java API changes

Multiple Java classes have been changed from public non-final into package-private final. This enables clearer distinction between public and internal API, and forbits subclassing classes which have not been designed and documented for extensibility.

SourceForge Enhancements Added

3177971 Improve plugin configuration file (Milestone 2)
3178275 Add xsl:import extension point to PDF2 topic merge XSL (Milestone 3)
3182113 Add common attribute processing to PDF2 plugin (Milestone 3)
3185914 Improve integration loggin (Milestone 3)
3189073 Plugin location should be available as Ant property (Milestone 3)
3126848 Repository cleanup (Milestone 3)
3204188 Support for defining extension point (Milestone 4)
3213163 Clean PDF2 build and integration scripts (Milestone 4)
3227387 Need extension to pass user param to dita.map.xhtml.toc targ (Milestone 4)
3231695 Use an XML serializer object for writing XML (Milestone 4)
3256796 Remove lecagy PDF code from xsl (Milestone 4)
3283638 Remove format attribute support from PDF2 vars (Milestone 5)
3285716 Clean up PDF2 build files (Milestone 5)
3286085 Add output and temp dir params to PDF2 (Milestone 5)
3293738 Use extensible pipeline task implementation (Milestone 6)
3271552 ${args.xsl.pdf} as an absolut path not supported (Milestone 6)
3033000 update to Apache FOP 1.0 release (Milestone 6)
3213324 Separate FOP/XEP/AXF stylesheets in PDF2 (Milestone 6)
3302779 Dependency extension points for PDF2 formatting (Milestone 7)
3304945 Allow setting local overrides with properties file (Milestone 7)
3190356 Pluginize DITA-OT base configuration files (Milestone 8)
3167087 Reduce static variable usage in Java code (Milestone 8)
3158929 Java clean-up (Milestone 8)
3194917 Change Java API to be more final and non-public (Milestone 8)
3197328 Refactor writers for cleaner XML serialization (Milestone 8)
3199755 Improve log integration (Milestone 8)
3296040 Refactor PDF2 build files (Milestone 8)
3306146 PDF2 stylesheet refactoring (Milestone 8)
3304447 Add support for selecting output format in PDF2 (Milestone 8)
3310476 Add plug-in ID and version syntax check (Milestone 8)
3309275 Warning reported by Apache FOP on any topic (Milestone 8)
3305843 Support list of tables/figures in PDF2 (Milestone 8)

SourceForge Patches Added

3123507 String concat in map2plugin (Milestone 1)
3110513 HTML XSLT uses complex casts (Milestone 1)
3097677 Add property to reload XHTML stylesheets (Milestone 1)
3106659 Added topicgroup elements to tocjs (Milestone 1)
3109051 RestoreEntity duplicates functionality (Milestone 1)
3107755 Configure templates with integrator properties (Milestone 1)
3142967 IndexTermReader leaves tab characters in terms (Milestone 1)
3140543 Add missing Commons Codec JAR into compile classpath for buildPackage.xml (Milestone 1)
3087664 Clean plugin configuration parser (Milestone 1)
3145258 Plug-in integrator code clean-up (Milestone 2)
3147226 Use common directory layout for Junit (Milestone 2)
3062765 Fix unit test file paths to be platform dependent (Milestone 2)
3164523 Refactor platform Java code (Milestone 2)
3160801 Improve unit test coverage (Milestone 8)
3189026 Avoid strings where other types are more appropriate (Milestone 8)

SourceForge Bugs Fixed

3114411 keyref links don't work for HTML Help (Milestone 1)
3126578 Chunking Issues in DITA 1.5.1 (Milestone 1)
3109616 More Antenna House Path Problems (Milestone 1)
3155375 Incorrect way to specify recognized image extensions(Milestone 2)
3157890 Navtitle Construction Does not Preserve Markup (Milestone 2)
3155848 xml decl in ditaval file not closed properly (Milestone 2)
3162808 Chunking remaps in-file <xref> to invalid value (Milestone 2)
3164866 Upper letter estensions (Milestone 2)
3165307 Add boilerplate to Java files (Milestone 2)
2793836 CHM Index terms come out with extra spaces (Milestone 2)
3165762 Initializer XMLReader without modifying system variables (Milestone 2)
3175328 Imagemap alt text gets extra text (Milestone 2)
3085106 FO: topicmerge drops id on map/topicref without href. (Milestone 2)
3147328 Error in commons.xsl: getTopicrefShortdesc (Milestone 2)
3130724 Error in tables.xsl: fix-relcolwidth (Milestone 2)
3174906 Normalize Map and Bookmap titles for JavaHelp output (Milestone 3)
3178361 Conkeyref push fails when equivalent conref push succeeds (Milestone 3)
3180681 PDF2: Inconsistent template import / include. (Milestone 3)
3191701 Conref Push to Same File Fails (Milestone 3)
3191704 Push Replace Results in Pushed element Being removed (Milestone 3)
3189883 MapLinksReader should not be namespace aware (Milestone 3)
3164587 Warnings issued by Saxon 9.3.0.4 when publishing to PDF (Milestone 3)
3159001 Clean unit tests (Milestone 4)
3199985 @chunk : xrefs and links break (Milestone 4)
3206158 Inconsistent message DOTJ038W (Milestone 4)
3206373 Better handling of referenced SVG images (Milestone 4)
3279539 Out of memory error from move-meta module (Milestone 5)
3281108 Fallback to $locale when xml:lang value is wrong format (Milestone 5)
3286679 ODT output transform deletes too many files (Milestone 6)
3287609 Chunking rewrites image based on map directory (Milestone 6)
3288639 Conref code improperly generalizes map domain elements (Milestone 6)
3294295 PDF2 indexing and I18N fails with missing languages (Milestone 6)
3294864 tocjs-demo: tocjs.ditamap is referencing a missing file (Milestone 6)
3297930 PDF2: axf specific templates can't be overridden. (Milestone 7)
2001271 DITA-OT documentation wants Ant 1.6.5 (Milestone 8)
3136773 Incorrect version reported in log file (Milestone 8)
3260746 Topichead not processed the same as title-only topic (Milestone 8)
3315029 Garbled character problem in Japanese HTMLHelp (Milestone 8)
3308775 Keyref map in grandparent folder fails (Milestone 8)

A.4.6 DITA Open Toolkit Release 1.5.2

Release 1.5.2 is a maintenance release based on the final version of the DITA 1.2 standard.

Release date: December 10, 2010
Supports: DITA 1.0 through 1.2
Download at: DITA-OT Latest Stable Build
Which package is for me? See DITA-OT Packages.

In addition to tweaks to match late changes in the standard, version 1.5.2 contains many enhancements, user patches, bug fixes, and significant updates to the documentation.

Release 1.5.2 was developed using a series of test builds released to the community every three weeks. Each item in the list below indicates which test build first contained the update. The eighth build was the final build, released as the DITA-OT 1.5.2 final stable build.

General Enhancements

Include final version of DITA 1.2 schemas and DTDs
Minor updates to DITA 1.2 support added in earlier releases, to ensure compliance with the final standard
Overhaul of documentation to remove outdated material
Reorganization of doc directory to highlight new and important info

11 SourceForge Enhancements Added

2797337 Support for ODF output transform (Prototype added in version 1.5.1, updates in each 1.5.2 Milestone, transform complete in Milestone 7)
3021544 Preserve DITA elements in XHTML class by default (Milestone 1)
3019853 Create new "textonly" output method for use by any transform (Milestone 1)
3012392 PDF transformation should allow args.xsl style override (Milestone 1)
2882123 Add Ant Quick Start Guide to DITA-OT (Updated in each Milestone after 3)
3086936 Add extension points for TOC output (Eclipse TOC, HTML Help TOC and Project, HTML TOC) (Milestone 6)
3079610 Add current OT version to log (Milestone 6)
1520909 HTML Help requires appropriate codepage (Milestone 6)
3125994 Allow PDF index conf. to be overridden in Customization (Milestone 7)
3125983 Create a basic glossary implementation for PDF (Milestone 7)
3109395 Add parameter for Eclipse symbolic name (Milestone 8)

SourceForge Patches Added

3058008 Refactor chunk module for cleaner code (Milestone 4)
3067681 Add class to ordered child links (Milestone 5)
3064412 Integrator fails to escape XML correctly (Milestone 5)
3062765 Fix unit test file paths to be platform dependent (Milestone 5)
2949860 PDF build.xml with args for JVM memory and architecture (Milestone 6)
3077935 Plug-in ignore in Integrator (Milestone 6)
3065050 Common logging interface (Milestone 6)
3063318 ChunkModule refactoring (Milestone 6)
3061100 Define AbstractPipelineInput's function (Milestone 6)
3102905 Move supported image extensions to configuration file (Milestone 7)
3097518 Show effective property values (Milestone 8)
3101335 apiMap.mod missing from catalog (Milestone 8)

SourceForge Bugs Fixed

2928582 commonTopicProcessing template prolog processing out of order (Milestone 1)
2823221 version of Xalan-J inconsistent (Milestone 1)
3023642 Invalid @colname generated in nested table (Milestone 1)
3016739 Chunking mixes up <link> to topic in reltable (Milestone 1)
3020314 Chunk output includes index terms in navtitles (Milestone 1)
3020313 Chunk processor adds <topicref> before <topicmeta> (Milestone 1)
3031513 Nested table processing in pdf2 (Milestone 2)
3030317 Filtering doesn't work on @rev or @props attributes (Milestone 2)
3028650 Replace xs:float with xs:double in Plus plugins (Milestone 2)
3022847 PDF transform gives Java exceptions for spaces in dir name (Milestone 2)
3032950 Scale is not correctly computed in XHTML transforms (Milestone 2)
3033141 dita.xml.properties file not closed after generating (Milestone 2)
3034445 "CURRENDIR" typo in plus-plugins ( Checked in to CVS during Milestone 3)
3034489 Remove all occurrences of <xmlcatalog> from plus-plugins ( Checked in to CVS during Milestone 3)
3035816 When creating .chm, .hhp-file is missing a line-break (Milestone 3)
3036222 RTF transform not editable with Word 2007 (Milestone 3)
3036985 Infinite recursivity in replaceString template (Milestone 3)
3038941 Link with & breaks in abstract (Milestone 3)
3039017 Comments in PDF plugin files are confusing (Milestone 3)
3058124 Toolkit Allows Unescaped URLs, doesn't handle escaped ones (Milestone 4)
3056939 Conref of keyref-based xref results in xref with no href (Milestone 4)
3052913 Multiple levels of keyref in map not resolved (Milestone 4)
3052904 Keydef with no href causes hard failure (Milestone 4)
3052156 Object with data that starts with slash breaks image copying (Milestone 4)
3044861 Inappropriate warning for resource-only topic to graphic (Milestone 4)
3042978 @copy-to and @chunk on topichead gives file not found (Milestone 4)
3016994 The included-domains entity cannot be used in document (Milestone 4)
2994593 Transformation breaks when DITA Topics contain entity refs (Milestone 4)
3028894 no support for title in plugin.xml file (Milestone 4)
3065853 Indent from <title> gets displayed in TOC (PDF) (Milestone 5)
3065486 CURRENTFILE not aware of DITAEXT (Milestone 5)
3065422 Wrong filename and filedir parameters for eclipse xsl (Milestone 5)
3063533 Adjacent words get glued together using DITA to RTF (Milestone 5)
3062912 Messages extension damages custom message formatting (Milestone 5)
3059256 Peer links break with missing format or wrong extension (Milestone 5)
2972393 Need to parameterize maxmemory and VM args for forked JVMs (Milestone 6)
3060269 Problem displaying French content TOC in CHM output (Milestone 6)
3038412 zh-CN file for PDF puts English strings in output (partial fix) (Milestone 6)
3079676 <navtitle> contents included in PDF output (Updated so that <navtitle> in a topic will only appear when the draft parameter is set to 'yes') (Milestone 6)
3004895 XHTML output for <draft-comment> should use class attribute (Milestone 6)
2794487 No Easy Way to Override/Extend HTML TOC Navtitle Generation (Milestone 6)
3088314 Need to clarify many error messages (Milestone 6)
3095233 Shortdesc metadata missing when using abstract (Milestone 6)
3081597 conkeyref accepts values in conref style (Milestone 6)
3081459 fragment generation without plugin fails (Milestone 6)
3073262 missing terminating quote in bundle version (Milestone 6)
2832863 <group> elements in catalogs don't work for all editors (Milestone 6)
3038933 Troff output drops prereq links (Milestone 7)
3098975 Disable Output Escaping Should Not Be Used (Milestone 7)
3102827 Allow a way to specify recognized image extensions (Milestone 7)
3102219 Unexpected character code in Japanese string definition (Milestone 7)
3101964 Unnecessary XML declaration in HHP and HHC (Milestone 7)
3095233 Shortdesc metadata missing when using abstract (Milestone 7)
3097409 PDF should skip empty columns in property tables (Milestone 7)
3090803 PDF fails when chunk specified and topic appears twice (Milestone 7)
3102845 Japanese character-set definition (Milestone 7)
3103488 Update Saxon command line args for IDIOM PDF build.xml (Milestone 7)
3026627 side-col-width variable has no effect (Milestone 7)
3126007 TOC entries not properly indented in PDF (Milestone 7)
3109616 Update PDF plug-in to check for latest Antenna House dirs (Milestone 8)
3056040 problematic Bundle-Version test in eclipseMap (Milestone 8)
3029074 Index file not generated by default for Eclipse Help (Milestone 8)
3086552 XMLReader.parse does not correctly receive the XML system ID (Milestone 8)
3110418 Duplicate @colname generated for entry (Milestone 8)
3114353 Java sun.* packages should not be used (Milestone 8)

A.4.7 DITA OT Release 1.5.1

Release 1.5.1 is a maintenance release based on Committee Draft 01 of the DITA 1.2 standard.

Release date: June 18, 2010
Supports: DITA 1.0 through 1.2 (Committee Draft 02 level)
Download at: DITA-OT Latest Stable Build
Which package is for me? See DITA-OT Packages.

This is the same version of the standard used for the DITA 1.2 Public Review. Release 1.5.1 contains many fixes and minor enhancements. It also includes a preview of a new output transform to the Open Document Format; this transform will be completed in a later release.

Release 1.5.1 was developed using a series of test builds released to the community every three weeks. Each item in the list below indicates which test build first contained the update. There were seven total test builds.

General Enhancements

Update to latest copy of DITA 1.2 Draft DTDs and Schemas (last update in Milestone 5)

14 SourceForge Enhancements Added

2797337 Support for ODF output transform (first prototype available in Milestone 2, further updates in each milestone)
2703335 Reduce duplicated code in XHTML <note> processing (Milestone 3)
2976463 Provide finer grained control of links in PDF (include reltable and in-topic links, without parent/child links) (Milestone 4)
2971536 New Java options for existing Ant parameters (Milestone 4)
2979084 Obey the "args.draft" parameter (Milestone 5)
2990783 allow caller-provided IndexTermCollection (Milestone 6 contains the core code updates; M7 contains the full enhancement)
3001750 Shortdesc from map should override link description in PDF (Milestone 7)
3004305 Notes with type="warning" need styling / localization in XHTML (Milestone 7)
3004859 "eclipsecontent" transform should drop debug info (Milestone 7)
2892706 Don't delete the FO file (new option to preserve topic.fo) (Milestone 7)
2928584 Add general model for end-of-topic processing in PDF (Milestone 7)
3006675 Support new DITA 1.2 <stepsection> element in PDF (Milestone 7)
3006847 Add generated task headers to PDF (using the option that works for XHTML in DITA-OT 1.5) (Milestone 7)
2987769 Add support for Eclipse Help index redirects (Milestone 7)

2 SourceForge Patches Added

2914475 Use Xerces Grammar Pool to Improve Performance (Milestone 1)
2991688 Refine package build Ant (Milestone 6)

46 SourceForge Bugs Fixed

2916469 @locktitle not respected by preprocessor (Milestone 1)
2917809 need empty lib/saxon directory for minimum and standard pkg. (Milestone 1)
2925636 Build fails when excluded section contains a table (Milestone 1)
2926417 Absolute file: URLs are not resolved. (Milestone 1)
2930109 Move meta module pushes content into peer topic. (Milestone 1)
1852808 args.css requires dummy file. (Milestone 1)
2952956 Imagemap processing drops outputclass from image (Milestone 3)
2953706 Minor improvements to "garage" samples (Milestone 3)
2961909 /onlytopicinmap does not respect conref (Milestone 3)
2957456 conkeyref breaks when topic is in subdir (Milestone 3)
2962813 stepsection throws off numbering in links to steps (Milestone 3)
2959588 Template Processor Doesn't handle XSLT atts that require ' (Milestone 3)
2914574 plus-htmlhelp-alias-map: using same extension point twice (Milestone 3)
2957938 coderef not working everytime (Milestone 3)
2962781 html documentation out of date (Milestone 3)
2952956 refactored XSL code in ut-d.xsl (Milestone 3)
2954819 NullPointer while processing simple BookMap (Milestone 3)
2954154 Updated default version from 1.0 to 1.0.0 (Milestone 3)
2970471 XSLFO test for @compact wrong (Milestone 4 for PDF, Milestone 5 for LegacyPDF)
2972043 Setting onlytopicinmap causes a blank imagelist (Milestone 4)
2974667 Integrator adds spaces into XML Catalog entries (Milestone 4)
2986492 Duplicate parameter in XHTML code (Milestone 5)
2982485 Cannot read a document that was written during the same transform (Milestone 5)
2981216 <tm> @tmclass requires IBM-specific values (Milestone 5)
2979361 Java stack traces in OT log (Milestone 5)
2979328 Output parameters info at INFO level (Milestone 5)
2978858 keyref processing doesn't respect basedir (Milestone 5)
2990162 Conref to elements in same DITA file throw parsing errors (Milestone 6)
3000677 msgph and systemoutput should use <samp> instead of <tt> (Milestone 7)
3004220 <tm> elements dropped when keyref text resolved (Milestone 7)
2987322 Navtitle attribute of glossarylist breaks PDF (Milestone 7)
2916474 Inappropriate match on mapgroup/topichead in PDF code (Milestone 7)
2916408 Topichead with <navtitle> not processed same as @navtitle in PDF (Milestone 7)
3006443 CSS for prereq links indents prereq element (Milestone 7)
2607892 (Plus Plug-in) plus-allhtml-encoding: map x-windows-950 to Big5 (Milestone 7)
2385466 Handle @font-family="inherit" (Milestone 7)
2928540 Shortdesc should align with body in PDF (use topic__shortdesc) (Milestone 7)
1839827 PDF does not properly process <xref> to <li> elements (Milestone 7)
2521819 PDF topic title widowed due to fo:marker placed in separate block (Milestone 7)
1385654 docbook/topic2db.xsl - better linking support (Milestone 7)
3004550 Conkeyref does not work if key referenced is not in same folder (Milestone 7)
3004060 keyref/id not producing link in PDF output (Milestone 7)
3001705 conkeyref doesn't work across ditamaps (Milestone 7)
3000604 Legacy PDF: empty @column-number causes errors (Milestone 7)
3013079 Keyref handling does not respect scope="external" (Final build)
3005748 XHTML: Topics w/ @print set to "printonly" are included (Final build)

A.4.8 DITA OT release 1.5

Release 1.5 is a major release based on the new DITA 1.2 draft standard.

It contains full support for DITA 1.2 draft as defined in the fall of 2009 (prior to public review).

In addition to DITA 1.2 support, release 1.5 contains the following updates, which are available in Milestone 21 or earlier of the DITA-OT test builds:

General Enhancements

New parameter to generate output for only the topics referenced in a map
Use fileparameter in Ant 1.7 to replace processing instruction in intermediate dita files
Determine the version of DITA-OT via the class org.dita.dost.util.Version
Remove duplicate ids in PDF topicmerge
Move Notices before the TOC, suppress in the TOC and suppress the second copy after the TOC
Include @scope="peer" condition when creating rel-links.

SourceForge Enhancements Added

2859612 Add support for Serbian (Latin)
2845278 Add Ant parameters for XSLT parameters
2824371 Support Hindi and Urdu for XHTML output
2790755 Process in unique temp directories (Designed to allow multiple builds to take place at once)
2780998 startcmd.sh: Run the user's shell, not sh
2698921 Add a way to set attributes on <body>
2120219 Add PDF to the supported image
2002857 homeID in javahelp .hs file is not set
1725284 add support for headings for sections within task (XHTML only)
1623246 Support RFC4646 language tags in Index modules
1367897 Xref content generation enforces formatting choices
2882109 Convert named PDF templates to mode template
2883406 Add extension point for modifying PDF link text
2882870 Add parameter to control PDF Chapter style
2882103 Provide hook for specializations to add custom headers
2882072 Add parameter to control PDF bookmarks (default collapsed)

93 SourceForge Bugs Fixed

2860433 Keyref on <image> fails to resolve
2860199 Chunk to-content in submap resulting in missing output
2860168 Suppress data and data-about in PDF output
2857167 conrefImpl.xsl 1.6.4.13 has duplicate variable decls
2856742 Problem of keys attribute in nested topicref elements
2854546 Peer xref leads to invalid destination error in PDF
2849200 Style on ditaval prop or revprop is ignored
2846111 Unnecessary text generated for external xref
2845598 1.5-M18-demo/fo/Customization pdf.formatter
2842753 catalog-dita.xml has invalid entries
2839035 Chunk code cannot parse xref with &
2832696 Move meta module pushes content into non-DITA file
2829350 Build_demo.xml places files in incorrect directory
2826143 Move meta module discards link text
2824907 1.5 M17 Bug - FileNotFoundException export.xml eclipsehelp
2819853 missing nested indexterm after 3rd
2815492 PDF: keep-with-next on shortdesc
2815485 Prolog indexterm not processed properly for PDF
2813082 Eclipse help MANIFEST.MF filename wrong case, needs CRLF
2811980 pdf2: japanese translate for generated page number of a ref
2811358 Incorrect entry@colname in middle file at PDF generation
2804442 Bad param name in prereq-fmt template's call to sect-heading
2799543 Child links in HTML Help output are wrong
2797030 Chunking fails with bookmap
2796614 Leading slash breaks PLUGINS_ROOT usage for Eclipse help
2791696 reltable DITA 1.2 (#12048)
2791345 Topicmeta searchtitles in map not used in topic
2791278 Keyref Resolution Fails for Non-Descendant Topics
2790807 Demo code should use new PDF output
2788069 Topicmerge does not handle copy-to properly
2788069 Topicmerge does not handle copy-to properly
2782503 Extra space before bullet list in xhtml output DITA-OT 1.4.3
2774128 startcmd.sh is encoded with DOS line endings in v1.5 M13
2759964 HTML outputs filters conditional topics poorly
2759964 HTML outputs filters conditional topics poorly
2748371 Revision + ID gives XSL error
2739236 plus-allhtml-svgobject handles <alt> badly
2724090 XHTML: conreffed by-reference footnotes break w/ chunking
2723928 gen-toc template not matching properly
2723715 Itemgroup sets @id when element is not open
2712074 XHTML: chunk=to-content on map breaks by-reference footnotes
2706725 Single quote inserted in empty table cells in FO
2696229 FO plugin code incompatible with Saxon 9 (OT1.4.3 default)
2696191 Java libraries missing from 1.4.3 distributions
2647292 HTML stylesheets should style <wintitle> and <filepath>
2629271 maplink: should not modify href if scope=external
2629256 mapref: should not modify href if scope=external
2573681 Move link module does extra processing
2547437 zh_TW.properties and zh_CN.properties contents are mixed up
2418932 toc attribute does not work for references to ditamaps
2317681 Extra files generated when many topics are chunked to one
2317581 inline formatting in shortdesc
1931457 Need to identify transtype during XHTML output step
1629094 docbook creates empty simplelists
1628936 transtype=docbook does not handle publisher and copyright element
2849078 Problems using keyrefs with DITA OT 1.5 M19 - ID: 2849078
2875373 tm in linktext is dropped
2870935 keyref within topics ignore @copy-to attributes
2873560 SWF flash not defined as resources to be copied
2872954 Conref push not working at map level
2871009 Temp directory leaves behind single directory and file
2866322 Generated links have bad URLs
2873654 PDF missing rules for new DITA 1.2 content elements
2872988 Bad relcolwidth crashes PDF output
2866204 Topicref with keyref fails to produce output
2878446 Issue with ampersand in xrefs in attributes
1629096 docbook creates invalid varlistentry
2871326 Cannot use different TOC titles for same topic in PDF
1880097 PDF2 ingnores contents of <xref> elements
1815571 Invalid property in fo:table-body
2879171 Shortdesc & Abstract formatting is incorrect for PDF
2882085 Obsolete code in PDF plug-in should be removed
2661418 make the TOC in pdf2 output link to topics in pdf
2871017 eclipsehelp plugin.xml invalid in 1.5M20
2887331 chunk="to-content" on a sub-map causes path error
2891736 indexterm in topicref level are copied into topic/prolog
2893316 This is a bug in the integrator.xml
2893493 ${clean.temp} is not set to true per documentation
2893664 ampersand entity with conref actions causes build to fail
2893924 htmlhelp transtype requires video plugin
1628937 Rename supportingboth.ditaand.xmlinaditamap.dita
1771123 Inappropriate Message 018 On type= value
1819660 Eclipse Help issue producing toc file.
1848313 ditaval file sent to XSLT not URL
1897542 Chunk to-content may need to rewrite topic IDs
2875946 PDF: table @pgwide semantics not implemented
2893745 missing fop's file/directory in standard package
2900047 map2htmtoc.xsl doesn't allow for extension of root template
2900417 html transform does not use image/@scale properly
2906957 Update Eclipse plugin DTDs and packaging
2796964 Use xml:lang for generated text in PDF
2860596 PullPrologIndexTerms selection too wide, Removed spurious pullPrologIndexTerms in section/title
1852733 Image "scale" attribute is ignored

4 SourceForge Patches Added

2790337 Add extension points to related-links code
2778178 Flagging code duplicates XSL
2715750 plus-transtype-htmlhelp: support alternate compilers
2804311 Feature value trim test bug

A.4.9 DITA OT release 1.4.3

Release 1.4.3 is a maintenance release and is intended to be the last released based fully on DITA 1.1.

It contains a significant amount of preview function for the upcoming DITA 1.2 standard, but the DITA 1.2 document types must be specifically referenced in order to use this capability.

Major Updates

The PDF codebase switched from the older deprecated code to the plugin previously known as PDF2. Running a build with the transform type PDF or PDF2 will now run the new code. To continue using the older code, set your transform type to "legacypdf".
The PDF plugin now runs with FOP, as well as with the latest version of Saxon.
The Full Easy Install package now ships with Saxon 9B instead of with Xalan, and code in the DITA-OT package has been updated to work with Saxon 9B.
The Full Easy Install package updates the versions of many open source libraries (including Ant and FOP)
RFE 1982567 Allow spaces in DITA file names
Preview function for the majority of the upcoming OASIS DITA 1.2 standard, including everything from milestone builds one through twelve of DITA-OT 1.5

10 SF Enhancements Added

1982567 Allow spaces in DITA file names
2631145 dita2htmlImpl.xsl should not define doctype
2562718 Rename the ant directory to avoid naming collisions with ant
2314086 Let maplink generate <linklist> elements
2258659 Extend integrator to allow addition of messages.
2117337 Customize Integrator to integrate custom directories
2074933 Make index output for new transtypes more extensible
1995667 Add plugin extension points to preprocess pipeline
1972537 Let users specify reloadstylesheet on xslt tasks
1803199 Allow ability to include class ancestry in XHTML class attribute

4 SourceForge Patches Added

1996733 Structure Ant <pipeline> better
1796007 Refactor of related links HTML for specialized processing
1947566 pdf2: allow XEP to be installed elsewhere
2477370 Refactor of conrefImpl.xsl

31 SF Bugs Fixed

2008294 End flag does not work in ditaval
2078563 Keyref not working for external links
2027170 maprefImpl.xsl removes part of class attr from topichead
2027058 Topichead element stops map processing in ChunkMapReader
2001268 DITA-OT documentation wants JDK 1.4
2008317 Chunking one topic from a large file hogs memory
2219479 <prodinfo> subelement associations are lost in HTML output
2340727 No link in TOC to topics in ditabase
2317627 Chunking map to create one file should use map file name
2143078 Relcolwidth not respected in choicetable
1995223 bookmap: bookmeta->bookrights information is not generated
1990167 reltable doesn't generate external links correctly
1953553 FO 1.4.2 plugin: Inconsistent display of "on page" in xref
1951879 Link generation is disabled for bookmaps
1997171 topic body suppressed in chapter topics
2417980 Toolkit should support both versions of Serbian lang code
1947817 Extra topics appear in PDF output when using reltables
2004588 Image alt text needs space normalized
1954463 Conditional processing multiple PDFs in the same JVM
2061301 Useless import of xslt4j stops dost.jar being built
2317659 Chunking "by-topic" does not work
1955211 Footnotes-by-reference rendered naively
2010062 Spaces dropped in indexterm that has keyword
2607496 USEINDEX=no breaks HTML Help HHP
2570118 <xref> without href drops content
2414891 Map contains wrong reference after chunking
2010092 example or section title can be orphaned in PDF2
1999117 Ubuntu 8.04 | startcmd.sh doesn't work
2020317 Many duplicated id in xxx_MERGED.xml in PDF2 output.
2614006 Conref processing ignores -dita-use-conref-target
1727863 <groupchoice> has an extra "|" character

A.4.10 DITA OT release 1.4.2.1

Release 1.4.2.1 is a full build to provide an urgent fix to fix the following critical problem which users found in release 1.4.2.

SF Bugs Fixed

SF Bug 1956231 OSGI Manifest for eclipsehelp transtype contains spaces.

For this fix, we have updated xsl/map2pluginImpl.xsl to prevent generating extra spaces at the head of every line in OSGI manifest file of eclipse help output.

A.4.11 DITA OT release 1.4.2

Release 1.4.2 is a maintenance release to fix defects and make patches based on release 1.4.1.

Release 1.4.2 comes in three versions:

Minimal package contains only the core processing code.
Standard package contains the core processing code, plus demos, documentation, and samples.
Full "easy install" package contains the standard package plus external libraries useful for many toolkit processes (such as Xalan and ANT), plus a batch file to setup a local environment.

39 SF Bugs Fixed

1945824 Index-see works for "ru-ru" but not for "ru"
1944245 Null pointer error with complex filename
1923519 Conrefs in nested, conreffed topics don't work
1911285 files.txt is not up-to-date
1906954 Constants.ANT_INVOKER_EXT_PARAM_OUTPUTDIR resulted in null ...
1903830 Error when collection-type=sequence in map
1903626 Topicref to Glossentry With Topicmeta Throws Null Pointer
1900907 Documentation of generateouter command-line param is incorrect
1900427 TIFF file format not a supported type
1898810 Problem running ant with DITA-OT in path with Latin char
1897358 Compiling CHM's in sequence results in errant index entries
1894561 wordrtf not correctly handling p inside li
1893234 Java TopicMerge removes processing instruction
1868423 Null pointer exception when a PI is at the end of the file
1857405 chunk processing fails when no section element
1855047 startup.sh fails under OS X
1849346 FO file generated from DITA MAP not valid
1843652 Image referenced in map is not found, topicmerge breaks
1843583 Extra bullet in TOC for topicref with no href or navtitle
1839765 index-sort-as not used, content appears in index
1908306 Index entry for external resource is ignored
1908293 HTML Help index contains extra anchor
1900916 Pointer to CSS is Incorrect in index.html
1898451 HTML titles should be space-normalized for CHM consumption
1898228 Table desc not being processed
1897551 maplink is unawareof chunk to-content
1893461 map file href handling
1889918 Index link goes with wrong entry
1883907 IndexTermReader class doesn't handle specialized titles
1873401 XHTML: colsep in last column when @frame=none
1872434 _merge.xml missing metadata
1868047 htmlhelp path in demo ant script is fixed
1864247 PIs missing from ditamaps in temp dir
1857282 path to css output is not correct
1848355 gen-list wants class on <foreign> descendants
1843693 Bad XREF syntax gives confusing message about unique_193
1841175 Need to clean up doc/ directory (remove invalid items)
1832800 Empty end-range indexterm causes eclipse error
1606387 Shortdesc & Abstract formatting is incorrect for XHTML

3 SF Patches Added

1930220 Simplify flag templates
1876118 Add plug-in support for string resource-files
1818318 Path to HTML Help compiler on x64 Windows

6 SF Enhancements Added

1855523 Pass dost.class.path to XSLT tasks
1827322 Let plugins add their own template files
1825843 Let plugins add dependencies to Ant targets
1824466 Subclass ImportAction
1782256 Let plugins not have to choose to go in "demo" or "plugins"
1859421 Add plug-in support for string resource-files

A.4.12 DITA OT release 1.4.1

Release 1.4.1 is a maintenance release to fix defects and make patches based on release 1.4.

23 SF Bugs Fixed

1833801 Infinite loop in MapMetaReader
1833796 move-meta-entries creates invalid XML
1827055 Dita 1.4 move metadata method failing
1819663 XHTML processing add   in output files.
1815155 Using xref moves output directory
1807808 Java TopicMerge calling XSLT transformer with URL not file
1806728 Merge doesn't normalize filenames
1806130 chunk module wraps long lines
1806081 <dita> without class attribute triggers warning
1803190 XHTML: processing <xref> to <a title="">
1803183 XHTML: <b> and <xref> within <pre>
1796207 topicmeta in ditamap causes build failure
1782109 Title input to Help Compiler invalid for taskbook example
1779066 [DOTX031E] Errors
1770571 Chunk "to-content" on map not implemented
1732678 Map without DOCTYPE declaration produces odd error
1675195 No Error Location for Titleless Topic
1639672 The Toolkit does not properly support valid xml:lang values.
1639344 Xref : topicpull : the spectitle not used as linktext
1628937 Rename supportingboth.ditaand.xmlinaditamap.dita
1584187 Bookmap 1.1: <title> element breaks topicmerge
1563093 Difficult to find location of error
1505172 foimgext Considered Harmful

5 SF Patches Added

1741302 Prevent indexterm crash with two-letter language codes
1630214 HTML Help HHP generator: Language tag
1498936 Failure when moving links with embedded mathml
1481586 CSS for ditamap-to-HTML TOC
1457541 xref to elements fails within topics in PDF

5 SF RFE Added

1764910 Allow greater control over the output directory
1764905 Allow option to build only topics listed in the map
1725280 Improve error reporting in general
1686939 Make dita.list into an XML file
1676947 Integration points for passing params to XSL

A.4.13 DITA OT release 1.4

Release 1.4 is a major release to add new functions, fulfill new requirements, make some function enhancements and fix bugs over release 1.3.1.

Available since August 1, 2007

The DITA-OT Release 1.4 contains full support for the OASIS DITA 1.1 standard. This completes the preliminary support added in the 1.3 and 1.3.1 versions of the toolkit. New and improved items for 1.1 are listed under [Improvements] below. Support for the new bookmap standard is available in the latest version of the FO plug-in, which uses the "pdf2" transform type; it will be released together with or soon after the release of DITA-OT 1.4. The deprecated "pdf" transform type has not been updated for the new bookmap. Together with DITA 1.1 support, the toolkit development team has improved error reporting so that build failures are more accurately reported at the end of the build. Error handling will continue to improve in future releases. Release 1.4 comes in two versions. The full version contains several external packages that are useful or critical to running the toolkit, such as Xalan and the XML Catalog resolver. The smaller package contains only core toolkit code. NOTE ABOUT DEPRECATED CODE: changes for the new DITAVAL standard required a change to code in dita2htmlImpl.xsl. The "flagit" named template is deprecated and will not work with the new ditaval format. Overrides to this step should be updated to use "start-flagit" and "end-flagit". The flagit template will continue to work with the old ditaval but will generate a warning for each call.

Changes

Release 1.4 improves the processing of DITA documents using XML Schemas. One was able to process these type of documents in Release 1.3.1 but it meant that the schema location had to have the ablsolute location of the schema in order for the Toolkit properly.

DITA 1.1 introduces the use of URNs to normatively identify the schemas used for validation. The URNs have the following desing pattern "urn:oasis:names:tc:dita:xsd:<schemaDocument>:1.1". You should use these in as the value for the attribute xsi:noNamespaceSchemaLocation.

13 Improvements

Support <title> in map
Ignore Index-base in default processing
Retrieve the link text from abstract element.
Format shortdesc in abstract appropriately
Add standard code to allow overrides to easily process generalized version of unknown and foreign element
Support @dir on every element
Refactor mapref resolution
Support generalization and re-specialization of unknown/foreign elements
Replace Move Index module with new Move Metadata module
New DITAVAL standard support
New chunk attribute support
Support XML Schema validated instance document processing using XML Catalogs

17 SF Bugs Fixed

1700561 Null Pointer Exception on Missing domain= Attribute
1733264 pretty.xsl is broken
1619074 table in step screws up following steps for HTML generation
1728700 GenMapAndTopicList keeps filtering when called a second time
1732562 DitaWriter.java can duplicate @xtrf and @xtrc
1733108 Update Bookmap sample files to DITA 1.1
1706263 Conrefing from a map to topic is not working properly
1677620 Non-DITA file is treated as DITA in pre-process
1717471 Links show up more than once
1712543 gen-list-without-flagging : NullPointerException
1652892 Invalid hdr/ftr arg value causes build failure
1647950 PIs in DITA source are dropped in the processing pipeline
1644559 Force Toolkit to use private catalog to allow schemas to work properly
1642138 Move javamerge target out of build_template.xml
1643155 Map TOC is HTML even for transtype="xhtml"
1637564 topicpull breaks specializations of xref
1676968 Plugins adding to classpath break when basedir != dita.dir

A.4.14 DITA OT release 1.3.1

Release 1.3.1 is a maintenance release to fix defects and make patches based on release 1.3.

15 SF Bugs Fixed

SF Bug 1385642 docbook/topic2db.xsl - shortdesc
SF Bug 1528638 wordrtf does not correctly number steps
SF Bug 1562518 Flag is confusing when a list is mixed with text
SF Bug 1563665 Should use CSS to honor rowsep and colsep in table entries
SF Bug 1567117 Xref to footnote is not resolved correctly
SF Bug 1569671 <reltable> in nested map creates bogus TOC entries
SF Bug 1573996 Plugins do not work in plugins directory
SF Bug 1574011 Spaces in a file name prevent XHTML output
SF Bug 1584186 Bookmap 1.1: <title> element duplicated in mappull
SF Bug 1588039 Conref domain checking is sub-par
SF Bug 1588624 OT v1.3 map2hhc.xsl error
SF Bug 1597444 Java topicmerge breaks when text contains less-than
SF Bug 1597473 Nothing references common.css
SF Bug 1598109 Java topicmerge does not rewrite image/@href
SF Bug 1598230 jhindexer of JavaHelp breaks Search Index for DITAOT content

A.4.15 DITA OT release 1.3

OASIS DITA 1.1 support

Things to know about OASIS DITA 1.1 support in this release:

DITA-OT 1.3 provides preliminary processing support for the upcoming OASIS DITA 1.1 specification (see http://wiki.oasis-open.org/dita/Roadmap_for_DITA_development). Because the proposed OASIS DITA 1.1 DTDs and Schemas are fully backwards compatible with the latest DITA 1.0.1 DTDs and Schemas, the 1.3 Toolkit provides the proposed 1.1 materials as the default DTDs for processing. The XML Catalog resolution maps any references for DITA 1.0 doctypes to the 1.1 DTDs, for example. All processing ordinarily dependent on the 1.0 definition continues to work as usual, and any documents that make use of the newer 1.1-based elements or attributes will be supported with specific new processing function (such as base support for the new <data> element). Documents created with the proposed OASIS DITA 1.1 DTDs are the only ones ever likely to have features that invoke the specific new 1.1-based processing support.

Important

Because this support is based on a yet-to-be-approved version of the proposed OASIS DITA 1.1 specification, if you choose to investigate any1.1-based function, be aware that the 1.1 implementation in this version of the Toolkit is preliminary and very much forward-looking. Upon final approval of the DITA 1.1 standard, Toolkit developers will, of course, review our implementation to make certain that it conforms to the defined level of reference implementation.
Related to the DITA 1.1 preliminary implementation, the much-discussed bookmap updates for DITA 1.1 will be provided as override capabilities for the FO plugin (Idiom's donation). Note that:
- The FO demo transform code at the 1.2.2 level is still included in the DITA 1.3 package, but is now deprecated.
- To get the FO updates for 1.3, grab the FO plug-in at its next update, which should be shortly after the 1.3 core Toolkit code is released.
- The updated FO plug-in will be usable with FOP as well as with XEP.

Changes

The DITA Open Toolkit team understands the need for stability in essential APIs in the Toolit. This verson of the toolkit provides some strategic updates that correct some long-overdue faults in the original implementation. Necessarily, there are some changes to note:

Change to build.xml: To make the DITA processing environment more like other Ant-driven build environments, the original build.xml has been renamed as build_demo.xml. The current build.xml in this release is now the normal ANT script entrance for starting a transformation. If you have created Ant tasks that tried to work around the former build.xml architecture, those might need to be revised to take advantage of the separated function.
Change to command line invocations: The "Ant refactoring" exercise for this release has changed some previously documented Ant calls for running demos. This change enables better use of the Ant modules for power users who need to integrate the Toolkit into programming build environments such as Eclipse, but the change affects some documentation. This is a permanent change that should remain stable from now on. Wherever you see an older instruction like "c:\dita-ot>ant all", you now need to indicate the component that contains the demos, so you would type "c:\dita-ot>ant all -f build_demo.xml".
Separation of demo targets from formal component targets: Another effect of the Ant refactoring is that the internal programming targets will now be displayed when you type "ant -p". To see both those programmings targets and the demos that are part of this component, type "c:\dita-ot>ant -p -f build_demo.xml". To run just one of the demos that you see in the resulting list, dita.faq for example, type "c:\dita-ot>ant dita.faq -f build_demo.xml".
Classpath update to enable catalog resolver: This release now includes the Apache catalog resolver for improved lookup of DTDs by any of the Toolkit components. The fullpackage version of the Toolkit sets up these variables for each session. For the regular (smaller) version of the Toolkit, you need to include lib and lib\resource\resolver.jar into your classpath. For example if your CLASSPATH is like:
```
c:\dita-ot\lib\dost.jar
```
you need to change it to:
```
c:\dita-ot\lib;c:\dita-ot\lib\dost.jar;c:\dita-ot\lib\resolver.jar
```
At any time, the full version can be used like a normal installation as long as you update the system variables either in the evironment settings or in a batch file that sets up the shell environment.
License bundling: To reduce the duplication of builds on Sourceforge in which the only difference was the license provided in each, both the Apache and CPL licenses are included in root directory of the Toolkit. Use the one that applies to your situation.
Two install options: Two download versions are now offered. The smaller one is for updating existing installations or for reuse in embedded applications that already provide the other processing components--business as usual. A new package with "fullpackage" in the name now incorporates the essential processing modules to create a processing environment for new users and evaluators that requires nothing more than to unzip the file into an appropriate directory and then click on a "start" batch file. A new document in its root directory (an output of doc/EvaluateOT.dita, Evaluating the DITA Open Toolkit (fullpackage version)) informs new users how to install and use the Toolkit for the first time.
Other enhancements: The public design discussions that fed into the final selection and architectures for this release are documented at the DITA Focus Area in a topic called DITA OT 1.3 Issues tracking (http://dita.xml.org/node/1282).

7 Improvements

Preliminary support for OASIS DITA 1.1
Support ICU in index sorting
Integrate with Eclipse
Refactor Ant script for easy override
Topicmerge reimplementation in JAVA
Enable XML Catalog Resolver
Full package distribution (was GUI/usability)

21 SourceForge Bugs Fixed

SF Bug 1582506 Docbook cannot handle <author>
SF Bug 1548189 Sections should not jump to <h4> for Accessibility reasons
SF Bug 1548180 Spaces dropped from index terms
SF Bug 1548154 XHTML index links should go to the topic
SF Bug 1545038 CommandLineInvoker is unfriendly towards spaces
SF Bug 1541055 topicref @id incorrectly uses NMTOKEN type
SF Bug 1530443 dost.jar relies on the incorrect behavior of Xerces
SF Bug 1473029 Syntax code makes overrides difficult
SF Bug 1470101 Metadata in topics is left out of XHTML headers
SF Bug 1470077 Choicetable headers create attribute inside attribute
SF Bug 1470057 Step template creates attributes after creating tags
SF Bug 1465947 <topichead> without children the whole branch to disappear
SF Bug 1465941 Keywords defined in map are ignored if <topicref> contains t
SF Bug 1465866 Problems in catalog-dita.txt
SF Bug 1460447 <morerows> not well supported in pdf tranformation.
SF Bug 1457187 'copy-to' doesn't actually copy files
SF Bug 1454835 OT renders files referenced via conref only
SF Bug 1427808 Should be easier to modify link attributes in XHTML
SF Bug 1422182 @colname renaming needs to apply to @namest and @nameend
SF Bug 1417820 fo and docbook outputs can\'t handle deep topic dirs
SF Bug 1368997 PDF Vertical list of author redundancy

1 SourceForge Patch Added

SF Patch 1503296 Refactor of HTMLHelp inifiles creation

1 SourceForge RFE Added

SF RFE 1160960 Enh: Toolkit should work with both both *.dita and *.xml

A.4.16 DITA OT release 1.2.2

Release 1.2.2 is a maintenance release to fix defects and make patches based on release 1.2.1.

Improvements

Chinese support in WORD RTF
Improve plug-in architecture in plug-in dependency handling

SourceForge Changes

SF Bug 1461642 Relative paths in toolkit.
SF Bug 1463756 TROFF output is not usable
SF Bug 1459527 Properties elements should generate default headings
SF Bug 1457552 FO gen-toc does not work right for ditamaps and bookmaps
SF Bug 1430983 Specialized indexterm does not generate entries in index
SF Bug 1363055 Shortdesc disappears when optional body is removed
SF Bug 1368403 The dita2docbook transformation lacks support for args.xsl
SF Bug 1405184 Note template for XHTML should be easier to override
SF Bug 1407646 Map titles are not used in print outputs
SF Bug 1409960 No page numbers in PDF toc
SF Bug 1459790 Related Links omitted when map references file#topicid
SF Bug 1428015 Topicmerge.xsl should leave indentation alone
SF Bug 1429400 FO output should allow more external links
SF Bug 1405169 Space inside XHTML note title affects CSS presentation
SF Bug 1402377 Updated translations for Icelandic
SF Bug 1366845 XRefs do not generate page numbers
SF Patch 1326450 Make ${basedir} mine
SF Patch 1328264 FOP task userconfig file
SF Patch 1385636 Tweaks to docbook/topic2db.xsl
SF Patch 1435584 Recognize more image extensions
SF Patch 1444900 Add template for getting input file URI
SF Patch 1460419 Add a new parameter /cssroot:{args.cssroot}
SF Patch 1460441 map2hhp [FILES] include
SF RFE 1400140 Add a new parameter /cssroot:{args.cssroot}

A.4.17 DITA OT release 1.2.1

Release 1.2.1 is a maintenance release to fix defects and make patches based on release 1.2.

Improvements

Corrupt table generated in WORD RTF is fixed
Pictures are merged into the WORD RTF instead of creating links to them
lq element is supported in WORD RTF
Generated text can be translated to different languages in WORD RTF
In WORD RTF, if no <choptionhd> given, head will be generated in table

SourceForge Changes

SF Bug 1460451 Spaces preserving methods are different among tags.
SF Bug 1460449 Nested list can not be well supported.
SF Bug 1460445 h2d stylesheet cannot handle HTML files within namespace.
SF Bug 1431229 hardcoded path in MessageUtils.java
SF Bug 1408477 <desc> element is not handled inside xref for XHTML
SF Bug 1398867 ampersands in hrefs (on xref and link) cause build to fail
SF Bug 1326439 filtered-out indexterms leak into index through dita.list
SF Bug 1408487 Short description is not retrieved for <xref> element
SF Bug 1407454 XHTML processing for <alt> is incomplete
SF Bug 1405221 Some table frames ignored in dita->xhtml
SF Bug 1414398 Cannot set provider for Eclipse help transformation
SF RFE 1448712 add support for /plugins directory in plug-in architecture

A.4.18 DITA OT release 1.2

DITA open toolkit Release 1.2 is a major release to add new functions, fulfill new requirements, make some function enhancements and fix bugs over release 1.1.2.1.

Important Change

DITA-OT 1.2 offers new error handling and logging system. If you invoke your transformation by using java command line where new error handling and logging system is mandatory, you need to set the CLASSPATH Environment Variable for dost.jar. If you invoke your transformation by using an ant script, you need to do one more step after the setting above. That is adding a parameter in your command to invoke an ant script. For example, use ant -f ant\sample_xhtml.xml -logger org.dita.dost.log.DITAOTBuildLogger instead of ant -f ant\sample_xhtml.xml to start a transformation defined in ant script file ant\sample_xhtml.xml.

New Functions

New plugin archiecture
DITA Open Toolkit 1.2 provides a new function to help users to download, install and use plug-ins and help developers create new plug-ins for DITA Open Toolkit.
Transformation to wordrtf
DITA Open Toolkit 1.2 provides DITA to Word transforming function to transform DITA source files to output in Microsoft® Word RTF file.
HTML to DITA migration tool
DITA Open Toolkit 1.2 provides a HTML to DITA migration tool, which migrates HTML files to DITA files. This migration tool originally comes from the developerWorks publication of Robert D. Anderson's how-to articles with the original h2d code.
Problem determination and log analysis
In DITA Open Toolkit 1.2, a new logging method is supported to log messages both on the screen and into the log file. The messages on the screen present user with the status information, warning, error, and fatal error messages. The messages in the log file present user with more detailed information about the transformation process. By analyzing these messages, user can know what cause the problem and how to solve it.
Open DITA User Guide for conditional processing
In DITA Open Toolkit 1.2, a new user guide which can help users to use conditional processing is added to toolkit document.
Include the OASIS version langref
In DITA Open Toolkit 1.2, a new OASIS version of language reference for DITA standard is added to toolkit document.
Document adapt to OASIS DITA 1.0.1 DTDs
DITA DTD files are updated to 1.0.1 version in DITA Open Toolkit 1.2.

Other Changes

SF Bug 1304545 Some folders were copied to DITA-OT's root directory
SF Bug 1328689 Stylesheet links in HTML emitted with local filesystem paths
SF Bug 1333481 Mapref function does not work for maps in another directory
SF Bug 1343963 Blank index.html generated for ditamap contains only reltabe
SF Bug 1344486 java.io.EOFException thrown out when reading ditaval file
SF Bug 1347669 Path Spec. in nested DITA maps
SF Bug 1357139 filtering behavior doesn't conform to spec
SF Bug 1358619 The property.temp file gets cleaned out by default
SF Bug 1366843 XRefs do not generate proper links in FO/PDF
SF Bug 1367636 dita2fo-elems.xsl has strange line breaks
SF RFE 1296133 Enable related-links in PDF output
SF RFE 1326377 Add a /dbg or /debug flag for diagnostic info
SF RFE 1331727 Toolkit need to run on JDK 1.5.x(only support to run under Sun JDK 1.5 with saxon in normal case)
SF RFE 1357054 Be more friendly towards relative directories
SF RFE 1357906 Provide a default output directory
SF RFE 1368073 Enable plugins for DITA open toolkit
SF RFE 1379518 Clearer error messages and improved exception handling
SF RFE 1379523 DITA to Rich Text Format (.rtf) file
SF RFE 1382482 plugin architecture of DITA-OT

A.4.19 DITA OT release 1.1.2.1

Release 1.1.2.1 is a full build to provide an urgent fix to fix the following critical problem which users found in release 1.1.2.

SF Bug 1345600 The build process failed when run "Ant all" in release 1.1.2

For this fix, we have restored all the source DITA files in 'doc' and directories in the binary packages.

Note that the original parameter "args.eclipse.toc" in "Ant tasks and script" was separated to "args.eclipsehelp.toc" for DITA-to-Eclipse help transformation, and "args.eclipsecontent.toc" for DITA-to-dynamic Eclipse content transformation.

Another issue is that we found there is a mismatch in the document and the toolkit behavior when you are trying to use the following command

ant -f conductor.xml -propertyfile ${dita.temp.dir}/property.temp.

Now we have updated the documentation. Please refer to the topic 'Building DITA output with Java command line' on our website for more details.

These updates do not affect standard operation of the toolkit. The main goal of this minor release to enable new users of the toolkit to run the installation verification tests without failure.

A.4.20 DITA OT release 1.1.2

Release 1.1.2 is a maintenance release to fix defects and make patches based on release 1.1.1.

But there are certain limitations and unfixed bugs in this release, such as,

Bug 1343963 Blank index.html generated for ditamap contains only reltabe
Bug 1344486 java.io.EOFException thrown out when reading ditaval file

Please check the current 'open' bugs on the SourceForge bugs tracker.

Changes

SF Bug 1297355: Multilevel HTML Help popup shows filenames
SF Bug 1297657: Update for Supported Parameters page
SF Bug 1304859: Toolkit disallows repetition of topic ID within map
SF Bug 1306361: Fatal error in published ditamap example
SF Bug 1306363: common.css not compiled with htmlhelp
SF Bug 1311788: DTD references not resolved
SF Bug 1314081: Fix catalog entries in catalag-ant.xml for OASIS DTDs
SF Bug 1323435: wrong system id for html output used in validation
SF Bug 1323486: HTML Help subterm indexes not sorted
SF Bug 1325290: JavaHelp output does not work for Russian
SF Bug 1325277: File missing from the map causes abend
SF Patch 1253783: dita2fo-links relative hrefs
SF Patch 1324387: In xslfo, groupchoice var prints extra | delimiter
SF RFE 1324990: Installation Guide

Parameter Changes

The original parameter "args.eclipse.toc" in "Ant tasks and script" was separated to "args.eclipsehelp.toc" for dita2eclipsehelp transformation, and "args.eclipsecontent.toc" for dita2eclipsecontent transformation.
Several parameters were added to the java command line interface, including "/javahelptoc","/javahelpmap","/eclipsehelptoc","/eclipsecontenttoc","/xhtmltoc".

Other Changes

Change to the "doc" directory, except "doc\langref" directory:

The source dita files and the generated HTML, CHM, and PDF files were separated into separate downloads.
The source package contains the source dita files.
The binary package contains the generated HTML, CHM, and PDF files.

A.4.21 DITA OT release 1.1.1

Release 1.1.1 is a maintenance release to fix defects and make patches based on release 1.1.

For patch 1284023, we are changing the name of the jar lib file from dost1.0.jar back to dost.jar because we believe we need to keep the jar file name consistent through various releases.

Changes

SF Bug 1196409: HTMLHelp output does not reference CSS
SF Bug 1272687: extra "../" link generated by topicgroup
SF Bug 1273751: revision flag using unavailable pictures
SF Bug 1273816: Index generation doesn't cope with multilevel well
SF Bug 1281900: Unnecessary comment and href typo
SF Bug 1283600: unecessary space in document cause invalid parameter of Ant
SF Bug 1283644: multipul document($FILTERFILE,/) doesn't work (XALAN)
SF Patch 1251609: pretargets xsl directory needs to use ${dita.script.dir}
SF Patch 1252441: Files in temp directory not deleted before build
SF Patch 1253785: Inline images in dita2fo-elems
SF Patch 1284023: change the name of jar file and remove the version name

A.4.22 DITA OT release 1.1

Release 1.1 is a major release to add new functions, fulfill new requirements, make some function enhancements and fix bugs over release 1.0.2.

Adaptation to the new OASIS DITA standard
Release 1.1 implements the new OASIS DITA 1.0 standard for DITA DTDs and Schemas.

DTDs of the previous release locate in the directory dtd/dita132 and schemas of the previous release locate in the directory schema/dita132.
Transformation to troff
Release 1.1 supports new troff output. Troff output looks like Linux man page output.
XML catalog support
An XML catalog, which can consist of several catalog entry files, is a logical structure that describes mapping information between public IDs and URLs of DTD files. A catalog entry file is an XML file that includes a group of catalog entries. If you want to know more about XML catalog, please referXML Catalog.

A catalog entry can be used to locate a unified resource identifier (URI) reference for a certain resource such as a DTD file. An external entity's public identifier is used for mapping to the URI reference. The URI of any system identifier can be ignored.
Topicref referring to a nested topic
The href attribute of the topicref is extended to quote a nested topic in a dita file.

For example, in previous releases, href attribute is set like: href = "xxx.dita"; in release 1.1, href attribute can be set like: href = "xxx.dita#abc.dita".
Globalization support
Release 1.1 supports over 20 popular languages within the content of dita files. And it also provides translation function for DITA keywords to over 20 languages. Currently this globalization support fully applies to Eclipse Help and XHTML transformations, and partially applies to other transformations.
Accessibility support
Accessibility support is now partially applies to PDF and XHTML transformations.
Eclipse Content Provider Support
Please refer to Eclipse Content Provider for detail information.
Index information in output
The output of HTML Help and Java Help transformations contain index information now.
Mapref function
Mapref refers to a special usage of the <topicref> element as a reference to another ditamap file. This allows you to manage the overall ditamap file more easily. A large ditamap file can thus be broken down into several ditamap files, making it easier for the user to manage the overall logical structure. On the other hand, this mechanism also increases the reusability of those ditamap files. If you want to know more about mapref, please refer Mapref.
TOC generation for Eclipse Help transformation
TOC generation now supported in transformation to Eclipse Help. Eclipse.
Helpset generation for Java Help transformation
Helpset generation now supported in transformation to Java Help.
New parameters supported in Java commands
In Java commands: /indexshow, /outext, /copycss, /xsl, /tempdir.
New parameters supported in Ant scripts
In Ant scripts: args.indexshow, args.outext, args.copycss, args.xsl, dita.temp.dir

Other Changes

SF bug 1220569: Add XML Schema processing to DITA-OT
SF bug 1220644: Prompted ant--image does not link for single topic to PDF
SF bug 1229058: Add schema validation loading file for processing
SF RFE 1176855: Ant must be run from toolkit directory
SF RFE 1183482: Copy pre-existing html to output dir
SF RFE 1183490: Provide argument to specify the location of temp dir
SF RFE 1201242: override capability

A.4.23 DITA OT release 1.0.2

Release 1.0.2 is a maintenance release to fix defects and adds some minor enhancements in release 1.0.1.

Changes

SF Bug 1181950: format attribute should be set to 'dita' for dita topic
SF RFE 1183487: Document the usage of footer property
SF RFE 1198847: command line interface support
SF RFE 1198850: architecture document update
SF RFE 1200410: need explanation for dita.list
SF RFE 1201175: XML catalog support
SF Patch 1176909: Add template for getting image URI

A.4.24 DITA OT release 1.0.1

Release 1.0.1 is a maintenance release to fix defects and adds some minor enhancements in release 1.0.

Changes

Committer: maplink.xsl doesn't generate related links for second level referred topic
Committer: avoid infinite loop of conref
SF Bug 1160964: Can't point above the directory which contains the map file
SF Bug 1163523: Broken XPath expression in mappull.xsl
SF Bug 1168974: useless DRAFT param in FO transformation
SF Bug 1173162: generate null internal link destination in fo transformation
SF Bug 1173164: Not correctly use document() in dita2fo-links.xsl
SF Bug 1173663: All base directories are DITA-OT 1.0
SF Patch 1163561: XLST match patterns test for element names
SF Patch 1165068: FO hyperlinks and FOP-generated PDF bookmarks
SF Patch 1174012: Modification to sequence.ditamap

A.4.25 DITA OT release 1.0

The initial release of the Open Sourced DITA Toolkit introduces major architectural changes from the previous, developerWorks version of the Toolkit.

New features

A new, Java-based processing architecture that supports single-threaded execution throughout.
Ant-based orchestration of the processing environment, from preprocessing to transformation to any required post-processing.
A pre-processor core that supports conditional processing and conref resolution.
Map-driven processing that generates links for transformed topics.
A new DITA to HTML transform that replaces the previous topic2html_Impl.xsl core transform. This new core is based on requirements for high-volume usage within IBM for the past several years.

Ant-driven processing means that you can integrate the DITA processing tools into a seamless pipeline within supportive environments such as Eclipse.

The DTDs and Schemas in this version are based on those in the previous dita132 package with bug fixes. The DITA OS Toolkit will later support the OASIS 1.0 specification in its public review form.

A.4.26 DITA history on developerWorks (pre-Open Source)

Versions of the toolkit prior to Open Source are in the developerWorks XML Zone at this address: DITA Downloads Change logs for those versions are within the Readme files in each distribution.

Appendix B: DITA Open Toolkit Project Management Guidelines

The DITA Open Toolkit Project Management Guidelines are designed to provide information about how the project is managed. These guidelines are geared to an audience that needs information about how to participate in the development of the DITA-OT.

The project is managed similarly to commercial software-development projects; it uses requirements gathering, plan validation with stakeholders and contributors, scheduled activities, tests, reviews, and builds. Quality is strongly emphasized.

B.5.1 Goals and objectives of the DITA Open Toolkit

The goal of the DITA Open Toolkit (DITA-OT) is to provide a high-quality implementation for production-level output of DITA content, built in a professionally-managed project environment by vetted contributors, and tested thoroughly for each release.

The DITA-OT is designed to meet the needs of users who want to publish DITA content, from individual users running the toolkit in a stand-alone mode to vendors who incorporate the toolkit into their software products. The different distribution packages are designed to meet the needs of these different audiences.

The DITA-OT project keeps up to date with the latest DTD and Schema updates from the OASIS DITA Technical Committee (TC), which develops and maintains the DITA standard. As the DITA TC produces drafts of future versions, the DITA-OT works to create early support for new features and helps to test the new draft versions of the standard.

The project agrees with the open-source motto of Release early and often and seeks to develop wide consensus on issues.

B.5.2 DITA Open Toolkit development process

The DITA Open Toolkit (DITA-OT) development process is modeled after development processes for other popular and successful open-source projects, most notably Eclipse.

Version 1.0 was released February 27, 2005. Version 2.0 was released June 29, 2012.

Project roles and responsibilities

The DITA Open Toolkit (DITA-OT) project has the following roles: Project manager, committer, and contributor. Each role has different rights and obligations.

Project manager (PM)

The project manager is responsible for managing the project. The PM provides leadership to guide the overall direction of the project and removes obstacles, solves problems, and resolves conflicts. The PM works to ensure that the following goals are met:

The project operates effectively.
All project plans, technical documents, and reports are publicly available.
The project operates using the open-source rules of engagement, which stress meritocracy, transparency, and open participation.

Committer

Committers oversee the quality and originality of all contributions. Committers influences the development of the project and have write access to the source-code repository. This position reflects a track record of high-quality contributions to the project.

Contributor

Contributors contribute code, documentation, fixes, tests, or other work to the project. Contributors do not have write access to the source-code repository. There is no limit to the scope of such contributions, though contributors who expect to donate a large amount of new function to the project are encouraged to work with committers in advance.

DITA Open Toolkit release management

The DITA-OT project works with an agile development process; it releases test (milestone) builds approximately every month, and it encourages feedback on the test builds while function is being developed. Stable releases are typically issued approximately every six months.

Each iteration begins with a meeting of project contributors. The meeting minutes are stored on the project Wiki and are available to the public. Active contributors are directly invited to these meetings, but anybody interested in the DITA-OT development is welcome to attend. If you are interested in attending these meetings, join the dita-ot-developer mailing list and send a note to the list or list owners.

Each iteration kick-off meeting covers the following topics:

Issues from the previous iteration
Plans from each contributor for the upcoming iteration or for new work that will span multiple iterations
Design discussion for any significant planned features or fixes
Longer-term plans for contributions to the current or following release
(As needed) Other project issues or hot topics, such as changes to the test and build process, interest from new contributors, etc.

The kick-off meeting for the final iteration before a stable build covers the following topics:

Evaluation of what is allowed in the iteration; the final iteration typically has no major changes in order to assure quality in the stable build.
Assessment of whether all release notes and other artifacts are up-to-date and ready for a final build.

When an iteration is complete, the build is uploaded to SourceForge. Test builds are placed in the Latest Test Build folder. At the end of a release cycle, the builds are loaded to the Stable Release folder, and the project information is updated to reflect the latest release.

Feature requests and defect reports

Feature requests and defect reports can be submitted at any time through the project page at GitHub.

The core project contributors track and address bugs reported against the project; they issue patches based on urgency. The core contributors also will provide feedback on requests for new features or design changes, but they might not be able to provide development assistance.

All new bug reports or feature requests should be submitted through github: DITA-OT bug and feature tracker.

Feature requests

The project committers periodically review new feature requests with contributors and interested parties; when possible, they make plans to implement the new features.

If an existing project contributor is interested in a new request, the item is assigned to the contributor and implemented based on the contributor's schedule. Otherwise, if the request is valid and in line with project goals, it is left open for an interested party to pick up and implement. Some requests are best implemented as a plug-in rather than in the core DITA-OT code; in those cases, project committers suggest alternatives and close the request.

Defect reports

The project committers determine the owner of the relevant components and assign the defect to the component owner for validation and disposition. Responses, fixes, and workarounds are issued faster if the defect report includes sample files and clear instructions for reproducing the issue.

If bugs are found in the OASIS DITA DTDs or Schemas, they are fixed in the toolkit and reported to the OASIS DITA Technical Committee.

B.5.3 How to participate in the DITA Open Toolkit

Any individual or any organization can contribute to the project; contributions must adhere to the existing toolkit license(s) and should fit in with the general goals of the project. All major contributors will get appropriate recognition in release announcements and on the project home page.

Contributors can submit new features, patches, and bug fixes using existing github facilities (this is done by creating a "pull request" within github). The Committer(s) who owns the relevant components will first do due diligence to check code originality and licensing according to the DITA Open Toolkit Contribution Policy. After due diligence, the Committer(s) will use his/her own judgment on whether to accept the code into the original code base, request updates to the code, or suggest that the code be maintained as an external patch or plug-in.

Contributions are always encouraged, and generally fall into one of two groups, as determined by project Committers:

Bug fixes and minor patches are accepted with little overhead.
Major contributions require the contributor to sign a form stating that the submitter is free to commit the code (individually or on behalf of an employer), and that the code complies with the current toolkit license terms.

Due diligence for submission of bug fixes and patches from non-committers

Any organization or individual may submit bug fixes using a github "pull request", generally tied to a specific report in the project's issue tracker.

Before committing code from a bug fix or patch provided by a third party who has not signed a current contribution form for the project, Committers should ask the following questions and follow up as appropriate in order to ensure that the code can be contributed to the project:

What is your name and who is your employer?
Did you write the code that you wish to contribute to the DITA Open Toolkit project? (If the contributor says no, the code should not become a “Contribution” to the project. The contributor may be asked to identify the complete details of the code’s source and of any licenses or restrictions applicable to the code, but the work should be conspicuously marked as “Submitted on behalf of a third-party: [name of contributor]”.)
Do you have the right to grant the copyright and patent licenses for the contribution that are set forth in the CPL version 1.0 license and Apache License version 2.0?
Does your employer have any rights to code that you have written, for example, through your contract for employment? If so, has your employer given you permission to contribute the code on its behalf or waived its rights in the code?
Are you aware of any third-party licenses or other restrictions (such as related patents or trademarks) that could apply to your contribution? If so, what are they?

DITA Open Toolkit Contribution Policy

The purpose of the DITA Open Toolkit Contribution Policy is to set forth the general principles under which the DITA Open Toolkit project shall accept contributions, license contributions, license materials owned by this project, and manage other intellectual property matters.

Overview

The Common Public License (CPL) and Apache License 2.0, which are incorporated herein by reference, will serve as the primary licenses under which the Committer will accept contributions of software, documentation, information (including, but not limited to, ideas, concepts, know-how and techniques) and/or other materials (collectively "Content") to the project from Contributors. A copy of the CPL and Apache License 2.0 can be found at the root directory of the DITA Open Toolkit deliverable package.

This Contribution Policy should at all times be interpreted in a manner that is consistent with the Purposes of the this project as set forth in the DITA Open Toolkit Development Process goals and objectives. This Contribution Policy shall serve as the basis for how non-Committers interact with this project through participation in this project, web-sites owned, controlled, published and/or managed under the auspices of the this project, or otherwise.

The Common Public License and Apache License 2.0 shall serve as the primary licenses under which the Committer(s) shall accept software, documentation, information (including, but not limited to, ideas, concepts, know-how and techniques) and/or other materials (collectively "Content") from contributors including, but not limited to, Contributors and Committers.

The DITA Open Toolkit project provides a process for accepting bug fixes and contributions from parties who have not accepted the license to be Contributors. See Due Diligence for Submission of Bug Fixes and Patches from Non-Committers

DUE DILIGENCE AND RECORD KEEPING

The Committer(s), shall be responsible for scrutinizing all Content contributed to the DITA Open Toolkit project and help ensure that the Contribution Policy licensing requirements set forth above are met. Except as set forth below, the applicable Committer shall conduct the following activities prior to uploading any Content into the repository or otherwise making the Content available for distribution:

Contact the potential contributor of the Content through an appropriate channel of communication and collect/confirm the following:
- Contributor's name, current address, phone number and e-mail address;
- Name and contact information of the contributor's current employer, if any;
- If the contributor is not self-employed, the Committer must request and receive a signed consent form (to be provided by the Committer) from the contributor's employer confirming that the employer does not object to the employee contributing the Content.
- Determine if the Content can be contributed under the terms of the CPL and Apache License 2.0 or the alternative terms and conditions supplied by the Contributor. This can be done by asking the contributor questions such as;
  1. Did you develop all of the Content from scratch;
  2. If not, what materials did you use to develop the Content?
  3. Did you reference any confidential information of any third party?
  4. If you referenced third party materials, under what terms did you receive such materials?
- If it is determined by the Committer that the Content is not the original work of the Contributor, collect the contact information of the copyright holder of the original or underlying work. The copyright holder of the Content or the underlying work may then need to be contacted to collect additional information.
The
was "Committer(s)"
Contributor(s) shall document all information requested in (1) above and fill in Contribution Questionnaire (to be provided by the Committer) and provide the completed Contribution Questionnaire to the Committer.
The Committer shall also be responsible for running a scan tool to help ensure that the Content does not include any code not identified by the contributor.
Based on the information collected, the Committer shall use his/her reasonable judgment to determine if the Content can be contributed under terms and conditions that are consistent with the licensing requirements of this IP Policy.

If the applicable Committer has any doubts about the ability to distribute the Content under terms and conditions that are consistent with the CPL and Apache License 2.0 or the proposed alternative terms and conditions, the Committer may not upload the code to the repository or otherwise distribute the Content. The Committer(s) shall be responsible for filing/maintaining the information collected for future reference as needed.

The above record keeping requirements shall not apply to

Minor modifications to Content previously contributed to and accepted by the Committer(s).
Articles and White Papers
Information or minor Content modifications provided through bug reports, mailing lists and news groups

While the record keeping requirements do not apply to the items listed above, Committers must conduct reasonable due diligence to satisfy themselves that proposed Contributions can be licensed under the terms of the CPL and Apache License 2.0.

DITA-OT Contribution Questionnaire Form 1.2

The Contribution Questionnaire is the first step in initiating the due diligence and approval process by the Project Manager (PM) for any significant contribution of content to be committed to the project. Prior to completing this Questionnaire, the Committer should have technical agreement from the PM that the new code is required. Once the PM has approved, the Committer, with the assistance of one or more of the contributors, may begin the due diligence and approval process by completing and submitting this questionnaire.

What is meant by a significant contribution?

Any initial code contribution used to kick off a new project. By definition, this code has been written elsewhere and it needs to be reviewed.

Any contribution authored by someone other than a committer which is adding new functionality to the codebase. In most cases, bug fixes do not add new functionality although it's not impossible.

Any contribution containing third-party code maintained by another open source project, individual, group, or organization. In addition to reviewing the contribution, if the license is not the Common Public License (CPL) or Apache License 2.0, the PM will need to review and approve the third-party license for compatibility with the CPL or Apache License 2.0.

How to send PM this form?

Please fill in this form and sign your name and get your employer's authorized signature, such as your manager's. then send a scanned copy to Project Manager Robert D Anderson. The scanned copy may be sent to rdanderson at users.sourceforge.net.

NOTE: A questionnaire and approval is not required for bug fixes or minor enhancements. If you have any questions, please send an email to the Project Manager.

Your Info

Please provide your contact details:

Name:
Organization:
Address:
Phone Number:
E-mail:

Committer

Please provide contact details for the committer who will be incorporating this contribution into the code base. If this is the same as above, just put "same" in the Name field.

Name:
Organization:
Address:
Phone Number:
E-mail:

PM Approval

PM Approval is required for all significant contributions. Please provide the contact info of the PM who has given approval for this contribution:

Name:
Phone Number:
E-mail:

Contribution

Please provide details about the contribution:

Component/Module (if known):
Contribution Name:
Contribution Version:
Contribution Size (in lines of code):
Contribution Description:
Does this contribution require any packages maintained by a 3rd party?
Please list all pkgs required by the contribution which are maintained by a 3rd party: (Please list one package per line e.g 3rd party package name v1.0)
Supporting Information:
Do you agree to distribute the Contribution under Common Public License 1.0?
Do you agree to distribute the Contribution under Apache License 2.0?
Provide any additional information you may have regarding intellectual property rights (patents, trademarks, etc.) related to the Contribution. If there is more than one committer who worked on this contribution, please list their name and email addresses.

Contributor

Note: All of the contributors should ensure that they possess the necessary rights to make the contribution under the terms and conditions set out in the Contribution Policy.

Please provide contact details for the contributor or the primary contributor if there is more than one:

Name:
Organization:
Phone Number:
E-mail:
% of content authored in the contribution:

If there are other contributors, please provide names, organizations, e-mail, and percentage of content authored in the contribution:

Other Contributors:

Cryptography

If the contribution deals in any way with cryptography, please provide details:

Details:
Identify the Cryptography algorithm used:

Contributor's signature

Name (Type or Print)
Title
Signature
Date

Contributor employer's signature

Name (Type or Print)
Title
Signature
Date

Appendix C: developerWorks articles

This document contains articles about DITA that were originally published on developerWorks. The online articles have been updated more recently than the versions in this document.

C.6.1 Introduction to the Darwin Information Typing Architecture

This document is a roadmap for the Darwin Information Typing Architecture: what it is and how it applies to technical documentation. It is also a product of the architecture, having been written entirely in XML and produced using the principles described here...

Executive summary

The Darwin Information Typing Architecture (DITA) is an XML-based, end-to-end architecture for authoring, producing, and delivering technical information. This architecture consists of a set of design principles for creating "information-typed" modules at a topic level and for using that content in delivery modes such as online help and product support portals on the Web.

At the heart of DITA (Darwin Information Typing Architecture ), representing the generic building block of a topic-oriented information architecture, is an XML document type definition (DTD) called "the topic DTD." The extensible architecture, however, is the defining part of this design for technical information; the topic DTD, or any schema based on it, is just an instantiation of the design principles of the architecture.

Background

This architecture and DTD were designed by a cross-company workgroup representing user assistance teams from across IBM. After an initial investigation in late 1999, the workgroup developed the architecture collaboratively during 2000 through postings to a database and weekly teleconferences. The architecture has been placed on IBM's developerWorks Web site as an alternative XML-based documentation system, designed to exploit XML as its encoding format. With the delivery of these signficant updates contains enhancements for consistency and flexibility, we consider the DITA design to be past its prototype stage.

Information interchange, tools management, and extensibility

IBM, with millions of pages of documentation for its products, has its own very complex SGML DTD, IBMIDDoc, which has supported this documentation since the early 1990s. The workgroup had to consider from the outset, "Why not just convert IBMIDDoc or use an existing XML DTD such as DocBook, or TEI, or XHTML?" The answer requires some reflection about the nature of technical information.

First, both SGML and XML are recognized as meta languages that allow communities of data owners to describe their information assets in ways that reflect how they develop, store, and process that information. Because knowledge representation is so strongly related to corporate cultures and community jargon, most attempts to define a universal DTD have ended up either unused or unfinished. The ideal for information interchange is to share the semantics and the transformational rules for this information with other data-owning communities.

Second, most companies rely on many delivery systems, or process their information in ways that differ widely from company to company. Therefore any attempt at a universal tool set also proves futile. The ideal for tools management is to base a processing architecture on standards, to leverage the contributed experience of many others, and to solve common problems in a broad community.

Third, most attempts to formalize a document description vocabulary (DTD or schema) have been done as information modelling exercises to capture the current business practices of data owners. This approach tends to encode legacy practices into the resulting DTDs or vocabularies. The ideal for future extensibility in DTDs for technical information (or any information that is continually exploited at the leading edge of technology) is to build the fewest presumptions about the "top-down" processing system into the design of the DTD.

In the beginning, the workgroup tried to understand the role of XML in this leading edge of information technology. As the work progressed, the team became aware that any DTD design effort would have to account for a plurality of vocabularies, a tools-agnostic processing paradigm, and a legacy-free view of information structures. Many current DTDs incorporate ways to deal with some of these issues, but the breadth of the issues lead to more than just a DTD. To support many products, brands, companies, styles, and delivery methods, the entire authoring-to-delivery process had to be considered. What resulted was a range of recommendations that required us to represent our design, not just as a DTD, but as an information architecture.

Main features of the DITA architecture

As the "Architecture" part of DITA's name suggests, DITA has unifying features that serve to organize and integrate information:

Topic orientation. The highest standard structure in DITA is the topic. Any higher structure than a topic is usually part of the processing context for a topic, such as a print-organizing structure or the helpset-like navigation for a set of topics. Also, topics have no internal hierarchical nesting; for internal organization, they rely on sections that define or directly support the topic.
Reuse. A principal goal for DITA has been to reduce the practice of copying content from one place to another as a way of reusing content. Reuse within DITA occurs on two levels:
- Topic reuse. Because of the non-nesting structure of topics, a topic can be reused in any topic-like context. Information designers know that when they reuse a topic in a new information model, the architecture will process it consistently in its new context.
- Content reuse. The SGML method of declaring reusable external entities is available for XML users, but this has several practical limitations in XML. DITA instead leans toward a different SGML reuse technique and provides each element with a conref attribute that can point to any other equivalent element in the same or any other topic. This referencing mechanism starts with a base element, thus assuring that a fail-safe structure is always part of the calling topic (the topic that contains the element with the conref attribute). The new content is always functionally equivalent to the element that it replaces.
Specialization. The class mechanism in CSS indicates a common formatting semantic for any element that has a matching class value. In the same way, any DITA element can be extended into a new element whose identifier gets added to the class attribute through its DTD. Therefore, a new element is always associated to its base, or to any element in its specialization sequence.
- Topic specialization. Applied to topic structures, specialization is a natural way to extend the generic topic into new information types (or infotypes), which in turn can be extended into more specific instantiations of information structures. For example, a recipe, a material safety data sheet, and an encyclopedia article are all potential derivations from a common reference topic.
- Domain specialization. Using the same specialization principle, the element vocabulary within a generic topic (or set of infotyped topics) can be extended by introducing elements that reflect a particular information domain served by those topics. For example, a keyword can be extended as a unit of weight in a recipe, as a part name in a hardware reference or as a variable in a programming reference. A specialized domain, such as programming phrases, can be introduced by substitution anywhere that the root elements are allowed. This makes the entire vocabulary available throughout all the infotyped topics used within a discipline. Also, a domain can be replaced within existing infotyped topics, in effect hiding the jargon of one discipline from writers dealing with the content of another. Yet both sets of topics can be appropriate for the same user roles of performing tasks or getting reference information.
Property-based processing. The DITA model provides metadata and attributes that can be used to associate or filter the content of DITA topics with applications such as content management systems, search engines, processing filters, and so on.
- Extensive metadata to make topics easier to find. The DITA model for metadata supports the standard categories for the Dublin Core Metadata Initiative. In addition, the DITA metadata enables many different content management approaches to be applied to its content.
- Universal properties. Most elements in the topic DTD contain a set of universal attributes that enable the elements to be used as selectors, filters, content referencing infrastructure, and multi-language support. In addition, some elements, whose attributes can serve a range of specialized roles, have been analyzed to make sure that their enumerated values provide a rich basis for specialization (which usually constrains values and never adds to them).
Taking advantage of existing tags and tools. Rather than being a radical departure from the familiar, DITA builds on well-accepted sets of tags and can be used with standard XML tools.
- Leveraging popular language subsets. The core elements in DITA's topic DTD borrow from HTML and XHTML, using familiar element names like p, ol, ul, dl within an HTML-like topic structure. In fact, DITA topics can be written, like HTML, for rendering directly in a browser. In more ambitious designs, DITA topics can be written, like SGML, to be normalized through processing into a deliverable, say XHTML or a well-formed XML format targeted for a particular browser's ability to handle XML. Also, DITA makes use of the popular OASIS (formerly CALS) table model.
- Leveraging popular and well-supported tools. The XML processing model is widely supported by a number of vendors. The class-based extension mechanism in DITA translates well to the design features of the XSLT and CSS stylesheet languages defined by the World Wide Web Consortium and supported in many transformation tools, editors and browsers. DITA topics can be processed by a spectrum of tools ranging from shareware to custom tailored products, on almost any operating platform.

Topic as the basic architectural unit

The various information architectures for online deliverables all tend to focus on the idea of topics as the main design point for such information. A topic is a unit of information that describes a single task, concept, or reference item. The information category (concept, task, or reference) is its information type (or infotype). A new information type can be introduced by specialization from the structures in the base topic DTD. Typed topics are easily managed within content management systems as reusable, stand-alone units of information. For example, selected topics can be gathered, arranged, and processed within a delivery context to provide a variety of deliverables. These deliverables might be groups of recently updated topics for review, helpsets for building into a user assistance application, or even chapters or sections in a booklet that are printed from user-selected search results or "shopping lists."

Benefits of the DITA architecture

Through topic granularity and topic type specialization, DITA brings the following benefits of the object-oriented model to information sets:

Encapsulation. The designer of the topic type only needs to address a specific, manageable problem domain. The author only needs to learn the elements that are specific to the topic type. The implementer of the processing for the topic type only needs to process elements that are special.
Polymorphism. Special topic types can be treated as more generic topic types for common processing.
Message passing. The class attribute preserves at all times the derivation hierarchy of an element. At any time, a topic may be generalized back to any earlier form, and if the class attributes are preserved, these topics may be re-specialized. One use of this capability would be to allow two separate disciplines to merge data at an earlier common part of the specialization hierarchy, after which they can be transformed into one, the other, or a brand new domain and set of infotyped topics.

DITA can be considered object-oriented in that:

Data and processors are separated from their environment and can be chunked to provide behaviors similar to object-orientation (such as override transforms that modify or redefine earlier behaviors).
Classification of elements through a sequence of derivations that are progressively more specific, possibly more constrained, and always rigidly tied to a consistent processing or rendering model.
Inheritance of behaviors, to the extent that new elements either fall through to behaviors for ancestors in their derivation hierarchy, or can be mapped to modified processors that extend previous behaviors.

With discipline and ingenuity, some of the benefits of topic information sets can be provided through a book DTD. In particular, techniques for chunking can generate topics out of a book DTD. In DITA, the converse approach is possible: a book can be assembled from a set of DITA topics. In both cases, however, the adaptation is secondary to the primary purpose of the DTD. That is, if you are primarily authoring books, it makes the most sense to use a DTD that is designed for books. If you are primarily authoring topics, it makes sense to use a DTD that is designed for topics and can scale to large, processable collections of topics.

DITA overview

The Darwin Information Typing Architecture defines a set of relationships between the document parts, processors, and communities of users of the information.

The Darwin Information Typing Architecture has the following layers that relate to specific design points expressed in its core DTD, topic.

Layers in the Darwin Information Typing Architecture

Delivery contexts
helpset	aggregate printing	Web site; information portal

Typed topic structures
topic	concept	task	reference

Specialized vocabularies (domains) across information types
Typed topic:	concept	task	reference
Included domains:	highlighting software programming user interface

Common structures
metadata	OASIS (CALS) table

A typed topic, whether concept, task, or reference, is a stand-alone unit of ready-to-be-published information. Above it are any processing applications that may be driven by a superset DTD; below it are the two types of content models that form the basis of all specialized DTDs within the architecture. We will look at each of these layers in more detail.

DITA delivery contexts

This domain represents the processing layer for topical information. Topics can be processed singly or within a delivery context that relates multiple topics to a defined deliverable. Delivery contexts also include document management systems, authoring units, packages for translation, and more.

delivery contexts
helpset	aggregate printing	Web site; information portal

DITA typed topic specializations (infotyped topics)

The typed topics represent the fundamental structuring layer for DITA topic-oriented content. The basis of the architecture is the topic structure, from which the concept, task, and reference structures are specialized. Extensibility to other typed topics is possible by further specialization.

typed topic structures
topic	concept	task	reference

The four information types (topic, concept, task, and reference) represent the primary content categories used in the technical documentation community. Moreover, specialized, information types, based on the original four, can be defined as required.

As a notable feature of this architecture, communities can define or extend additional information types that represent their own data. Examples of such content include product support information, programming message descriptions, and GUI definitions. Besides the ability to type topics and define specific content models therein, DITA also provides the ability to extend tag vocabularies that pertain to a domain. Domain specialization takes the place of what had been called "shared structures" in DITA's original design.

DITA vocabulary specialization (domains)

Commonly, when a set of infotyped topics are used within a domain of knowledge, such as computer software or hardware, a common vocabulary is shared across the infotyped topics. However, the same infotyped topic can be used across domains that have different vocabularies and semantics. For example, a hardware reference topic might refer to diagnostic codes while a software reference topic might refer to error message numbers, with neither domain necessarily needing to expose the other domain's unique vocabulary to its own writers.

Using the same technique as specialization for topics, DITA allows the definition of domains of special vocabulary that can be shared among infotyped topics. Domains can even be elided entirely, to produce typed topics that have only the core elements. The vocabulary of a domain can take the form of phrases, special paragraphs, and lists--basically anything allowed within a section, the smallest organizing part of a topic.

specialized vocabularies (domains) across information types
Typed topic:	concept	task	reference
Included domains:	highlighting software programming user interface

The basic domains defined as examples for DITA include:

Domain	Elements
highlighting	b, u, i, tt, sup, sub
software	msgph, msgblock, msgnum, cmdname, varname, filepath, userinput, systemoutput
programming	codeph, codeblock, option, var, parmname, synph, oper, delim, sep, apiname, parml, plentry, pt, pd, syntaxdiagram, synblk, groupseq, groupchoice, groupcomp, fragment, fragref, synnote, synnoteref, repsep, kwd
user interface	uicontrol, wintitle, menucascade, shortcut

By following the rules for specializing a new domain of content, you can extend, replace, or remove these domains. Moreover, content specialization enables you to name and extend any content element in the scope of DITA infotyped topics for a more semantically significant role in a new domain.

To enable specialized vocabulary, you declare a parameter entity equivalent for every element used in a DTD (such as topic or one of its specializations), and then use the parameter entities instead of literal element tokens within the content models of that DTD. Later, after entity substitution, because an element's parameter entity is redefined to include both the original element and the domain elements derived from that element, anywhere the original element is allowed, the other derived domain elements are also allowed. In effect, a domain-agnostic topic can be easily extended for different domains by simply changing the scope of entity set inclusions in a front-end DTD "shell" that formalizes the vocabulary extensions within that typed topic or family of typed topics

DITA common structures

One of the design points of DITA has been to exploit the reuse of common substructures within the world of XML. Accordingly, the topic DTD incorporates the OASIS table model (known originally as the CALS table model). It also has a defined set of metadata that might be shared directly with the metadata models of quite different DTDs or schemas.

common structures
metadata	OASIS (CALS) table

The metadata structure defines document control information for individual topics, higher-level processing DTDs, or HTML documents that are associated to the metadata as side files or as database records.

The table structure provides presentational semantics for body-level content. The OASIS/CALS table display model is supported in many popular XML editors.

Elements designed for specialization

DITA provides a rich base for specialization because of the general design of elements used in its archetype-like topic DTD.

For example, a section in the base topic DTD can contain both text and element data. However, a section can be specialized to eliminate PCDATA, yielding an element-only content model similar to the body level of most DTDs. Specialized another way, a section can eliminate most block-like elements and thus be characterized as a description for definitions, field labels, parts, and so forth.

In DITA, an effort has been made to select element names that are popular or that are common with HTML. Some semantic names have been borrowed from industry DTDs that support large SGML libraries, such as IBMIDDoc and DocBook.

The attribute lists within the topic DTD reflect this design philosophy. For example, one of the "universal attributes" (they appear on most elements) is importance, which defines values for weightings or appraisals that are often used as properties in specialized elements. This attribute shows up in several elements of the task topic specialization with only two allowed values out of the original set, "optional' and "required." In other domains, the elements are more appropriately ranked as "high" or "low," again values that are provided at the topic level.

The values of specialization

A company that has specific information needs can define specialized topic types. For example, a product group might identify three main types of reference topic: messages, utilities, and APIs. By creating a specialized topic type for each type of content, the product architect can be assured that each type of topic has the appropriate content. In addition, the specialized topics make XML-aware search more useful because users can make fine-grained distinctions. For example, a user could search for "xyz" only in messages or only in APIs, as well as search for "xyz" across reference topics in general.

There are rules for how to specialize safely: each new information type must map to an existing one and must be more restrictive in the content that it allows. With such specialization, new information types can use generic processing streams for translation, print, and Web publishing. Although a product group can override or extend these processes, they get the full range of existing processes by default without any extra work or maintenance.

A corporation can have a series of DTDs that represent a consistent set of information descriptions, each of which emphasizes the value of specialization for those new information types.

Role of content communities in the Darwin Information Typing Architecture

The technical documentation community that designed this architecture defined the basic architecture and shared resources. The content owned by specified communities (within or outside of the defining community) can reuse processors, styles, and other features already defined. But, those communities are responsible for their unique business processes based on the data that they manage. They can manage data by creating a further specialization from one of the base types.

The following figure represents how communities, as "content owners at the topic level," can specialize their content based on the core architecture.

Relationship of specialized communities to the base architecture

In this figure, the overlap represents the common architecture and tools shared between content-owning communities that use this information architecture. New communities that define typed documents according to the architecture can then use the same tools at the outset, and refine their content-specific tools as needed.

Notices

The information provided in this document has not been submitted to any formal IBM test and is distributed "AS IS," without warranty of any kind, either express or implied. The use of this information or the implementation of any of these techniques described in this document is the reader's responsibility and depends on the reader's ability to evaluate and integrate them into their operating environment. Readers attempting to adapt these techniques to their own environments do so at their own risk.

C.6.2 Specializing topic types in DITA

The Darwin Information Typing Architecture (DITA) provides a way for documentation authors and architects to create collections of typed topics that can be easily assembled into various delivery contexts. Topic specialization is the process by which authors and architects can define topic types, while maintaining compatibility with existing style sheets, transforms, and processes. The new topic types are defined as an extension, or delta, relative to an existing topic type, thereby reducing the work necessary to define and maintain the new type.

The point of the XML-based Darwin Information Typing Architecture (DITA) is to create modular technical documents that are easy to reuse with varied display and delivery mechanisms, such as helpsets, manuals, hierarchical summaries for small-screen devices, and so on. This article explains how to put the DITA principles into practice with regards to the creation of a DTD and transforms that will support your particular information types, rather than just using the base DITA set of concept, task, and reference.

Topic specialization is the process by which authors and architects define new topic types, while maintaining compatibility with existing style sheets, transforms, and processes. The new topic types are defined as an extension, or delta, relative to an existing topic type, thereby reducing the work necessary to define and maintain the new type.

The examples used in this paper use XML DTD syntax and XSLT; if you need background on these subjects, see Resources.

Architectural context

In SGML, architectural forms are a classic way to provide mappings from one document type to another. Specialization is an architectural-forms-like solution to a more constrained problem: providing mappings from a more specific topic type to a more general topic type. Because the specific topic type is developed with the general topic type in mind, specialization can ignore many of the thornier problems that architectural forms address. This constrained domain makes specialization processes relatively easy to implement and maintain. Specialization also provides support for multi-level or hierarchical specializations, which allow more general topic types to serve as the common denominator for different specialized types.

The specialization process was created to work with DITA, although its principles and processes apply to other domains as well. This will make more sense if you consider an example: Given specialization and a generic DTD such as HTML, you can create a new document type (call it MyHTML). In MyHTML you could enforce site standards for your company, including specific rules about forms layout, heading levels, and use of font and blink tags. In addition, you could provide more specific structures for product and ordering information, to enable search engines and other applications to use the data more effectively.

Specialization lets MyHTML be defined as an extension of the HTML DTD, declaring new element types only as necessary and referencing HTML's DTD for shared elements. Wherever MyHTML declares a new element, it includes a mapping back to an existing HTML element. This mapping allows the creation of style sheets and transforms for HTML that operate equally well on MyHTML documents. When you want to handle a structure differently (for example, to format product information in a particular way), you can define a new style sheet or transform that holds the extending behavior, and then import the standard style sheet or transform to handle the rest. In other words, new behavior is added as extensions to the original style sheet, in the same way that new constraints were added as extensions to the original DTD or schema.

Specializing information types

The Darwin Information Typing Architecture is less about document types than information types. A document is considered to be made up of a number of topics, each with its own information type. A topic is, simply, a chunk of information consisting of a heading and some text, optionally divided into sections. The information type describes the content of the topic: for example, the type of a given topic might be "concept" or "task."

DITA has three types of topic: a generic topic, or information-typed concept, task, and reference topics. Concept, task, and reference topics can all be considered specializations of topic:

Additional information types can be added to the architecture as specializations of any of these three basic types, or as a peer specialization directly off of topic; and any of these additional specializations can in turn be specialized:

Each new information type is defined as an extension of an existing information type: the specializing type inherits, without duplication, any common structures; and the specializing type provides a mapping between its new elements and the general type's existing elements. Each information type is defined in its own DTD module, which defines only the new elements for that type. A document that consists of exactly one information type (for example, a task document in a help web) has a document type defined by all the modules in the information type's specialization hierarchy (for example, task.mod and topic.mod). A document type with multiple information types (for example, a book consisting of concepts, tasks, and reference topics) includes the modules for each of the information types used, as well as the modules for their ancestors (concept.mod, task.mod, reference.mod, plus their ancestor topic.mod).

Because of the separation of information types into modules, you can define new information types without affecting ancestor types. This separation gives you the following benefits:

Reduces maintenance costs: each authoring group maintains only the elements that it uniquely requires
Increases compatibility: the core information types can be centrally maintained, and changes to the core types are reflected in all specializing types
Distributes control: reusability is controlled by the reuser, instead of by the author; adding a new type does not affect the maintenance of the core type, and does not affect other users of different types

Any information-typed topic belongs to multiple types. For example, an API description is, in more general terms, a reference topic.

Specialization example: Reference topic

Consider the specialization hierarchy for a reference topic:

Table 1 expresses the relationship between the general elements in topic and the specific elements in reference. Within the table, the columns, rows, and cells indicate information types, element mappings, and elements. Table 2 explains the relationships in detail to help you interpret Table 1.

Relationships between topic and a specialization based on it

Topic	Reference
(topic.mod)	(reference.mod)
topic	reference
title
body	refbody
simpletable	properties
simpletable
section	refsyn
section

Structure	Associations
Columns	The Topic column shows basic `topic` structure, which comprises a title and body with optional sections, as declared in a DTD module called topic.mod . The Reference column shows a more specialized structure, with `reference` replacing `topic`, `refbody` replacing `body`, and `refsyn` replacing `section`; these new elements are declared in a DTD module called reference.mod .
Rows	Each row represents a mapping between the elements in that row. The elements in the Reference column specialize the elements in the Topic column. Each general element also serves as a category for more specialized elements in the same row. For example, `reference`'s `refsyn` is a kind of `section`.
Cells	Each cell in a column represents the following possibilities in relation to the cell to its left: A blank cell: The element in the cell to the left is reused as-is. For example, a `reference` `title` is the same as a `topic` `title`, and `topic`'s declaration of the `title` element can be used by `reference`. A full cell: An element that is specific to the current type replaces the more general element to the left. For example, in `reference` , `refbody` replaces the more general `body`. A split row with a blank cell: The new specializations are in addition to the more general element, which remains available in the specialized type. For example, `reference` adds properties as a special type of simpletable ( `dl`), but the general kind of `simpletable` remains available in `reference`.

The reference type module

Listing 1 illustrates not the actual reference.mod content, but a simplified version based on Table 1. The use of entities in the content models support domain specialization, as described in the domain specialization article.

<!ELEMENT reference ((%title;), (%prolog;)?, (%refbody;),(%info-types;)* )> 
<!ELEMENT refbody (%section; | refsyn | %simpletable; | properties)*>
<!ELEMENT properties ((%sthead;)?, (%strow;)+) > 
<!ELEMENT refsyn (%section;)* >

Most of the content models declared here depend on elements or entities declared in topic.mod. Therefore, if topic's structure is enhanced or changed, most of the changes will be picked up by reference automatically. Also the definition of reference remains simple: it doesn't have to redeclare any of the content that it shares with topic.

Adding specialization attributes

To expose the element mappings, we add an attribute to each element that shows its mappings to more general types.

<!ATTLIST reference class CDATA "- topic/topic reference/reference ">
<!ATTLIST refbody class CDATA "- topic/body reference/refbody ">
<!ATTLIST properties class CDATA "- topic/simpletable reference/properties "> 
<!ATTLIST refsyn class CDATA "- topic/section reference/refsyn ">

Later on, we'll talk about how to take advantage of these attributes when you write an XSL transform. See the appendix for a more in-depth description of the class attribute.

Creating an authoring DTD

Now that we've defined the type module (which declares the newly typed elements and their attributes) and added specialization attributes (which map the new type to its ancestors), we can assemble an authoring DTD.

<!--Redefine the infotype entity to exclude other topic types--> 
<!ENTITY % info-types "reftopic">
<!--Embed topic to get generic elements --> 
<!ENTITY % topic-type SYSTEM "topic.mod"> 
%topic-type; 
<!--Embed reference to get specific elements --> 
<!ENTITY % reference-type SYSTEM "reference.mod"> 
%reference-type;

Specialization example: API description

Now let's create a more specialized information type: API descriptions, which are a kind of (and therefore specialization of) reference topic:

A more specialized information type, API description

Table 3 shows part of the specialization for an information type called APIdesc, for API description. As before, each column represents an information type, with specialization occurring from left to right. That is, each information type is a specialization of its neighbor to the left. Each row represents a set of mapped elements, with more specific elements to the right mapping to more general equivalents to the left.

As before, each cell specializes the contents of the cell to its left:

A blank cell: The element to the left is picked up by the new type unchanged. For example, simpletable and refsyn are available in an API description.
A full cell: The element to the left is replaced by a more specific one. For example, APIname replaces title.
A split row with a blank cell: New elements are added to the elements on the left. For example, the API description adds a usage section as a peer of the refsyn and section elements.

Summary of APIdesc specialization

Topic	Reference	APIdesc
(topic.mod)	(reference.mod)	(APIdesc.mod)
topic	reference	APIdesc
title		APIname
body	refbody	APIbody
simpletable	properties	parameters
simpletable
section	refsyn

		usage

The APIdesc module

Here you can see that the content for an API description is actually much more restricted than the content of a general reference topic. The sequence of syntax, then usage, then parameters is now imposed, followed by optional additional sections. This sequence is a subset of the allowable structures in a reference topic, which allows any sequence of syntax, properties, and sections. In addition, the label for the usage section is now fixed as Usage, taking advantage of the spectitle attribute of section (which is there for exactly this kind of usage): with the spectitle attribute providing the section title, we can also get rid of the title element in usage's content model, making use of the predefined section.notitle.cnt entity.

<!ELEMENT APIdesc (APIname, (%prolog;)?, APIbody,(%info-types;)* )> 
<!ELEMENT APIname (%title.cnt;)*>
<!ELEMENT APIbody (refsyn,usage,parameters,(%section;)*)> 
<!ELEMENT usage (%section.notitle.cnt;)* > 
<!ATTLIST usage spectitle CDATA #FIXED "Usage"> 
<!ELEMENT parameters ((%sthead;)?, (%strow;)+)>

Adding specialization attributes

Every new element now has a mapping to all its ancestor elements.

<!ATTLIST APIdesc class CDATA "- topic/topic reference/reference APIdesc/APIdesc " >
<!ATTLIST APIname spec CDATA "- topic/title reference/title APIdesc/APIname " >
<!ATTLIST APIbody spec CDATA "- topic/body reference/refbody APIdesc/APIbody" >
<!ATTLIST parameters spec CDATA "- topic/simpletable reference/properties APIdesc/parameters "> 
<!ATTLIST usage spec CDATA "- topic/section reference/section APIdesc/usage ">

Note that APIname explicitly identifies its equivalent in both reference and topic, even though they are the same (title) in both cases. In the same way, usage explicitly maps to section in both reference and topic. This explicit identification makes it easier for processes to keep track of complex mappings. Even if you had a specialization hierarchy 10 levels deep or more, the attributes would still allow unambiguous mappings to each ancestor information type.

Authoring DTDs

<!--Redefine the infotype entity to exclude other topic types-->
<!ENTITY % info-types "APIdesc">
<!--Embed topic to get generic elements --> 
<!ENTITY % topic-type SYSTEM "topic.mod"> 
%topic-type; 
<!--Embed reference to get more specific elements --> 
<!ENTITY % reference-type SYSTEM "reference.mod"> 
%reftopic-type; 
<!--Embed APIdesc to get most specific elements --> 
<!ENTITY % APIdesc-type SYSTEM "APIdesc.mod"> 
%APIdesc-type;

Working with specialization

After a specialized type has been defined the necessary attributes have been declared, they can provide the basis for the following operations:

Applying a general style sheet or transform to a specialized topic type
Generalizing a topic of a specialized type (transforming it into a more generic topic type)
Specializing a topic of a general type (transforming it into a more specific topic type - to be used only when a topic was originally authored in specialized form, and has gone through a general stage without breaking the constraints of its original form)

Applying general style sheets or transforms

Because content written in a new information type (such as APIdesc) has mappings to equivalent or less restrictive structures in preexisting information types (such as reference and topic), the preexisting transforms and processes can be safely applied to the new content. By default, each specialized element in the new information type will be treated as an instance of its general equivalent. For example, in APIdesc the <usage> element will be treated as a topic <section> element that happens to have the fixed label "Usage".

To override this default behavior, an author can simply create a new, more specific rule for that element type, and then import the default style sheet or transform, thus extending the behavior without directly editing the original style sheet or transform. This reuse by reference reduces maintenance costs (each site maintains only the rules it uniquely requires) and increases consistency (because the core transform rules can be centrally maintained, and changes to the core rules will be reflected in all other tranforms that import them). Control over reuse has moved from the author of the transform to the reuser of the transform.

The rest of this section assumes knowledge of XSLT, the XSL Transformations language.

Requirements

This process works only if the general transforms have been enabled to handle specialized elements, and if the specialized elements include enough information for the general transform to handle them.

Requirement 1: mapping attributes

To provide the specialization information, you need to add specialization attributes, as outlined previously. After you include the attributes in your documents, they are ready to be processed by specialization-aware transforms.

Requirement 2: specialization-aware transforms

For the transform, you need template rules that check for a match against both the element name and the attribute value.

<xsl:template match="*[contains(@class," topic/simpletable "]"> 
<!--matches any element that has a class attribute that mentions
     topic/simpletable--> 
<!--do something--> 
</xsl:template>

Example: overriding a transform

To override the general transform for a specific element, the author of a new information type can create a transform that declares the new behavior for the specific element and imports the general transform to provide default behavior for the other elements.

For example, an APIdesc specialized transform could allow default handling for all specialized elements except parameters:

<xsl:import href="general-transform.xsl"/>
<xsl:template match="*[contains(@class," APIdesc/parameters "]">
 <!--do something--> 
<xsl:apply-templates/>
</xsl:template>

Both the preexisting reference properties template rule and the new parameters template rule match when they encounter a parameters element (because the parameters element is a specialized type of reference properties element), and its class attribute contains both values). However, because the parameters template is in the importing style sheet, the new template takes precedence.

Generalizing a topic

Because a specialized information type is also an instance of its ancestor types (an APIdesc is a reference topic is a topic), you can safely transform a specialized topic to one of its more generic ancestors. This upward compatibility is useful when you want to combine sets of documentation from two sources, each of which has specialized differently. The ancestor type provides a common denominator that both can be safely transformed to. This compatibility may also be useful when you have to feed topics through processes that are not specialization-aware. For example, a publication center that charges per document type or uses non-DTD-aware processes could be sent a generalized set of documents, so that they only support one document type or set of markup. However, wherever possible, you should use specialization-aware processes and transforms, so that you can avoid generalizing and process your documents in their more descriptive, specialized form.

To safely generalize a topic, you need a way to map from your information type to the target information type. You also need a way to preserve the original type in case you need round-tripping later.

The class attribute that was introduced previously serves two purposes. It provices:

The information needed to map.
A way to preserve the information to allow round-tripping.

Each level of specialization has its own set of class attributes, which in the end provide the full specialization hierarchy for all specialized elements.

Consider the APIdesc topic in Listing 11:

<APIdesc> 
 <APIname>AnAPI</APIname>
 <APIbody> 
  <refsyn>AnAPI (parm1, parm2)</refsyn>
  <usage spectitle="Usage">Use AnAPI to pass parameters to your process.
  </usage> 
  <parameters >
  ...
  </parameters>
 </APIbody> 
</APIdesc>

With the class attributes exposed (all values are provided as defaults by the DTD):

<APIdesc class="- topic/topic reference/reference APIdesc/APIdesc "> 
 <APIname class="- topic/title reference/title APIdesc/APIname ">AnAPI
 </APIname>
 <APIbody class="- topic/body reference/refbody APIdesc/APIbody ">
  <refsyn class="- topic/section reference/refsyn ">AnAPI(parm1,
  parm2)</refsyn> 
  <usage class="- topic/section reference/section APIdesc/usage "
  spectitle="Usage">
   <p class="- topic/p ">Use AnAPI to pass parameters to your process.</p>
  </usage> 
  <parameters class="topic/simpletable reference/properties APIdesc/parameters ">
  ...
  </parameters>
 </APIbody> 
</APIdesc>

From here, a single template rule can transform the entire APIdesc topic to either a reference or a generic topic. The template rule simply looks in the class attribute for the ancestor element name, and renames the current element to match.

After a transform to topic, it should look something like Listing 13:

<topic class="- topic/topic reference/reference APIdesc/APIdesc "> 
 <title class="- topic/title reference/title APIdesc/APIname ">AnAPI
 </title>
 <body class="- topic/body reference/refbody APIdesc/APIbody ">
  <section class="- topic/section reference/refsyn ">AnAPI(parm1,
  parm2)</section> 
  <section class="- topic/section reference/section APIdesc/usage "
  spectitle="Usage">
   <p class="- topic/p ">Use AnAPI to pass parameters to your process.</p>
  </section> 
  <simpletable class="topic/simpletable reference/properties APIdesc/parameters ">
  ...
  </simpletable>
 </body> 
</topic>

Even after generalization, specialization-aware transforms can continue to treat the topic as an APIdesc, because the transforms can look in the class attribute for information about the element type hierarchy.

From here, it is possible to round-trip by reversing the transformation (looking in the class attribute for the specializing element name, and renaming the current element to match). Whenever the class attribute doesn't list the target (the first section has no APIdesc value), the element is changed to the last value listed (so the first section becomes, accurately, a refsyn).

However, if anyone changes the structure of the content while it is a generic topic (as by changing the order of sections), the result might not be valid anymore under the specialized information type (which in theAPIdesc case enforces a particular sequence of information in the APIbody). So although mapping to a more general type is always safe, mapping back to a specialized type can be problematic: The specialized type has more rules, which make the content specialized. But those rules aren't enforced while the content is encoded more generally.

Specializing a topic

It is relatively trivial to specialize a general topic if the content was originally authored as a specialized type. However, a more complex case can result if you have authored content at a general level that you now want to type more precisely.

For example, suppose that you create a set of reference topics. Then, having analyzed your content, you realize that you have a consistent pattern. Now you want to enforce this pattern and describe it with a specialized information type (for example, API descriptions). In order to specialize, you need to first create the target DTD and then add enough information to your content to allow it to be migrated.

You can put the specializing information in either of two places:

Add it to the class attribute. You need to be careful to get the order correct, and include all ancestor type values.
Or give the name of the target element in an outputclass attribute, migrate based on that value, and add the class attribute values afterward.

In either case, before migration you can run a validation transform that looks for the appropriate attribute, then checks that the content of the element will be valid under the specialized content model. You can use a tool like Schematron to generate both the validating transform and the migrating transform, or you can migrate first and use the specialized DTD to validate that the migration was successful.

Specializing with schemas

Like the XML DTD syntax, the XML Schema language is a way of defining a vocabulary (elements and attributes) and a set of constraints on that vocabulary (such as content models, or fixed vs. implied attributes). It has a built-in specialization mechanism, which includes the capability to restrict allowable specializations. Using the XML Schema language instead of DTDs would make it much easier to validate that specialized information types represent valid subsets of generic types, which ensures smooth processing by generic translation and publishing transforms.

Unlike DTDs, XML schemas are expressed as XML documents. As a result, they can be processed in ways that DTDs cannot. For example, we can maintain a single XML schema and then use XSL to generate two versions:

An authoring version of it that eliminates any fixed attributes and any overridden elements
A processor-ready version of it that includes the class attributes that drive the translation and publishing transforms

However, XML schemas are not yet popular enough to adopt wholeheartedly. The main problems are a lack of authoring tools, and incompatibilities between the implementations of an evolving standard. These problems should be remedied by the industry over the next year or so, as the standard is finalized and schemas become more widely adopted and supported.

Summary

You can create a specialized information type by using this general procedure:

Identify the elements that you need.
Identify the mapping to elements of a more general type.
Verify that the content models of specialized elements are more restrictive than their general equivalents.
Create a type module file that holds your specialized element and attribute declarations (including the class attribute).
Create an authoring DTD file that imports the appropriate type modules.

You can create specialized XSL transforms by using this general procedure:

Create a new transform for your information type.
Import the existing transform that you want to extend.
Identify the elements that you need to treat specially.
Add template rules that match those elements, based on their class attribute content.

Appendix: Rules for specialization

Although you could create a new element equivalent for any tag in a general DTD, this work is useless to you as an author unless the content models that would include the tag are also specialized. In the APIdesc example, the parameters element is not valid content anywhere in topic or reference. For it to be used, you need to create valid contexts for parameters, all the way up to the topic-level container. To expose the parameters element to your authors, you need to specialize the following parts:

A body element, to allow parameters as valid content (giving us APIbody)
A topic element, to allow the specialized body (giving us APIdesc)

This domino effect can be avoided by using domain specialization. If you truly just want to add some new variant structures to an existing information type, use domain specialization instead of topic specialization (see Specializing domains in DITA).

To ensure that the specialized elements are more constrained than their general equivalents (that is, that they allow a proper subset of the structures that the general equivalent allows), you need to look at the content model of the general element. You can safely change the content model of your specialized element as shown in Table A:

Summary of specialization rules

Content type	Allowed specialization	Example (Special specializing General)
Required	Rename only	<!ELEMENT General(a)> <!ELEMENT Special(a.1)>
Optional (?)	Rename, make required, or delete	<!ELEMENT General(a?)> <!ELEMENT Special(a.1?)> <!ELEMENT Special(a.1)> <!ELEMENT Special EMPTY>
One or more (+)	Rename, make required, split into a required element plus others, split into one or more elements plus others.	<!ELEMENT General(a+)> <!ELEMENT Special(a.1+)> <!ELEMENT Special(a.1)> <!ELEMENT Special(a.1,a.2,a.3+,a.4)> <!ELEMENT Special(a.1+,a.2,a.3)>
Zero or more (*)	Rename, make required, make optional, split into a required element plus others, split into an optional element plus others, split into one-or-more plus others, split into zero-or-more plus others, or delete	<!ELEMENT General(a)> <!ELEMENT Special(a.1)> <!ELEMENT Special(a.1)> <!ELEMENT Special(a.1?)> <!ELEMENT Special(a.1,a.2,a.3+,a.4)> <!ELEMENT Special(a.1?,a.2,a.3+,a.4)> <!ELEMENT Special(a.1+,a.2,a.3)> <!ELEMENT Special(a.1,a.2?,a.3*)> <!ELEMENT Special EMPTY>
Either-or	Rename, or choose one	<!ELEMENT General (a\|b)> <!ELEMENT Special (a.1\|b.1)> <!ELEMENT Special (a.1)>

Extended example

You have a general element General, with the content model (a,b?,(c|d+)). This definition means that a General always contains element a, optionally followed by element b, and always ends with either c or one or more d's.

<!ELEMENT General (a,b?,(c|d+))>

When you specialize General to create Special, its content model must be the same or more restrictive: It cannot allow more things than General did, or you will not be able to map upward, or guarantee the correct behavior of general processes, transforms, or style sheets.

Leaving aside renaming (which is always allowed, and simply means that you are also specializing some of the elements that Special can contain), here are some valid changes that you could make to the content model of Special, resulting in the same or more restrictive content rules:

<!ELEMENT Special (a,b,(c|d))>

Special now requires b to be present, instead of optional, and allows only one d. It safely maps to General.

<!ELEMENT Special (a,b?,c)>

Special now requires c to be present, and no longer allows d. It safely maps to General.

<!ELEMENT Special (a,b?,d1,d2,d3)>

Special now requires three specializations of d to be present, and does not allow c. It safely maps to General.

Details of the class attribute

Every element must have a class attribute. The class attribute starts and ends with white space, and contains a list of blank-delimited values. Each value has two parts: the first part identifies a topic type, and the second part (after a /) identifies an element type. The class attribute value should be declared as a default attribute value in the DTD. Generally, it should not be modified by the author.

Example:

<appstep class="- topic/li task:step bctask/appstep ">A specialized step</appstep>

When a specialized type declares new elements, it must provide a class attribute for the new element. The class attribute must include a mapping for every topic type in the specialized type's ancestry, even those in which no element renaming occurred. The mapping should start with topic, and finish with the current element type.

Example:

<appname class="- topic/kwd task/kwd bctask/appname ">

This is necessary so that generalizing and specializing transforms can map values simply and accurately. For example, if task/kwd was missing as a value, and I decided to map this bctask up to a task topic, then the transform would have to guess whether to map to kwd (appropriate if task is more general, which it is) or leave as appname (appropriate if task were more specialized, which it isn't). By always providing mappings for more general values, we can then apply the simple rule that missing mappings must by default be to more specialized values, which means the last value in the list is appropriate. While this example is trivial, more complicated hierarchies (say, five levels deep, with renaming occurring at two and four only) make this kind of mapping essential.

A specialized type does not need to change the class attribute for elements that it does not specialize, but simply reuses by reference from more generic levels. For example, since task and bctask use the p element without specializing it, they don't need to declare mappings for it.

A specialized type only declares class attributes for the elements that it uniquely declares. It does not need to declare class attributes for elements that it reuses or inherits.

Using the class attribute

Applying an XSLT template based on class attribute values allows a transform to be applied to whole branches of element types, instead of just a single element type.

Wherever you would check for element name (any XPath statement that contains an element name value), you need to enhance this to instead check the contents of the element's class attribute. Even if the element is unrecognized, the class attribute can let the transform know that the element belongs to a class of known elements, and can be safely treated according to their rules.

Example:

<xsl:template match="*[contains(@class,' topic/li ')]">
This match statement will work on any li element it encounters. It will also work on step and appstep elements, even though it doesn't know what they are specifically, because the class attribute tells the template what they are generally.
<xsl:template match="*[contains(@class,' task/step ')]">

This match statement won't work on generic li elements, but it will work on both step elements and appstep elements; even though it doesn't know what an appstep is, it knows to treat it like a step.

Be sure to include a leading and trailing blank in your class attribute string check. Otherwise you could get false matches (without the blanks, 'task/step' would match on 'notatask/stepaway', when it shouldn't).

The class attribute in domains specialization

When you create a domains specialization, the new elements still need a class attribute, but should start with a "+" instead of a "-". This signals any generalization transforms to treat the element differently: a domains-aware generalization transform may have different logic for handling domains than for handling topic specializations.

Domain specializations should be derived either from topic (the root topic type), or from another domain specialization. Do not create a domain by specializing an already specialized topic type: this can result in unpredictable generalization behavior, and is not currently supported by the architecture.

Notices

C.6.3 Specializing domains in DITA

In current approaches, DTDs are static. As a result, DTD designers try to cover every contingency and, when this effort fails, users have to force their information to fit existing types. DITA changes this situation by giving information architects and developers the power to extend a base DTD to cover their domains.

The Darwin Information Typing Architecture (DITA) is an XML architecture for extensible technical information. A domain extends DITA with a set of elements whose names and content models are unique to an organization or field of knowledge. Architects and authors can combine elements from any number of domains, leading to great flexibility and precision in capturing the semantics and structure of their information. In this overview, you learn how to define your own domains.

Introducing domain specialization

In DITA, the topic is the basic unit of processable content. The topic provides the title, metadata, and structure for the content. Some topic types provide very simple content structures. For example, the concept topic has a single concept body for all of the concept content. By contrast, a task topic articulates a structure that distinguishes pieces of the task content, such as the prerequisites, steps, and results.

In most cases, these topic structures contain content elements that are not specific to the topic type. For example, both the concept body and the task prerequisites permit common block elements such as p paragraphs and ul unordered lists.

Domain specialization lets you define new types of content elements independently of topic type. That is, you can derive new phrase or block elements from the existing phrase and block elements. You can use a specialized content element within any topic structure where its base element is allowed. For instance, because a p paragraph can appear within a concept body or task prerequisite, a specialized paragraph could appear there, too.

Here's an analogy from the kitchen. You might think of topics as types of containers for preparing food in different ways, such as a basic frying pan, blender, and baking dish. The content elements are like the ingredients that go into these containers, such as spices, flour, and eggs. The domain resembles a specialty grocer who provides ingredients for a particular cuisine. Your pot might contain chorizo from the carnicería when you're cooking TexMex or risotto when you're cooking Italian. Similarly, your topics can contain elements from the programming domain when you're writing about a programming language or elements from the UI domain when you're writing about a GUI application.

DITA has broad tastes, so you can mix domains as needed. If you're describing how to program GUI applications, your topics can draw on elements from both the programming and UI domains. You can also create new domains for your content. For instance, a new domain could provide elements for describing hardware devices. You can also reuse new domains created by others, expanding the variety of what you can cook up.

In a more formal definition, topic specialization starts with the containing element and works from the top down. Domain specialization, on the other hand, starts with the contained element and works from the bottom up.

Understanding the base domains

A DITA domain collects a set of specialized content elements for some purpose. In effect, a domain provides a specialized vocabulary. With the base DITA package, you receive the following domains:

Domain	Purpose
highlight	To highlight text with styles such as bold, italic, and monospace
programming	To define the syntax and give examples of programming languages
software	To describe the operation of a software program
UI	To describe the user interface of a software program

In most domains, a specialized element adds semantics to the base element. For example, the apiname element of the programming domain extends the basic keyword element with the semantic of a name within an API.

The highlight domain is a special case. The elements in this domain provide styled presentation instead of semantic or structural markup. The highlight styles give authors a practical way to mark up phrases for which a semantic has not been defined.

Providing such highlight styles through a domain resolves a long-standing dispute for publication DTDs. Purists can omit the highlight domain to enforce documents that should be strictly semantic. Pragmatists can include the highlight domain to provide expressive flexibility for real-world authoring. A semipragmatist could even include the highlight domain in conceptual documents to support expressive authoring but omit the highlight domain from reference documents to enforce strict semantic tagging.

More generally, you can define documents with any combination of domains and topics. As we'll see in Generalizing a domain, the resulting documents can still be exchanged.

Combining an existing topic and domain

The DITA package provides a DTD for each topic type and an omnibus DTD (ditabase.dtd) that defines all of the topic types. Each of these DTDs includes all of the predefined DITA domains. Thus, topics written against one of the supplied DTDs can use all of the predefined domain specializations.

Behind the scenes, a DITA DTD is just a shell. Elements are actually defined in other modules, which are included in the DTD. Through these modules, DITA provides you with the building blocks to create new combinations of topic types and domains.

When you add a domain to your DITA installation, the new domain provides you with additional modules. You can use the additional modules to incorporate the domain into the existing DTDs or to create new DTDs.

In particular, each domain is implemented with two files:

A file that declares the entities for the domain. This file has the .ent extension.
A file that declares the elements for the domain. This file has the .mod extension.

As an example, let's say we're authoring the reference topics for a programming language. We're purists about presentation, so we want to exclude the highlight domain. We also have no need for the software or UI domains in this reference. We could address this scenario by defining a new shell DTD that combines the reference topic with the programming domain, excluding the other domains.

A shell DTD has a consistent design pattern with a few well-defined sections. The instructions in these sections perform the following actions:

Declare the entities for the domains.

In the scenario, this section would include the programming domain entities:

<!ENTITY % pr-d-dec PUBLIC "-//IBM//ENTITIES DITA Programming Domain//EN" "programming-domain.ent">
  %pr-d-dec;

Redefine the entities for the base content elements to add the specialized content elements from the domains.

This section is crucial for domain specialization. Here, the design pattern makes use of two kinds of entities. Each base content element has an element entity to identify itself and its specializations. Each domain provides a separate domain specialization entity to list the specializations that it provides for a base element. By combining the two kinds of entities, the shell DTD allows the specialized content elements to be used in the same contexts as the base element.

In the scenario, the pre element entity identifies the pre element (which, as in HTML, contains preformatted text) and its specializations. The programming domain provides the pr-d-pre domain specialization entity to list the specializations for the pre base element. The same pattern is used for the other base elements specialized by the programming domain:
```
<!ENTITY % pre     "pre     | %pr-d-pre;">
<!ENTITY % keyword "keyword | %pr-d-keyword;">
<!ENTITY % ph      "ph      | %pr-d-ph;">
<!ENTITY % fig     "fig     | %pr-d-fig;">
<!ENTITY % dl      "dl      | %pr-d-dl;">
```
To learn which content elements are specialized by a domain, you can look at the entity declaration file for the domain.
Define the domains attribute of the topic elements to declare the domains represented in the document.

Like the class attribute, the domains attribute identifies dependencies. Where the class attribute identifies base elements, the domains attribute identifies the domains available within a topic. Each domain provides a domain identification entity to identify itself in the domains attribute.

In the scenario, the only topic is the reference topic. The only domain is the programming domain, which is identified by the pr-d-att domain identification entity:
```
<!ATTLIST reference  domains CDATA "&pr-d-att;">
```
Redefine the infotypes entity to specify the topic types that can be nested within a topic.

In the scenario, this section would declare the reference topic:
```
<!ENTITY % info-types "reference">
```

Define the elements for the topic type, including the base topics.

In the scenario, this section would include the base topic and reference topic modules:

<!ENTITY % topic-type PUBLIC "-//IBM//ELEMENTS DITA Topic//EN" "topic.mod">
  %topic-type;
<!ENTITY % reference-typemod PUBLIC "-//IBM//ELEMENTS DITA Reference//EN" "reference.mod">
  %reference-typemod;

Define the elements for the domains.

In the scenario, this section would include the programming domain definition module:
```
<!ENTITY % pr-d-def PUBLIC "-//IBM//ELEMENTS DITA Programming Domain//EN" "programming-domain.mod">
  %pr-d-def;
```

Often, it would be easiest to work by copying an existing DTD and adding or removing topics or domains. In the scenario, it would be easiest to start with reference.dtd and remove the highlight, software, and UI domains as shown with the underlined text below.

<!--vocabulary declarations-->
<!ENTITY % ui-d-dec PUBLIC "-//IBM//ENTITIES DITA User Interface Domain//EN" "ui-domain.ent">
  %ui-d-dec;
<!ENTITY % hi-d-dec PUBLIC "-//IBM//ENTITIES DITA Highlight Domain//EN" "highlight-domain.ent">
  %hi-d-dec;
<!ENTITY % pr-d-dec PUBLIC "-//IBM//ENTITIES DITA Programming Domain//EN" "programming-domain.ent">
  %pr-d-dec;
<!ENTITY % sw-d-dec PUBLIC "-//IBM//ENTITIES DITA Software Domain//EN" "software-domain.ent">
  %sw-d-dec;

<!--vocabulary substitution-->
<!ENTITY % pre     "pre     | %pr-d-pre;     | %sw-d-pre;">
<!ENTITY % keyword "keyword | %pr-d-keyword; | %sw-d-keyword; | %ui-d-keyword;">
<!ENTITY % ph      "ph      | %pr-d-ph;      | %sw-d-ph;      | %hi-d-ph; | %ui-d-ph;">
<!ENTITY % fig     "fig     | %pr-d-fig;">
<!ENTITY % dl      "dl      | %pr-d-dl;">

<!--vocabulary attributes-->
<!ATTLIST reference  domains CDATA "&ui-d-att; &hi-d-att; &pr-d-att; &sw-d-att;">

<!--Redefine the infotype entity to exclude other topic types-->
<!ENTITY % info-types "reference">

<!--Embed topic to get generic elements -->
<!ENTITY % topic-type PUBLIC "-//IBM//ELEMENTS DITA Topic//EN" "topic.mod">
  %topic-type;

<!--Embed reference to get specific elements -->
<!ENTITY % reference-typemod PUBLIC "-//IBM//ELEMENTS DITA Reference//EN" "reference.mod">
  %reference-typemod;

<!--vocabulary definitions-->
<!ENTITY % ui-d-def PUBLIC "-//IBM//ELEMENTS DITA User Interface Domain//EN" "ui-domain.mod">
  %ui-d-def;
<!ENTITY % hi-d-def PUBLIC "-//IBM//ELEMENTS DITA Highlight Domain//EN" "highlight-domain.mod">
  %hi-d-def;
<!ENTITY % pr-d-def PUBLIC "-//IBM//ELEMENTS DITA Programming Domain//EN" "programming-domain.mod">
  %pr-d-def;
<!ENTITY % sw-d-def PUBLIC "-//IBM//ELEMENTS DITA Software Domain//EN" "software-domain.mod">
  %sw-d-def;

Creating a domain specialization

For some documents, you may need new types of content elements. In a common scenario, you need to mark up phrases that have special semantics. You can handle such requirements by creating new specializations of existing content elements and providing a domain to reuse the new content elements within topic structures.

As an example, let's say we're writing the documentation for a class library. We intend to write processes that will index the documentation by class, field, and method. To support this processing, we need to mark up the names of classes, fields, and methods within the topic content, as in the following sample:

<p>The <classname>String</classname> class provides
the <fieldname>length</fieldname> field and 
the <methodname>concatenate()</methodname> method.
</p>

We must define new content elements for these names. Because the names are special types of names within an API, we can specialize the new elements from the apiname element provided by the programming domain.

The design pattern for a domain requires an abbreviation to represent the domain. A sensible abbreviation for the class library domain might be cl. The identifier for a domain consists of the abbreviation followed by -d (for domain).

As noted in Combining an existing topic and domain, the domain requires an entity declaration file and an element definition file.

Writing the entity declaration file

The entity declaration file has sections that perform the following actions:

Define the domain specialization entities.

A domain specialization entity lists the specialized elements provided by the domain for a base element. For clarity, the entity name is composed of the domain identifier and the base element name. The domain provides domain specialization entities for ancestor elements as well as base elements.

In the scenario, the domain defines a domain specialization entity for the apiname base element as well as the keyword ancestor element (which is the base element for apiname):
```
<!ENTITY % cl-d-apiname "classname | fieldname | methodname">
<!ENTITY % cl-d-keyword "classname | fieldname | methodname">
```
Define the domain identification entity.

The domain identification entity lists the topic type as well as the domain and other domains for which the current domain has dependencies. Each domain is identified by its domain identifier. The list is enclosed in parentheses. For clarity, the entity name is composed of the domain identifier and -att.

In the scenario, the class library domain has a dependency on the programming domain, which provides the apiname element:
```
<!ENTITY cl-d-att "(topic pr-d cl-d)">
```

The complete entity declaration file would look as follows:

<!ENTITY % cl-d-apiname "classname | fieldname | methodname">
<!ENTITY % cl-d-keyword "classname | fieldname | methodname">

<!ENTITY cl-d-att "(topic pr-d cl-d)">

Writing the element definition file

The element definition file has sections that perform the following actions:

Define the content element entities for the elements introduced by the domain.

These entities permit other domains to specialize from the elements of the current domain.

In the scenario, the class library domain follows this practice so that additional domains can be added in the future. The domain defines entities for the three new elements:
```
<!ENTITY % classname  "classname">
<!ENTITY % fieldname  "fieldname">
<!ENTITY % methodname "methodname">
```
Define the elements.

The specialized content model must be consistent with the content model for the base element. That is, any possible contents of the specialized element must be generalizable to valid contents for the base element. Within that limitation, considerable variation is possible. Specialized elements can be substituted for elements in the base content model. Optional elements can be omitted or required. An element with multiple occurrences can be replaced with a list of specializations of that element, and so on.

The specialized content model should always identify elements through the element entity rather than directly by name. This practice lets other domains merge their specializations into the current domain.

In the scenario, the elements have simple character content:
```
<!ELEMENT classname        (#PCDATA)>
<!ELEMENT fieldname        (#PCDATA)>
<!ELEMENT methodname       (#PCDATA)>
```
Define the specialization hierarchy for the element with class attribute.

For a domain element, the value of the attribute must start with a plus sign. Elements provided by domains should be qualified by the domain identifier.

In the scenario, specialization hierarchies include the keyword ancestor element provided by the base topic and the apiname element provided by the programming domain:
```
<!ATTLIST classname      class CDATA "+ topic/keyword pr-d/apiname cl-d/classname ">
<!ATTLIST fieldname      class CDATA "+ topic/keyword pr-d/apiname cl-d/fieldname ">
<!ATTLIST methodname     class CDATA "+ topic/keyword pr-d/apiname cl-d/methodname ">
```

The complete element definition file would look as follows:

<!ENTITY % classname  "classname">
<!ENTITY % fieldname  "fieldname">
<!ENTITY % methodname "methodname">

<!ELEMENT classname        (#PCDATA)>
<!ELEMENT fieldname        (#PCDATA)>
<!ELEMENT methodname       (#PCDATA)>

<!ATTLIST classname      class CDATA "+ topic/keyword pr-d/apiname cl-d/classname ">
<!ATTLIST fieldname      class CDATA "+ topic/keyword pr-d/apiname cl-d/fieldname ">
<!ATTLIST methodname     class CDATA "+ topic/keyword pr-d/apiname cl-d/methodname ">

Writing the shell DTD

After creating the domain files, you can write shell DTDs to combine the domain with topics and other domains. The shell DTD must include all domain dependencies.

In the scenario, the shell DTD combines the class library domain with the concept, reference, and task topics and the programming domain. The portions specific to the class library domain are highlighted below in bold:

<!--vocabulary declarations-->
<!ENTITY % pr-d-dec PUBLIC "-//IBM//ENTITIES DITA Programming Domain//EN" "programming-domain.ent">
  %pr-d-dec;
<!ENTITY % cl-d-dec SYSTEM "classlib-domain.ent"> %cl-d-dec;

<!--vocabulary substitution-->
<!ENTITY % pre     "pre     | %pr-d-pre;">
<!ENTITY % keyword "keyword | %pr-d-keyword; | %cl-d-apiname;">
<!ENTITY % ph      "ph      | %pr-d-ph;">
<!ENTITY % fig     "fig     | %pr-d-fig;">
<!ENTITY % dl      "dl      | %pr-d-dl;">
<!ENTITY % apiname "apiname | %cl-d-apiname;">

<!--vocabulary attributes-->
<!ATTLIST concept    domains CDATA "&pr-d-att; &cl-d-att;">
<!ATTLIST reference  domains CDATA "&pr-d-att; &cl-d-att;">
<!ATTLIST task       domains CDATA "&pr-d-att; &cl-d-att;">

<!--Redefine the infotype entity to exclude other topic types-->
<!ENTITY % info-types "concept | reference | task">

<!--Embed topic to get generic elements -->
<!ENTITY % topic-type PUBLIC "-//IBM//ELEMENTS DITA Topic//EN" "topic.mod">
  %topic-type;

<!--Embed topic types to get specific topic structures-->
<!ENTITY % concept-typemod PUBLIC "-//IBM//ELEMENTS DITA Concept//EN" "concept.mod">
  %concept-typemod;
<!ENTITY % reference-typemod PUBLIC "-//IBM//ELEMENTS DITA Reference//EN" "reference.mod">
  %reference-typemod;
<!ENTITY % task-typemod PUBLIC "-//IBM//ELEMENTS DITA Task//EN" "task.mod">
  %task-typemod;

<!--vocabulary definitions-->
<!ENTITY % pr-d-def PUBLIC "-//IBM//ELEMENTS DITA Programming Domain//EN" "programming-domain.mod">
  %pr-d-def;
<!ENTITY % cl-d-def SYSTEM "classlib-domain.mod"> %cl-d-def;

Notice that the class library phrases are added to the element entity for keyword as well as for apiname. This addition makes the class library phrases available within topic structures that allow keywords and not just in topic structures that explicitly allow API names. In fact, the structures of the reference topic specify only keywords, but it's good practice to add the domain specialization entities to all ancestor elements.

Considerations for domain specialization

When you define new types of topics or domain elements, remember that the hierarchies for topic specialization and domain specialization must be distinct. A specialized topic cannot use a domain element in a content model. Similarly, a domain element can specialize only from an element in the base topic or in another domain. That is, a topic and domain cannot have dependencies. To combine topics and domains, use a shell DTD.

When specializing elements with internal structure including the ul, ol, and dl lists as well as table and simpletable, you should specialize the entire content element. Creating special types of pieces of the internal structure independently of the whole content structure usually doesn't make much sense. For example, you usually want to create a special type of list instead of a special type of li list item for ordinary ul and ol lists.

You should never specialize from the elements of the highlight domain. These style elements do not have a specific semantic. Although the formatting of the highlight styles might seem convenient, you might find you need to change the formatting later.

As noted previously, you should use element entities instead of literal element names in content models. The element entities are necessary to permit domain specialization.

The content model should allow for the possibility that the element entity might expand to a list. When applying a modifier to the element entity, you should enclose the element entity in parentheses. Otherwise, the modifier will apply only to the last element if the entity expands to a list. Similar issues affect an element entity in a sequence:

..., ( %classname; ), ...
... ( %classname; )? ...

... ( %classname; )* ...
... ( %classname; )+ ...
... | %classname; | ...

The parentheses aren't needed if the element entity is already in a list.

Generalizing a domain

As with topics, a specialized content element can be generalized to one of its ancestor elements. In the previous scenario, a classname can generalize to apiname or even keyword. As a result, documents using different domains but the same topics can be exchanged or merged without having to generalize the topics.

To return to the highlight style controversy mentioned in Understanding the base domains, a pragmatic document authored with highlight domain will contain phrases like the following:

... the <b>important</b> point is ...

When the document is generalized to the same topic but without the highlight domain, the pragmatic b element becomes a purist ph element, indicating that the phrase is special without introducing presentation:

... the <ph class="+ topic/ph hi-d/b ">important</ph> point is ...

In the previous scenario, the class library authors could send their topics to another DITA shop without the class library domain. The recipients would generalize the class library topics, converting the classname elements to apiname base elements. After generalization, the recipients could edit and process the class, field, and method names in the same way as any other API names. That is, the situation would be the same as if the senders had decided not to distinguish class, field, and method names and, instead, had marked up these names as generic API names.

As an alternative, the recipients could decide to add the class library domain to their definitions. In this approach, the senders would provide not only their topics but also the entity declaration and element definition files for the domain. The recipients would add the class library domain to their shell DTD. The recipients could then work with classname elements without having to generalize.

The recipients can use additional domains with no impact on interoperability. That is, the shell DTD for the recipients could use more domains than the shell DTD for the senders without creating any need to modify the topics.

Note

When defining specializations, you should avoid introducing a dependency on special processing that lacks a graceful fallback to the processing for the base element. In the scenario, special processing for the classname element might generate a literal class label in the output to save some typing and produce consistent labels. After automated generalization, however, the label would not be supplied by the base processing for the apiname element. Thus, the dependency would require a special generalization transform to append the literal class label to classname elements in the source file.

Summary

Through topic specialization and domains, DITA provides the following benefits:

Simpler topic design.

The document designer can focus on the structure of the topic without having to foresee every variety of content used within the structure.
Simpler topic hierarchies.

The document designer can add new types of content without having to add new types of topics.
Extensible content for existing topics.

The document designer can reuse existing types of topics with new types of content.
Semantic precision.

Content elements with more specific semantics can be derived from existing elements and used freely within documents.
Simpler element lists for authors.

The document designer can select domains to minimize the element set. Authors can learn the elements that are appropriate for the document instead of learning to disregard unneeded elements.

In short, the DITA domain feature provides for great flexibility in extending and reusing information types. The highlight, programming, and UI domains provided with the base DITA release are only the beginning of what can be accomplished.

Notices

How to define a formal information architecture with DITA map domains

The benefits of formal information typing are well known for the content of topics, but collections of topics also benefit from formal organizing structure. Such formal structures guide authors while they assemble collections of topics and ensure consistent large-scale patterns of information for the user. Using DITA map domains, a designer can define a formal information architecture that can be reused in many deliverables.

This article explains the design technique for creating DITA map domains. As an example, the article walks through the definition for assembling a set of topics as a how-to. Such a how-to could be one reusable design component within an information architecture.

Formal information architecture

Information architecture can be summarized as the design discipline that organizes information and its navigation so an audience can acquire knowledge easily and efficiently. For instance, the information architecture of a web site often provides a hierarchy of web pages for drilling down from general to detailed information, different types of web pages for different purposes such as news and documentation, and so on.

An information architecture is subliminal when it works well. The lack of information architecture is glaring when it works poorly. The user cannot find information or, even worse, cannot recognize or assimilate information when by chance it is encountered. You probably have experience with websites that are poorly organized or uneven in their approach, so that conventions learned in part of the website have no application elsewhere. Extracting knowledge from such information resources is exhausting, and you quickly abandon the effort and seek the information elsewhere.

Currently, information architects work by defining the architecture through guidelines and instructions to the writer. A better approach is to formalize the architecture through an XML design that is validated by the XML editor or parser. This formal approach has the following benefits:

Authors receive guidance from the markup while working.
Information with the same purpose is consistent across deliverables.
Information for a purpose is complete.
Processing can rely on the structure of the information and operate on the declared semantics of the information.

The following drawings illustrate the gain in clarity and consistency by applying a design to produce a formal information architecture:

Casual architecture	Applied design	Formal architecture

In short, the formal design acts as a kind of blueprint to be fullfilled by the writer.

Specializing topics and maps

DITA supports the definition of a formal information architecture through topics and map types. The topic type defines the information architecture within topics (the micro level) while the map type defines the information architecture across topics (the macro level).

The base topic and map types are general and flexible so they can accomodate a wide variety of readable information. You specialize these general types to define the restricted types required for your information architecture.

Topic: The topic type mandates the structure for the content of a topic. For instance, the DITA distribution includes a task type that mandates a list of steps as part of the topic content. This specialized topic type provides guidance to the author and ensures the consistency of all task topics. Processing can rely on this consistency and semantic precision. For instance, the processing for the task type could format the task steps as checkable boxes.
Map: The map type mandates the structure for a collection of topics. A map can define the navigation hierarchy for a help system or the sequence and nesting of topics in a book. For instance, the DITA distribution includes a bookmap demo that mandates a sequence of preface, chapter, and appendix roles for the top-level topics. This specialized map type ensures that the collection of topics conforms to a basic book structure.

Without formal types, the information architecture is defined only through editorial guidelines. Different authors may interpret or conform to the guidelines in varying degrees, resulting in inconsistency and impredictability. By contrast, the formal types ensure that the design that can be repeated for many deliverables.

The how-to collection

One typical purpose for a collection of topics is explain how to accomplish a specific goal. A how-to assembles the relevant topics and arranges them in a typical sequence for one way to reach that goal. A standard design pattern for the how-to collection might consist of an introduction topic, some background concepts, some task and example topics, and a summary.

A help system or book might have several how-tos, for instance, on setting up web authentication, reading a database from a web application, and so on. Or, a web provider might publish an ongoing series of how-to articles on technical subjects. Thus, designing a formal how-to pattern would be useful so that all how-tos are consistent regardless of the writer.

Note that formalizing a collection doesn't prevent topic reuse but, instead, guides topic reuse so that appropriate types of topics are used at positions within the collection. For example, in the how-to, concept topics will appear only as background before the tasks rather than in the middle of the how-to.

Map specialization

Among the many capabilities added to maps by DITA 1.3 is specialization through map domains. Instead of packaging specializations of elements for topic content, however, you specialize elements for map content, typically thetopicref. The specialized topicrefelement lets authors specify semantics or constraints on collections of topics. By packaging the topicref specializations as a map domain rather than as a map type, you can reuse the formal collection design in many different map types.

A specialized topicrefcan be used for the following purposes:

To restrict the references to topics of a specialized type. For instance, a conceptref refers only to concept topics (including specialized concepts).
To assign a topic a topic to a role within a collection. For instance, the topic identified by a summaryref could provide the concluding explanation for a collection.
To restrict the contents of the collection, requiring specific topic types or requiring topics to act in specific roles at specified positions within the collection.

Drawing on all of these capabilities, we can define a formal structure for a how-to collection.

Implementing a map domain

A map domain uses the same DTD design pattern as a topic domain. See specializing domains for the details on the domain design pattern, which aren't repeated here. Instead, this article summarizes the application of the domain DTD design pattern to maps.

Create a domain entities file to declare the elements extending the topicref element.
Create a domain definition module to define the elements including their element entities, content and attribute definitions, and the architectural class attribute.
Create a shell DTD that assembles the base map module and the domain entities file and definition module.
Create map collections from the shell DTD.

Declaring the map domain entities

The entities file for the how-to domain defines the howto, conceptref, taskref, and exampleref extensions for the topicref element and defines the how-to domain declaration for the domain attributes entity:

<!ENTITY % howto-d-topicref "howto">
<!ENTITY howto-d-att "(map howto-d)">

Defining the map domain module

The definition module for the how-to domain starts with the element entities so the new elements could, in turn, be extended by subsequent specializations. Of these new elements, only howto has been declared in the entities file because the other new elements should only appear in the child list of the howto element. (In fact, reference typing elements such as conceptref and taskref might also be defined in the entities file for reuse in other specialized child lists.)

<!ENTITY % howto       "howto">
<!ENTITY % conceptref  "conceptref">
<!ENTITY % taskref     "taskref">
<!ENTITY % exampleref  "exampleref">
<!ENTITY % summaryref  "summaryref">

The definition module goes on to define the elements. The definition for the howto element restricts the content list for the collection to the metadata for the topic, references to any number of concept topics, references to task topics and optional example topics, and a topic acting in the role of a concluding summary. In addition, the howto element refers to the topic that provides an overview of the contents.

<!ELEMENT howto ((%topicmeta;)?, (%conceptref;)*, ((%taskref;), (%exampleref;)?)+,
      (%summaryref;))>
<!ATTLIST howto
  navtitle     CDATA     #IMPLIED
  id           ID        #IMPLIED
  href         CDATA     #IMPLIED
  keyref       CDATA     #IMPLIED
  query        CDATA     #IMPLIED
  conref       CDATA     #IMPLIED
  copy-to      CDATA     #IMPLIED
  %topicref-atts;
  %select-atts;>

The conceptref and taskref elements have a restricted type, meaning that validating processing is obligated to report an error if the referenced topic doesn't have the declared type (or a specialization from the declared type):

<!ELEMENT conceptref ((%topicmeta;)?, (%conceptref;)*)>
<!ATTLIST conceptref
  href         CDATA     #IMPLIED
  type         CDATA     "concept"
  ...>
<!ELEMENT taskref    ((%topicmeta;)?, (%taskref;)*)>
<!ATTLIST taskref
  href         CDATA     #IMPLIED
  type         CDATA     "task"
  ...>

The exampleref and summaryref elements don't restrict the type but, instead, assign roles to the referenced topics. Because the content list of the howto collection topic allows a topic to act as an example and requires a topic to act as a summary, the author is prompted to create topics in those roles, and the roles can be used in processing, for instance, to add a lead-in word to the emitted topic titles.

<!ELEMENT exampleref  ((%topicmeta;)?, (%exampleref;)*)>
<!ATTLIST exampleref
  ...>
<!ELEMENT summaryref  ((%topicmeta;)?)>
<!ATTLIST summaryref
  ...>

On closer investigation, either or both of these particular roles may turn out to reflect a persistent topic structure or semantic, in which case it would be appropriate to define topic types and limit the corresponding topicref specialization to topics of those types. The general technique, however, of assigning a role to a topic in the context of a collection remains valid.

Finally, the definition module sets the class attribute to declare that the new elements derive from topicref and are provided by the howto package:

<!ATTLIST howto %global-atts;
    class CDATA "- map/topicref howto/howto ">
<!ATTLIST conceptref %global-atts;
    class CDATA "- map/topicref howto/conceptref ">
...

Assembling the shell DTD

As with topic domains, a shell DTD assembles the base map module with the entities file and definition module for the how-to domain:

<!--vocabulary declarations-->
<!ENTITY % howto-d-dec PUBLIC "-//IBM//ENTITIES DITA How To Map Domain//EN" "howto.ent">
  %howto-d-dec;
...

<!--vocabulary substitution (one for each extended base element,
    with the names of the domains in which the extension was declared)-->
<!ENTITY % topicref  "topicref | %mapgroup-d-topicref; | %howto-d-topicref;">

<!--vocabulary attributes (must be declared ahead of the default definition) -->
<!ENTITY included-domains "&mapgroup-d-att; &howto-d-att;">

<!--Embed map to get generic elements -->
<!ENTITY % map-type PUBLIC "-//IBM//Elements DITA Map//EN" "../../dtd/map.mod">
  %map-type;

<!--vocabulary definitions-->
...

<!ENTITY % howto-d-def PUBLIC "-//IBM//ELEMENTS DITA How To Map Domain//EN" "howto.mod">
  %howto-d-def;

Creating a collection with the domain

Using the shell DTD, a map could include one or more how-to collections, as in the following example:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//IBM//DTD DITA How To Map//EN"
  "howtomap.dtd">
<map>
  <!-- how-to clusters can appear anywhere in a map hierarchy but always
       follow a consistent information pattern within the how to -->
  <howto href="dita-mapdomains.xml">
    <conceptref href="informationArchitecture.xml"/>
    <conceptref href="mapBackground.xml"/>
    <conceptref href="formalCollection.xml"/>
    <conceptref href="mapSpecialization.xml"/>
    <taskref href="implementDomain.xml"/>
    <exampleref href="declareEntities.xml"/>
    <exampleref href="domainModule.xml"/>
    <exampleref href="assembleDTD.xml"/>
    <exampleref href="domainInstance.xml"/>
    <summaryref href="summary.xml"/>
  </howto>
</map>

In fact, this example is the map for the article that you're reading right now. That is, as you may well have noticed, this article conforms to the formal pattern for a how-to collection. Here's the list of topics in this how-to article but with the addition of the topic type or role and title:

howto: How to define a formal information architecture with DITA map domains
- concept: Formal information architecture
- concept: Specializing topics and maps
- concept: The how-to collection
- concept: Map specialization
- task: Implementing a map domain
- example: Declaring the map domain entities
- example: Defining the map domain module
- example: Assembling the shell DTD
- example: Creating a collection with the domain (this topic)
- summary: Summary

While this article contains only a how-to collection, a how-to collection could be part of a larger deliverable. For instance, a help system could include multiple how-tos as part of a navigation hierarchy. Similarly, how-to collections could be used in books by creating a new shell DTD that combines the bookmap map type with the how-to map domain.

As you explore collection types, you'll find that, in addition to topics, a collection can aggregate smaller collections. For instance, you could create domains for a how-to collection, a case study collection, and a reference set collection. A product information collection could then require a product summary topic and at least one of each of these subordinate collections in that order.

You'll also find that, to represent a high-level relationship with a collection, you can create a relationship to the root topic for the collection branch. As the introduction and entry point for the collection, the root topic should provide the most statement of the content of the collection. That is, you can treat the set of topics as a collective content object, using the root topic to represent the collection as a whole for navigation and cross references.

Summary

In this article, you've learned how to specialize the topicref element to mandate a specific collection of topics. For complete, single-purpose collections such as functional specifications and quick reference guides, you might package these specialized topicref elements with a new map type. For building-block collections (such as how-tos or case studies) that can appear within a large deliverable, especially when different designers might create different collection types, you might want to package the specialized topicref elements as a map domain.

By specializing a DITA map in this way, you can implement a formal information architecture not just at the micro level within topics but at the macro level across topics. By defining such large-scale collective content objects, you can provide guidance to authors and declare semantics for processors with the end result that users have consistent and complete information deliverables.

DITA Open Toolkit, version 1.8.M2

Chapter 1: Getting Started with the DITA Open Toolkit

1.1.1: Installing the full-easy-install package

1.1.2: Running the demo build

XHTML output for the sample files

1.1.3: Building your own content using the demo build

Chapter 2: DITA Open Toolkit User Guide

2.2.1: Overview of the DITA Open Toolkit

Related information:

2.2.1.1: DITA Open Toolkit Release 1.8

General Enhancements and Changes

Preprocessing

PDF

Migration from previous releases

Preprocessing

XHTML

PDF

Legacy PDF

ODT

Issues

Feature requests

Bugs

2.2.1.2: DITA 1.2 Specification Support

Related information:

2.2.1.3: Tested platforms and tools

Note

2.2.2: Installing the DITA Open Toolkit

2.2.2.1: Distribution packages

Minimal package

Standard package

Full-easy-install package

Related information:

2.2.2.2: Prerequisite software

Software required for core DITA-OT processing

Software required for specific transformations

2.2.2.3: Installing the full-easy-install package

2.2.2.4: Installing the minimal or standard package on Linux or Mac OSX

Note

2.2.2.5: Installing the minimal or standard package on Windows

2.2.3: Publishing DITA content

2.2.3.1: DITA-OT transformations

2.2.3.1.1: DITA to Docbook

2.2.3.1.2: DITA to Eclipse Content

Related information:

2.2.3.1.3: DITA to Eclipse help

Related information:

2.2.3.1.4: DITA to HTML Help (CHM)

Note

Related information:

2.2.3.1.5: DITA to legacy PDF transformation

Related information:

2.2.3.1.6: DITA to Open Document Type

Related information:

2.2.3.1.7: DITA to PDF (PDF2)

Related information:

2.2.3.1.8: DITA to Rich Text Format

2.2.3.1.9: DITA to TocJS

2.2.3.1.10: DITA to Troff

2.2.3.1.11: DITA to XHTML

Related information:

2.2.3.2: Publishing DITA content from Ant

Related information:

2.2.3.2.1: Ant

Related information:

2.2.3.2.2: Building output using Ant

Related information:

2.2.3.2.3: Creating an Ant build script

Related information:

2.2.3.3: Publishing DITA content from the command-line tool

Related information:

2.2.3.3.1: Command-line tool

Related information:

2.2.3.3.2: Building output using the command-line tool

Related information:

2.2.4: Globalizing DITA content

Related information:

2.2.4.1: Globalization support offered by the DITA-OT

2.2.4.2: Supported languages: HTML-based transformations

Supported languages: HTML- and XHTML-based transformations

Related information: