DITA Open Toolkit and FrameMaker Using the DITA Open Toolkit to publish your DITA content from FrameMaker Eliot Kimber Contrext Adobe DITA World 2016
DITA Open Toolkit and FrameMaker
Using the DITA Open Toolkit to publish your DITA content from
FrameMaker
Eliot KimberContrext
Adobe DITA World 2016
Adobe DITA World 20162
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)
Adobe DITA World 20163
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
Adobe DITA World 20164
WHAT IS THE DITA OPEN TOOLKIT?
Adobe DITA World 20165
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”
Adobe DITA World 20166
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
Adobe DITA World 20167
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
Adobe DITA World 20168
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
Adobe DITA World 20169
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
Adobe DITA World 201610
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
Adobe DITA World 201611
WHY WOULD I USE THE OPEN TOOLKIT WITH FRAMEMAKER?
Adobe DITA World 201612
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
Adobe DITA World 201613
SETTING UP YOUR SYSTEM
Adobe DITA World 201614
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 Files\java
Adobe DITA World 201615
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 Files\Java\jre1.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.
Adobe DITA World 201616
JAVA_HOME Environment Variable
Adobe DITA World 201617
Step 3. Restart FrameMaker• You can verify that the variable is set using the
command line:
c:\>echo %JAVA_HOME%c:\Program Files\Java\jre1.8.0_101
• Should be ready to run the Open Toolkit
Adobe DITA World 201618
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
Adobe DITA World 201619
DITA Options Dialog• DITA -> DITA Options…
Adobe DITA World 201620
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
Adobe DITA World 201621
GENERATING OUTPUT
Adobe DITA World 201622
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
Adobe DITA World 201623
Step 2. Open Generate DITA Output Dialog
• DITA -> Generate DITA Output …
Adobe DITA World 201624
Step 3. Select An Output Type
• E.g., xhtml.• Also, check “View log file”
Adobe DITA World 201625
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
Adobe DITA World 201626
Step 5. Check The Output• Output will be in directory
“build-{docfilename}/{transtype}”under the directory containing the input file:
Adobe DITA World 201627
Generic HTML Result
Adobe DITA World 201628
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
Adobe DITA World 201629
HTML Help Transform• Generates files for use with the Windows Help
Workshop
Adobe DITA World 201630
Generic PDF
Adobe DITA World 201631
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
Adobe DITA World 201632
ADDING NEW OPEN TOOLKIT PLUGINS
Adobe DITA World 201633
Two Steps1. Install new Open Toolkit plugins to the OT
you’re using with FrameMaker2. Update the FrameMaker ditafm.ini file to
add the new transformation types
Adobe DITA World 201634
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
Adobe DITA World 201635
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
Adobe DITA World 201636
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
Adobe DITA World 201637
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 bin\dita –install command with the Zip path or URL:
c:\DITA-OT>bin\dita –install https://github.com/dita-community/org.dita-community.qa/releases/download/version-1.3/org.dita-community.qa-1.3.zip
Adobe DITA World 201638
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>bin\dita –install• Same as running the integrator.xml Ant
script
Adobe DITA World 201639
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=xhtml2=htmlhelp3=pdf24=qa
• No need to restart FrameMaker
Adobe DITA World 201640
Modified ditafm.ini File…DitaExtraParams=Count=5DitaDir=%FMHOME%\fminit\ditafm\DITA-OT1=xhtml2=htmlhelp3=pdf24=qa
Adobe DITA World 201641
WRAP UP AND RESOURCES
Adobe DITA World 201642
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
Adobe DITA World 201643
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