Using the DITA Open Toolkit to publish your DITA content from FrameMaker

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

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

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

4. WHAT IS THE DITA OPEN
TOOLKIT?
Adobe DITA World 20164

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

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

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

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

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

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

11. WHY WOULD I USE THE OPEN
TOOLKIT WITH FRAMEMAKER?
Adobe DITA World 201611

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

13. SETTING UP YOUR SYSTEM
Adobe DITA World 201613

14. 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
Adobe DITA World 201614

15. 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.
Adobe DITA World 201615

16. JAVA_HOME Environment Variable
Adobe DITA World 201616

17. 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
Adobe DITA World 201617

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

19. DITA Options Dialog
• DITA -> DITA Options…
Adobe DITA World 201619

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

21. GENERATING OUTPUT
Adobe DITA World 201621

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

23. Step 2. Open Generate DITA
Output Dialog
• DITA -> Generate DITA Output …
Adobe DITA World 201623

24. Step 3. Select An Output Type
• E.g., xhtml.
• Also, check “View log file”
Adobe DITA World 201624

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

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

27. Generic HTML Result
Adobe DITA World 201627

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

29. HTML Help Transform
• Generates files for use with the Windows Help
Workshop
Adobe DITA World 201629

30. Generic PDF
Adobe DITA World 201630

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

32. ADDING NEW OPEN TOOLKIT
PLUGINS
Adobe DITA World 201632

33. 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
Adobe DITA World 201633

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

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

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

37. 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
Adobe DITA World 201637

38. 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
Adobe DITA World 201638

39. 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
Adobe DITA World 201639

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

41. WRAP UP AND RESOURCES
Adobe DITA World 201641

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

43. 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
Adobe DITA World 201643