Presenter: Adena Frazer, Senior Developer, Suite Solutions Abstract: In this webinar you will learn about the DITA Open Toolkit architecture and acquire the basics of running and benefiting from the DITA-OT. This webinar will guide you in: • Leveraging your DITA content in a variety of output formats, such as PDF, XHTML, and HTML Help • Customizing your DITA content processing • Filtering your output for different audiences

1. Getting Started with the DITA Open
Toolkit
Adena Frazer, Suite Solutions

2. Who am I?
Adena Frazer
• Background in Computer Science and Education
• Early and senior member of the Suite Solutions team
• Given many public and private training seminars over the past five
years
• Extensive expertise implementing DITA and CMS solutions for a wide
variety of organizations
• Responsible for internal training and mentoring for developers at Suite
Solutions
• Help companies get it right the first time

3. About Suite Solutions
Our Vision: Enable companies to engage their customers by providing quick
access to relevant information
• Help companies get it right the first time
• XML-based Authoring/Publishing Solutions
• Enterprise Intelligent Dynamic Content: SuiteShare
• Consultancy, Systems Integration, Application Development
• Cross-Industry Expertise
• High Tech, Aerospace & Defense
• Healthcare, Discrete Manufacturing
• Blue Chip Customer Base
• Hundreds of Person Years of Experience on Staff

4. Main Topics
•
•
•
•
•
•
Overview of the DITA-OT
DITA-OT Architecture
Rendering Output with the DITA-OT
Customizing Processing using ANT
Filtering Output Using DITAVAL
DITA-OT Resources

5. Overview of the DITA-OT
DITA Open Toolkit – Open source tool that processes DITA source content
and produces output in a variety of formats.
Processing tasks include:
• Validation
• Checks that files are valid DITA
• Checks referenced files and links
• Resolves references and links
• topicrefs, conrefs, xrefs, keyrefs, conkeyrefs
• Performs conditional publishing
• Includes or excludes topics and elements based on conditional
attributes: product, audience, platform, otherprops

6. Overview of DITA-OT
•
•
Dynamically generates links
• Parent/child links
• Related links
• TOC
• Index
• Bookmarks
Renders or compiles the final output using the relevant style sheets:
• HTML Formats: XHTML, HTML Help, Eclipse Help, JavaHelp
• Docbook, ODT, RTF, TROFF
• FO to PDF
 Merges files into one document
 Calls a PDF rendering engine

7. Plug-ins
•
•
•
•
The DITA-OT uses a plug-in mechanism to allow users to add and
remove components in a modular way.
Recent releases of the DITA-OT have moved existing code to separate
plug-ins.
Plug-ins are located in the DITA-OTplugins directory.
• Includes many files that used to be located in the demo folder.
For details about how plug-ins are implemented in the DITA-OT, see
the Developing Plug-ins and Working with FO plug-in Extension Points
webinar
• Located at http://www.suite-sol.com/pages/services/
services_training_dita_ot_training_webinars_recorded.html

8. DITA-OT 1.8
•
The latest version of the DITA-OT is 1.8 (M2)
• Released on September 17, 2013
New Features Include:
• Additional validation in the preprocessing step
• Bundled FOP has been updated from version 1.0 to 1.1.
• Code cleanup and reorganization
• Removed deprecated code and ANT properties
• Updated existing code.
• Moved a number of style sheets to plug-in specific folders
• A variety of bug fixes and new features
• For more details, see DITA-OT1.8.M2relnotes.html or the DITA-OT
Release History section of the DITA-OT User Guide

9. Main Topics

•
•
•
•
•
Overview of the DITA-OT
DITA-OT Architecture
Rendering Output with the DITA-OT
Customizing Processing using ANT
Filtering Output Using DITAVAL
DITA-OT Resources

10. DITA-OT Architecture
DOST.ja
r
XML Parsing and
Validation
XSL
Transforms
Apache ANT
XSL
style sheets
XML Parser
XSLT Engines
•XERCES
•SAXON
•XALAN
•Resolver.jar
•Icu4j.jar
•Fop.jar
•Batik.jar

11. Apache ANT
•
•
•
•
•
Build management tool similar to Make files from DOS – manages
targets and dependencies
Used primarily by the Java community
Used as the control program for the DITA-OT workflow
ANT is used for common development tasks such as
• Running the Toolkit
• Creating plug-ins
• HTML customization
Located in ditaottoolsant

