FrameMaker and the DITA Open Toolkit

DITA Open Toolkit and FrameMaker
Using the DITA Open Toolkit to
publish your DITA content from
FrameMaker
Eliot Kimber
Contrext
Adobe DITA World 2016

About the Author
• Independent consultant focusing on DITA analysis,
design, and implementation
• Doing SGML and XML for cough 30 years cough
• Founding member of the DITA Technical Committee
• Founding member of the XML Working Group
• Co-editor of HyTime standard (ISO/IEC 10744)
• Primary developer and founder of the DITA for
Publishers project (dita4publishers.org)
• Author of DITA for Practitioners, Vol 1 (XML Press)

Agenda
• What is the DITA Open Toolkit?
• Why would you use it with FrameMaker?
• Setting up your system
• Generating output from FrameMaker using
the Open Toolkit
• Adding new Open Toolkit plugins
• Wrap up

WHAT IS THE DITA OPEN
TOOLKIT?

The DITA Open Toolkit Is…
• A general Java-based framework for processing
DITA content into a variety of formats:
– HTML, PDF, EPUB, online help, etc.
• An open-source project developed and
maintained by volunteers
• Widely integrated by DITA-aware tools
– Including by FrameMaker 15
• Widely used by the DITA community
– “Everyone uses the Open Toolkit”

The DITA Open Toolkit is NOT…
• Not a “reference implementation” of DITA
– It tries to reflect the standard as well as it can
– But it is not a formal reference implementation
• Not affiliated with OASIS Open or the DITA
Technical Committee

DITA OT Architecture
• Java, Ant, and XSLT-based framework
– Cross platform
– Relatively easy to extend or customize using XSLT
• Provides “transformation types” that produce different
types of output
• Extension is through plugins
– Extend or customize existing transformation types
– Add new transformation types
– Extend or customize preprocessing
• OT does DITA preprocessing “heavy lifting” for you

Transformation Types
• Built in as of OT 2.1:
– HTML, PDF, Eclipse help, Windows help, HTML help,
Java help, troff, Word RTF, DocBook
• Additional transformation types from other
sources:
– EPUB, full HTML5, InDesign: DITA for Publishers
– Quality Assurance report: DITA Community
– Web help: oXygenXML (Syncro Soft), Suite Solutions
• Anyone can add new transformation types

DITA OT Also Manages DTDs
• The Open Toolkit can also manage DITA DTDs
• Maintains a master entity resolution catalog
• Use plugins to add custom document type shells
and specializations
• Makes the DTDs available to any tool that uses
catalogs
• Simplifies DTD management
• Useful even if you never generate output with the
Open Toolkit

DITA OT Versions
• Version 1.8.5:
– Last of the 1.x versions
– Supports DITA 1.2
– Very stable, lots of plugins (e.g., DITA for Publishers)
– Not actively supported by OT team
• Version 2.x:
– Supports DITA 1.3
– Significant re-architecture from 1.x
– Easier to install and use than 1.x

WHY WOULD I USE THE OPEN
TOOLKIT WITH FRAMEMAKER?

Why Use the OT?
• Use the same processing as non-FrameMaker
authors
• Automate document processing outside of
FrameMaker
• Generate outputs not provided for by
FrameMaker
– E.g., quality assurance report, Eclipse help, etc.
• Manage your local document type shells and
specializations

SETTING UP YOUR SYSTEM

Step 1. Install Java
• DITA Open Toolkit requires Java
• Must install it if it’s not already installed
• Go to java.oracle.com and install latest Java
for Windows
– Java SE is fine.
– JDK is best but just JRE is OK too
• You may already have it installed
– Look in c:Program Filesjava

Step 2. Set JAVA_HOME
Environment Variable
• FrameMaker requires that JAVA_HOME be set
• Not set by Java installer
• Find where Java is installed:
– E.g., C:Program FilesJavajre1.8.0_111
• Get to Advanced Settings, e.g.:
– Right click on “This PC” -> Properties -> Advanced
System Settings -> Change settings -> Advanced ->
Environment Variables
– Create new system variable “JAVA_HOME” using the
Java installation directory as the value.

JAVA_HOME Environment Variable

Step 3. Restart FrameMaker
• You can verify that the variable is set using the
command line:
c:>echo %JAVA_HOME%
c:Program FilesJavajre1.8.0_101
• Should be ready to run the Open Toolkit

Step 4. Set FrameMaker DITA
Version to 1.2
• As of FM 13.0.5.547 the built-in Open Toolkit
does not include the DITA 1.3 DTDs
• Need to use DITA 1.2 files or add the 1.3 DTDs
to the built-in OT or use a different OT
installation
• To get started, easiest to set DITA version to
1.2

