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


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 Files\java


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.


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 Files\Java\jre1.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 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


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


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


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


Modified ditafm.ini File…DitaExtraParams=Count=5DitaDir=%FMHOME%\fminit\ditafm\DITA-OT1=xhtml2=htmlhelp3=pdf24=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

http://dita-ot.org/

http://dita-community.org/

http://dita4publishers.org/

http://metadita.org/toolkit/ditaversusditaot.html



http://www.slideshare.net/RobertAnderson151/ditaot-2x-discover-whats-new-in-toolkit-two



framemaker and the dita open toolkit

Software