12. Xerces
•
•
Xerces is a collection of software libraries created by Apache
Used for parsing, validating, serializing and manipulating XML
(http://en.wikipedia.org/wiki/Xerces)
•
Located in ditaotlibxercesImpl.jar
XML Parsing and
Validation
XML Parser
•XERCES

13. DOST.jar
•
•
•
•
DOST – DITA Open Source Toolkit
Contains all of the JAVA code unique to the Toolkit as a whole
• JAVA is a more general purpose programming language than ANT
or XSLT
• Some code is written in JAVA to improve performance.
Code is compiled
• Source needs to be downloaded separately
• When the source is changed, the jar needs to be recompiled.
Located in the ditaotlib directory

14. Additional JAVA Components
•
•
Additional Java libraries that are packaged with the Toolkit include:
• Resolver.jar
 Resolves file references using catalog files
• Icu4j.jar
 International Components for Unicode for Java - used for
internationalization
• Fop.jar
 Formatting Object Processor - Apache open source application
that converts XSL Formatting Objects to PDF
• Batik.jar
 Graphics library used by FOP
Located in ditaotlib and ditaotpluginsorg.dita.pdf2fop

15. XSLT Engines
Saxon
• Saxon is an XSLT and XQuery processor created by Michael Kay.
• Saxon version 9 (and up) implements the XSLT 2.0 specifications and
can process XSLT 1.0 files as well.
• This version ships with the DITA-OT
• Located in ditaotlibsaxon
Xalan
• XSLT and XPath Processor from the Apache Software Foundation.
• It has some bugs and does not support XSLT2.
• It was initially packaged with the DITA-OT (through version 1.4.2) due
to licensing issues with Saxon.
Saxon is the recommended XSLT processor to be used with the DITA-OT.

16. DITA-OT Architecture
DOST.ja
r
XML Parsing and
Validation
XSL
Transforms
Apache ANT
XSL
style sheets
XML Parser
XSLT Engines
•XERCES
•SAXON
•XALAN
•Resolver.jar
•Icu4j.jar
•Fop.jar
•Batik.jar

17. Main Topics


•
•
•
•
Overview of the DITA-OT
DITA-OT Architecture
Rendering Output with the DITA-OT
Customizing Processing using ANT
Filtering Output Using DITAVAL
DITA-OT Resources

18. Required Parameters
•
Three main parameters are required to run the DITA-OT, regardless of
the method used:
• args.input - The path and name of the input file to publish
• transtype – The output format to be produced.
Transtypes Available by Default
docbook
javahelp
rtf
eclipsehelp
legacypdf
troff
eclipsecontent
odt
xhtml
htmlhelp
pdf
• output.dir – The path of the output directory

19. Rendering Output
•
Always open the cmd window by double clicking on ditaotstartcmd.bat
or running ditaotstartcmd.sh to make sure that the required variables
are properly set
•
Run ditaotbuild_demo.xml to easily test installation
• Type: ant –f build_demo.xml
• Follow the instructions
•
Use the command-line tool.
• Supports a subset of the ANT parameters
• Type: java -jar lib/dost.jar
/i:samples/sequence.ditamap /outdir:out
/transtype:xhtml

20. Rendering Output
•
Use a property file to send properties to build.xml.
• Sample property file:
args.input=samples/sequence.ditamap
transtype=xhtml
output.dir=out
• ANT command:
 ant -f build.xml –propertyfile mypropertyfile.txt
•
Use ANT build scripts
• Samples and templates can be found in the
ditaot/samples/ant_sample directory.
• Type: ant -f samples/ant_sample/sample_pdf.xml
• This is the recommended method for running the Toolkit.

21. Sample ANT Build File
•
Concise version of ditaotsamplesant_samplesample_pdf.xml:
<project name="sample_pdf" default="samples.pdf" basedir=".">
<property name="dita.dir" location="${basedir}/../.."/>
<target name="samples.pdf">
<ant antfile="${dita.dir}/build.xml">
<property name="args.input”
location="${dita.dir}/samples/sequence.ditamap"/>
<property name="output.dir" location="${dita.dir}/out/samples/pdf"/>
<property name="transtype" value="pdf"/>
</ant>
</target>
</project>

22. Main Topics



•
•
•
Overview of the DITA-OT
DITA-OT Architecture
Rendering Output with the DITA-OT
Customizing Processing using ANT
Filtering Output Using DITAVAL
DITA-OT Resources

23. Using ANT Parameters
•
•
•
•
•
The DITA-OT provides an extensive list of built in ANT parameters
that can be used to control the DITA-OT processing
Parameters can be relevant to
• All transtypes
• HTML based transtypes
• Specific transtypes.
For a detailed reference of available parameters, see pages 57-64
of the DITA-OT User Guide
Custom parameters can also be added to the DITA-OT processing
and passed in from ANT.
Optional parameters are passed into the DITA-OT using the same
format as the required parameters. For example:
<property name=“clean.temp" value=“no"/>

24. Using ANT Parameters
•
Selected ANT Parameters:
Name
Description
Allowed
Values
Default
Value
args.draft
Specifies whether the content of <draft-comment>
and <required-cleanup> elements is included in
the output.
yes, no
no
clean.temp
Specifies whether the DITA-OT deletes the files in
the temporary directory after it finishes a build.
yes, no
yes
validate
Specifies whether the DITA-OT validates the
content.
true,
false
true
args.rellinks
Specifies which links to include in the output.
• none – No links are included.
• all – All links are included.
• nofamily – Parent, child, next, and previous links
are not included
none, all,
nofamily
none

25. Additional Processing with ANT
•
ANT can be used for a wide variety of custom processing tasks
•
For example, the sample ANT build files that are shipped with the
Toolkit use ANT to delete old output before new output is generated:
<target name="samples.pdf" " depends="clean.samples.pdf">
<!--Call to DITA-OT goes here-->
</target>
<target name="clean.samples.pdf" >
<delete dir="${dita.dir}/out/samples/pdf"/>
</target>

26. Calling Multiple Targets
•
ANT build files can be structured to run multiple targets with one call
<target name="all" depends=“render_xhtml, render_pdf"></target>
<target name=“render_xhtml">
<!--Call to XHTML DITA-OT processing goes here -->
</target>
<target name=“render_pdf" >
<!-- Call to PDF DITA-OT processing goes here -->
</target>
•
Targets can also be nested

27. Debugging using ANT
•
•
•
ANT output can be useful for debugging
• Often useful to look for the first error – later errors can be
misleading
Can pipe output to a log file
• ant –f sample_pdf.xml>log.txt
• Especially useful for builds with a large amount of output
Information can be added to the output.
• Values of variables can be echoed to the output
• Use xsl:message to send information to the ANT output from the
XSL

28. Main Topics




•
•
Overview of the DITA-OT
DITA-OT Architecture
Rendering Output with the DITA-OT
Customizing Processing using ANT
Filtering Output Using DITAVAL
DITA-OT Resources

29. Filtering Output Using DITAVAL
•
•
•
The DITA-OT performs filtering (conditional processing) based on
conditional attributes:
• product
• audience
• platform
• otherprops
The props attribute may be specialized to create additional conditional
attributes
Use the DITAVAL XML file to set criteria
• By default, all topics and elements are included.
• DITAVAL file specifies which elements to exclude.

30. Filtering Output Using DITAVAL
•
Sample DITAVAL file (e.g. garage.ditaval):
<?xml version="1.0" encoding="UTF-8"?>
<val>
<prop att="product" val="ford" action="include"></prop>
<prop att="product" val="honda" action="exclude"></prop>
</val>
•
Pass the name of the DITAVAL file as a parameter in the ANT build file.
<property name="dita.input.valfile“ value="${dita.dir}/garage.ditaval" />

31. Filtering Output Using DITAVAL
•
•
All values of a particular attribute have to be excluded for the attribute to
disappear
• Example: <step product=“ford honda”>
If only one of the product values is excluded, the element will still
appear.
If all of the values of any one of the attributes are excluded, the element
will not appear.
• Example:
<step product=“ford” audience=“admin”>
If “admin” is excluded then the whole element is removed

32. Flagging Output Using DITAVAL
•
•
The action of a DITAVAL entry can be set to „flag‟ to distinguish that
element in the output.
The flagging style can be determined by the attributes of the prop element
in the DITAVAL file.
• Color – sets the text color
• Backcolor – sets the background color
• Style – sets the text style
<prop att="product" val="volkswagon" action="flag"
backcolor="pink" style="italics"></prop>
•
color="red"
For details, see http://ditaspec.suite-sol.com/langref/ditaval-prop.html

33. DITAVAL Utility
•
•
•
•
•
•
Developed by Suite Solutions: available for free
Displays all conditional attribute values used in any DITA files referenced
by the chosen map
Displays all topics in which a particular conditional value is used
Choose attribute values to include using checkboxes
Generate DITAVAL file based on chosen criteria
Can be downloaded from:
http://www.suite-sol.com/pages/resources/
resources_ditaval_generation_utility.html

34. Main Topics





•
Overview of the DITA-OT
DITA-OT Architecture
Rendering Output with the DITA-OT
Customizing Processing using ANT
Filtering Output Using DITAVAL
DITA-OT Resources

35. DITA-OT Resources
•
•
•
•
•
DITA-OT User Guide
• ditaotdochtmlindex.html
• ditaotdocuserguide.pdf
Source Forge
• http://sourceforge.net/projects/dita-ot
• http://dita-ot.sourceforge.net/
Dita-Users email list
• http://tech.groups.yahoo.com/group/dita-users/
DITA-XML
• http://dita.xml.org/wiki/the-dita-open-toolkit
DITA Specification
• http://ditaspec.suite-sol.com/Home_ditaspec.html

36. Main Topics






Overview of the DITA-OT
DITA-OT Architecture
Rendering Output with the DITA-OT
Customizing Processing using ANT
Filtering Output Using DITAVAL
DITA-OT Resources

37. Hmmm, this looks interesting…
For additional information, contact us:
Adena Frazer
solutions@suite-sol.com
U.S. Office
(609) 360-0650
EMEA Office
+972-2-993-8054
www.suite-sol.com
Please take a moment and follow us on LinkedIn: http://www.linkedin.com/company/527916

38. Next Steps…
UPCOMING WEBINARS IN THE DITA QUICK START SERIES:
• COMING UP NEXT: System Architecture of a Basic DITA Toolset Tuesday, October 29 2PM EDT
• Migrating to DITA: Building a Project Plan
• Migrating to DITA: Defining Your Style Sheet Requirements
• Migrating to DITA: Defining Your Conversion Requirements
• Migrating to DITA: Defining Your Translation Requirements
•
Please take a moment and follow us on LinkedIn:
http://www.linkedin.com/company/527916