DITA Options Dialog
• DITA -> DITA Options…

Further Configuration
• Can add plugins to built-in Open Toolkit
• Can use a different Open Toolkit installation
• Will need read-write access to the
FrameMaker fminit/ditafm directory

GENERATING OUTPUT

Step 1. Open A DITA Map or Topic
• Most processing should be against DITA maps
• Can process individual topics but result may
not be good

Step 2. Open Generate DITA
Output Dialog
• DITA -> Generate DITA Output …

Step 3. Select An Output Type
• E.g., xhtml.
• Also, check “View log file”

Step 4. Click OK
• Will get new window until processing ends
and then will get the log.
• Processing may take some time depending on
size of document and speed of your PC

Step 5. Check The Output
• Output will be in directory
“build-{docfilename}/{transtype}”
under the directory containing the input file:

Generic HTML Result

About Generic HTML Output
• Generic styling is not very interesting
• Useful for testing and verifying your content
• XHTML transtype is base for many other
transforms:
– HTML-based help formats, HTML5, EPUB, Eclipse
InfoCenters, etc.
• Can provide your own CSS and JavaScript
• See DITA Open Toolkit site for an example of
modern-looking HTML produced from the Open
Toolkit

HTML Help Transform
• Generates files for use with the Windows Help
Workshop

Generic PDF

About Generic PDF Output
• Default styling is OK
• Uses open-source FOP XSL-FO engine out of
the box
• Can use commercial FO engines (Antenna
House Formatter or RenderX XEP)
• Most companies customize the PDF output to
reflect their styles and branding

ADDING NEW OPEN TOOLKIT
PLUGINS

Two Steps
1. Install new Open Toolkit plugins to the OT
you’re using with FrameMaker
2. Update the FrameMaker ditafm.ini file to
add the new transformation types

Step 0: Install A Local Open Toolkit
• You shouldn’t modify the OT that is built into
FrameMaker
• If you want to add plugins best to set up your
own Toolkit
• To install, simply download the version you
want and unzip it somewhere convenient, e.g.
c:dita-ot
• If you’ve already installed Java and set
JAVA_HOME then you’re all set

Using Different OT Versions
• As of November 2016 FrameMaker uses
version 2.1.0
• If you use a different version you’ll need to
modify the ditafm.ini file
– Set the ClassPath property to reflect the JAR files
used in OT version you’re installing
– Jars are in the OT lib/ directory

Step 1: Install New Plugins
(OT 2.1 and earlier)
• Get the plugin from wherever it is (e.g.,
github, another OT installation, etc.)
• Put the plugin’s directory under the OT’s
plugins/ directory
• Run the Ant command:
c:DITA-OT>ant –f integrator

Step 1: Install New Plugins
(OT 2.2 and later)
• Can install plugin Zip files directly
– From local file system
– From Web URLs (e.g., from GitHub)
• Run the bindita –install command with the
Zip path or URL:
c:DITA-OT>bindita –install
https://github.com/dita-community/org.dita-
community.qa/releases/download/version-
1.3/org.dita-community.qa-1.3.zip

Install New Plugins (2.2 and Later)
(cont)
• If you need to install multiple plugins at once…
• …unzip the plugins into the OT’s plugins/
directory
• Then run the dita –install command with no
parameters:
c:DITA-OT>bindita –install
• Same as running the integrator.xml Ant
script

Step 2: Update ditafm.ini
• Change the Count= property to reflect the new
transformation:
Count=4
• Add an entry for your new transformation type:
1=xhtml
2=htmlhelp
3=pdf2
4=qa
• No need to restart FrameMaker

Modified ditafm.ini File
…
DitaExtraParams=
Count=5
DitaDir=%FMHOME%fminitditafmDITA-OT
1=xhtml
2=htmlhelp
3=pdf2
4=qa

WRAP UP AND RESOURCES

Wrap Up
• DITA Open Toolkit is a general-purpose DITA
processing framework
• Often used for DITA publishing automation
• Can be easily used from FrameMaker
• Can use your own Open Toolkit if needed

Resources
• DITA Open Toolkit: http://dita-ot.org
• DITA Community: http://dita-community.org
• DITA For Publishers: http://dita4publishers.org
• DITA vs the DITA OT: They’re not the same thing
(Robert Anderson):
http://metadita.org/toolkit/ditaversusditaot.html
• What’s new in OT 2.0 (Robert Anderson):
http://www.slideshare.net/RobertAnderson151/ditaot-
2x-discover-whats-new-in-toolkit-two

FrameMaker and the DITA Open Toolkit

More Related Content

Similar to FrameMaker and the DITA Open Toolkit (20)

More from Contrext Solutions (20)

Recently uploaded (20)

FrameMaker and the DITA Open Toolkit