framemaker and the dita open toolkit

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