Adobe FRAMEMAKER Leitfaden

WHITEPAPER

Using the Open Toolkit plug-in

for FrameMaker

With the Darwin Information Typing Architecture (DITA) emerging as the de facto stan-

dard for creating topic-based content, Adobe® FrameMaker® 9 provides extensive support

for authoring DITA content. In addition, you can use the DITA Open Toolkit with

FrameMaker to obtain deliverable outputs. This document describes how to use the DITA

Open Toolkit with FrameMaker 9.

You are expected to know how to use DITA in FrameMaker. For information on installing

DITA Open Toolkit, see “Appendix 1: Installing the DITA Open Toolkit” on page 9, and

“Appendix 2: Installing the Open Toolkit plug-in for FrameMaker” on page 13.

Overview of DITA Open Toolkit

DITA Open Toolkit is a set of software tools, originally developed by IBM®, for publishing

DITA to various formats, including HTML, Microsoft HTML Help (.CHM) and Java™

Help. If your content conforms to the DITA structure, you can use the DITA Open Toolkit

to generate a wide variety of outputs.

The DITA Open Toolkit—an Open Source tool chain for multichannel publishing

DITA Open Toolkit is available for free distribution on the Organization for the Advance-

ment of Structured Information Standards (OASIS) website at http://www.oasis-open.org/

committees/tc_home.php?wg_abbrev=dita. OASIS maintains the DITA specification.

Working with the Open Toolkit plug-in for FrameMaker

The Open Toolkit plug-in for FrameMaker lets you manage publishing through the

FrameMaker user interface. The plug-in provides a DITA menu for publishing multiple

outputs through the DITA Open Toolkit, using the default options or your customized

builds.

HTML

Compiled Help

Java Help

XML conforming to

DITA Structure

DITA Open

ToolKit

XML

TABLE OF CONTENTS

1 Over view of DITA Open Toolkit

1 Working with the Open Toolkit plug-in for

FrameMaker

3 Advanced features

9 Appendix 1: Installing the DITA Open Toolkit

13 Appendix 2: Installing the Open Toolkit plug-

in for FrameMaker

14 Next steps

14 Resources

Using the Open Toolkit plug-in for FrameMaker 2

The Open Toolkit plug-in for FrameMaker

Generating output from the current file

After installation, you can run the DITA Open Toolkit processes from within FrameMaker. There

are two ways to do this, corresponding to the two options, Current File and Selected Target in the

DITA Generate Output dialog box:

The DITA Generate Output dialog box offers two forms of DITA Open Toolkit processing.

•Current File uses a pre-configured Ant script: This Ant script is the ditafm-ant.xml file that you

copied to your DITA-open toolkit folder on installation. This script generates output from a topic

that is currently open or from the map file to a sub folder of the folder containing the topic. On a

configured system, you can generate output without having to modify the Ant script. However,

you can edit the ditafm-ant.xml file to customize the processing of output. You must specify the

path where you installed the DITA Open Toolkit.

•Selected Target lets you specify an Ant script you’ve created. You must set up your own Ant script

and reference the script in the ditafm.ini file. The list of selected targets does not appear until you

define them in the Ant script and reference them in the ditafm.ini file.

• Most users may require only the Current File method starting the DITA open toolkit. Most

FrameMaker users may use the Current File method for running the DITA Open Toolkit pro-

cesses.

You can use Current File to process the map file or DITA topics that are open.

In the Selected Target method, the Ant scripts referenced in your DITA initialization file are run.

This method indicates the following:

• Files to process

• Applications and processes to run

• Destination folders and filenames

Using the Open Toolkit plug-in for FrameMaker 3

Thus, the Selected Target method is more appropriate for calling publishing processes that generate

output from source files in the locations specified in your custom Ant scripts.

Current File Method

Make the following changes in fminit\ditafm\ditafm.ini

To process a topic file that is open, change the ditafm.ini file as follows:

[BuildFile]

AntCommand=ant

AntScript=ditafm-ant.xml

Count=2

DitaDir=C:\DITA-OT1.4.2.1

1=chm

2=html

To generate output from the example Help file DITA map, using the Current File option:

1 Open a ditamap file.

2 If prompted, select the structured application DITA-Map-HTML, and click Continue.

Use the Structured Application dialog box.

3 Select the path where the DITA Open Toolkit is installed.

4 Select the Current File option.

5 Select .html.

6 Select the output folder, and click Build.

On a fully configured system, the example DITA content is saved in HTML.

HTML output

To view the HTML output, double-click the index.html file, which is located in the output folder.

Compiled Help (.chm) output

You can generate compiled Help (.CHM) easily. This process is similar to generating HTML output.

Open the .ditamap file, and choose DITA-->Generate CHM Output. A folder named CHM is cre-

ated in the output folder. The CHM folder contains the CHM file.

When you use the Current File option to generate output using the DITA Open Toolkit, you do not

need to modify any of the Ant, XSLT, or initialization files.

PDF output

The recommended way to generate a PDF for DITA files is through the Save As PDF option in

FrameMaker.

However, to generate PDFs using the DITA Open Toolkit:

1 Install a FO processor that helps in converting FO files to PDF. (Apache FOP is free.)

2 With Apache FOP installed, add fop.jar, batik.jar, avalon-framework-cvs-20020806.jar file path to

the CLASSPATH environment variable.

3 Update ditafm.ini to add an entry for PDF.

The route to generate PDFs through DITA Open Toolkit is added to the DITA Generate Output dia-

log box.

Advanced features

The publishing capabilities of Adobe FrameMaker are enhanced by the Open Toolkit plug-in for

FrameMaker. To take advantage of these features, you must have knowledge of the following:

Using the Open Toolkit plug-in for FrameMaker 4

• The settings in the DITA initialization file (ditafm.ini), which determine the Apache Ant file to be

used for different target outputs.

• Apache Ant scripts, in general, and their role in defining publishing processes that generate

output from the DITA Open Toolkit.

• The XSLT style sheets that are used to generate HTML and other forms of output with the

DITA Open Toolkit, as well as the other files that control the format of output, such as

cascading style sheets.

Using the Selected Target option

A user can customize using the selected target option. The ditafm.ini file provides users with entry

points from where they can run various Ant scripts. Also, for customizing Ant scripts, the user also

needs to have a basic understanding of these scripts.

When you use the Selected Target option, rather than starting an Ant script that is preset to process

the currently open file, you start an Ant script without parameters. The Ant script must contain

explicit instructions about the following:

• Files to process

• Folders to be used for different forms of output

• Publishing methods and processes

While the Selected Target option requires more setup than the Current File option, it offers more

fine-grained control.

About Ant scripts

Apache Ant, a Java™ application installed with the DITA Open Toolkit, is used for automating soft-

ware build processes. For example, the following types of publishing processes can be automated:

1 Transform specified XML files, such as DITA map files or associated topic files, with XSLT style

sheets, to generate XHTML output.

2 Run a subsequent process to place these files into specific folders for deployment to a website.

With Ant, such processes are completely controlled by an Ant script or XML build file, which

defines the following:

• All steps of the publishing process, including the processes or applications called, the target and

destination folders and files

• Processing sequence

Example custom Ant script

If the DITA Open Toolkit is properly installed, you should see a file named PROJECT.xml in your

DITA_OT folder, such as C:\dita-ot1.2.\PROJECT.xml. You can define any custom publishing pro-

cesses by copying, renaming, and modifying the PROJECT.xml file. In addition, you must modify

the DITA initialization file.

For example, to process DITA files located in the C:\Projects\Test folder, do the following:

1 Create a folder named C:\Projects\Test and copy all .dita and .xml files from the source folder to it.

Source refers to the location where you extracted the OpenToolkit.zip file. See Appendix 2 for

details.

2 Copy PROJECT.xml to your Open Toolkit (typically, C:\dita-ot1.4.2.1) folder and rename

PROJECT. xml to Test.xml.

3 Open Test.xml in Windows® Notepad® (Start > Programs > Accessories > Notepad). In steps 4

through 9, you will set the main properties indicated in the comments, which appear at the begin-

ning of the file.

Using the Open Toolkit plug-in for FrameMaker 5

Test.xml open in Windows Notepad

4 Set the property value for dita.dir to your Open Toolkit path (for example, C:\DITA-OT1.4.2.1).

Property name and value settings for dita.dir

5 Set the property value for project.ditamap to the name of your DITA map file, and the value for

project.dir to the path of your project folder (in this case, C:\Projects\Test). If necessary, you can

change the output folder. In the initial configuration of PROJECT.xml, the default output folder is

the sub folder, out, in the folder defined as project.dir.

Property name and value settings for project.dita

6 Set the property value for dita.extname to the extension of your referenced topic files (in this

case, .xml).

Property name and value settings for dita.extname

7 Save and close Test.xml.

At this stage, Test.xml must include all parameters required for running builds that target the

specific test folders and files. However, such Ant scripts must be referenced in the initialization file

before their targets show as options in the DITA Generate Output dialog box.

Editing the DITA initialization file

To complete the process of adding the selected targets, edit the DITA initialization file.

Note: Take a backup of the DITA initialization file before changing anything.

1 Using Windows Notepad, open ditafm.ini from the fminit\ditafm folder.

2 Add the following lines at the end of the file:

Using the Open Toolkit plug-in for FrameMaker 6

[AntBuild]

AntCommand=ant

Count=2

1=Test - CHM

2=Test - HTML

[ANT:Test - CHM]

BuildFile=C:\DITA-OT1.4.2.1\Test.xml

Target=chm

OutputDir=C:\Projects\Test\out\chm

Logfile=C:\Projects\Test\ant-buildlog-chm.txt

[ANT:Test - HTML]

BuildFile=C:\DITA-OT1.4.2.1\Test.xml

Target=html

OutputDir=C:\Projects\Test\out\html

Logfile=C:\Projects\Test\ant-buildlog-html.txt

3 Save and close ditafm.ini.

Now you can run the selected targets. Note that Test.xml is a single script that contains multiple tar-

gets, such as CHM and HTML.

To run the selected targets you have defined (formats like CHM, PDF, and so on):

4 In FrameMaker, select DITA > Generate Output.

5 Click Selected Target. The list of targets specified in the .ini file appears.

DITA Generate Output dialog box with Selected Target option selected

6 Select one of the targets and click Build.

You can review the output, which is similar to the output generated using the Current File option.

Using the Open Toolkit plug-in for FrameMaker 7

Customizing Ant

You can customize Ant scripts to automate a wide range of publishing processes.

For example, you might use an Ant script to copy files from one location to another. You can either

create a script or add a target to an existing script, as shown in the following figure:

Customizing the Text.xml Ant script

To add this target as an option in FrameMaker, you can modify the DITA initialization file to refer-

ence and define the new target, as shown in the following examples:

Modifying the ditafm.ini file

When the ditafm.ini file is updated, the new form of output is listed as a target in the DITA Gener-

ate Output dialog box.

New target available in DITA Generate Output dialog box

Using the Open Toolkit plug-in for FrameMaker 8

Customizing DITA Open Toolkit files

In addition to customizing Ant scripts, you can customize other components of the DITA Open

Toolkit publishing process. The DITA-OT contains the files you can modify. Ant processing can

include files in any location, and processes and applications not included in the DITA Open Toolkit

distribution.

Main files of the DITA Open Toolkit

You can modify some of the following files to customize the output generated using the Open Tool-

kit plug-in for FrameMaker.

• XSLT style sheets that control HTM and other forms of published output. You can change the

XSLT style sheet to customize HTML design, or you can use XSLT to generate XML in a different

structure from your core DITA structure to interface with specific systems.

• CSS style sheets that are used in HTML output

•Antscripts

• Any other tools used in new targets

This customization must be separated from the core toolkit processing. For example, you can cus-

tomize the XSLT that generates XHTML to accommodate a specialized structure by doing the fol-

lowing:

1 In the xsl sub folder in your DITA Open Toolkit folder, rename dita2xhtml.xsl to

dita2xhtml_original.xsl.

2 Create a file named dita2xhtml.xsl that imports both the renamed .xsl file, and a second .xsl file

where you add your custom processing:

<xsl:stylesheet version="1.0"

xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:import href="dita2xhtml_original.xsl"/>

<xsl:import href="/path/to/custom2xhtml.xsl"/>

</xsl:stylesheet>

3 Create the XSLT for custom processing, and save it in a folder outside the DITA Open Toolkit

folder. By doing this, you can manage Open Toolkit updates, without losing any customization.

You must install a new version of the Open Toolkit and then do steps 1 and 2 above.

Using the Open Toolkit plug-in for FrameMaker 9

Appendix 1: Installing the DITA Open Toolkit

The DITA Open Toolkit includes the basic document type definitions (DTDs) associated with DITA,

as well as some XSLT style sheets for processing DITA into various output formats. The toolkit

depends on several freely available software applications, such as the following:

• The Java Development Kit, required for core processing of published output

• Apache Ant, required to define different forms of output, including location of source and

destination files

• JavaHelp, used when you are publishing your content as Help for Java applications

• SAXON, an XSLT processor used for HTML publishing

• Microsoft® HTML Help, used to generate compiled HTML Help (.chm) files

• XML-Resolver - xml-resolver-1.2.jar file required for DITA-OT1.4.2.1. (Located in the path con-

taining openToolkit.dll)

A complete installation includes installing these applications and Open Toolkit, then setting the

Environment Variables on the computer on which you’ve installed these so that the various applica-

tions can work together. To run the DITA Open Toolkit from FrameMaker, you will also need to

install the Open Toolkit plug-in for FrameMaker. For information on downloading and installing

the plug-in, see “Appendix 2: Installing the Open Toolkit plug-in for FrameMaker” on page 13.

Installing the Java Development Kit

At the core of the DITA Open Toolkit is the Java Development Kit (JDK), which provides the base

Java functionality on which most other toolkit programs depend. To install the JDK:

1Gotohttp://java.sun.com/javase/downloads/index.jsp.

2 Click the Download J2SE SDK link to download the JDK. Check for JDK 6 Update 3.

3 Accept the license agreement, and click Windows Offline Installation.

4 Click Save to save the file to your hard disk; note where you saved the file.

5 Open Windows Explorer again by right-clicking the Windows Start menu and choosing Explore

from the pop-up menu. Navigate to the folder where you saved the file, and double-click the

executable file.

6 Click Run and accept the default installation options.

7 Open Windows Explorer again. Look in the root folder to see where the JDK was installed, for

example, C:\Program Files\Java\jdk1.6.0_10 (the precise name depends on the version of the JDK

you installed).

Installing Apache Ant

Apache Ant is a build tool used by the DITA Open Toolkit for defining different processing steps

for generating published output. To install Apache Ant:

1Gotohttp://ant.apache.org/bindownload.cgi.

2 Click the .zip archive link to download the current version of Apache Ant (for example,

apache-ant-1.7.1-bin.zip [PGP] [SHA1] [MD5]).

3 Click Save to save the archive file to your hard disk; note where you saved the file.

4 Open Windows Explorer by right-clicking the Windows Start menu and choosing Explore from

the pop-up menu. Navigate to the folder where you saved the archive file.

5 Extract the contents of the archive file to the C:\ folder.

Using the Open Toolkit plug-in for FrameMaker 10

Installing JavaHelp

JavaHelp creates Help for use in Java-based applications. To install JavaHelp:

1Gotohttp://java.sun.com/products/javahelp/download_binary.html.

2 Download the latest version of JavaHelp (for example, JavaHelp 2.0_02 [Zip]), accepting the

license agreements.

3 Click Save to save the archive file to your hard disk; note where you saved the file.

4 Open Windows Explorer by right-clicking the Windows Start menu and choosing Explore from

the pop-up menu. Navigate to the folder where you saved the archive file.

5 Extract the contents of the archive file to the C:\ folder.

Installing the SAXON XSLT Processor

The SAXON XSLT Processor is an Open Source XSLT processor built by Michael Kay, used to

transform source XML conforming to the DITA architecture to HTML. To install the SAXON

XSLT Processor:

1Gotohttp://saxon.sourceforge.net/.

2 Click the download link under the heading Saxon 6.5.5.

3 Click one of the download options on the SourceForge.net page.

4 Click Save to save the archive file to your hard disk; note where you saved the file.

5 Open Windows Explorer by right-clicking the Windows Start menu and choosing Explore from

the pop-up menu. Create a folder within the root folder called Saxon (for example, C:\Saxon).

6 In Windows Explorer, navigate to the folder where you saved the archive file.

7 Extract the contents of the archive file to the C:\Saxon folder that you created.

Installing Microsoft HTML Help

Microsoft HTML Help is a tool for authoring online Help, which is used by the Open Toolkit to

create compiled Help (.chm) files. To install Microsoft HTML Help:

1Gotohttp://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/

html/hwMicrosoftHTMLHelpDownloads.asp (make sure this is a single line).

2 Click Download Htmlhelp.exe and click Save to save the executable file to your hard disk; note

where you saved the file.

3 Open Windows Explorer by right-clicking on the Windows Start menu, and choosing Explore

from the pop-up menu. Double-click the Htmlhelp.exe file and follow the steps in the HTML

Help installation wizard to complete the installation.

Installing the DITA Open Toolkit

The DITA Open Toolkit itself provides files that control the dependent applications, such as the

JDK, Ant, and SAXON, to generate published output. To install the DITA Open Toolkit:

1Gotohttp://dita-ot.sourceforge.net/.

2 Click Download in the left pane, and click Download DITA Open Toolkit.

3 Select and download the most recent DITA Open Toolkit .zip archive (for example,

DITA-OT1.4.2.1_full_easy_install_bin.zip), selecting a mirror site for your download.

4 Click Save to save the archive file to your hard disk; note where you saved the file.

5 Open Windows Explorer by right-clicking the Windows Start menu and choosing Explore from

the pop-up menu. Navigate to the folder where you saved the archive file.

6 Extract the contents of the archive file to the C:\ folder.

Technical skill required

Note that installing the DITA Open Toolkit requires con-

siderable expertise, and may not be appropriate for

those without at least some programming background.

Time allocation

This process can be time-consuming, as you will be

installing multiple Open Source applications that sup-

port the toolkit, as well as the toolkit itself. Allocate sev-

eral hours for installation and testing.

Dieses Handbuch passt für folgende Modelle

Inhaltsverzeichnis

Andere Adobe Software Handbücher

Adobe

Adobe 25520388 - Premiere Pro - PC Bedienungsanleitung

Adobe

Adobe 65022870 - Creative Suite 4 Production... Bedienungsanleitung

Adobe

Adobe 65030089 - Robohelp - PC Bedienungsanleitung

Adobe

Adobe ACROBAT READER 4.0 - 2 Bedienungsanleitung

Adobe

Adobe 65016169 - Photoshop CS4 Extended Betriebsanleitung

Adobe

Adobe DEVICE CENTRAL CS4 - READ ME Bedienungsanleitung

Adobe

Adobe PHOTOSHOP 5.0 Bedienungsanleitung

Adobe

Adobe 22020738 Kurzanleitung

Adobe

Adobe AFTER EFFECTS 7.0 Bedienungsanleitung

Adobe

Adobe 37980039 - FrameMaker Server - Unix Bedienungsanleitung

Adobe

Adobe ACROBAT 3D Bedienungsanleitung

Adobe

Adobe ACROBAT 9 HOW-TOS Bedienungsanleitung

Adobe

Adobe 65029902 - Robohelp Server - PC Bedienungsanleitung

Adobe

Adobe PRESENTER 7 Montage- und Bedienungsanleitung

Adobe

Adobe 38039336 - Flash CS3 Professional Referenzhandbuch

Adobe

Adobe TYPE MANAGER DELUXE 4.1 Bedienungsanleitung

Adobe

Adobe 18030211 - Creative Suite 2 Standard Bedienungsanleitung

Adobe

Adobe CONFIGURATOR 1 Bedienungsanleitung

Adobe

Adobe 38040165 - Visual Communicator - PC Bedienungsanleitung

Adobe

Adobe 65007312 - Photoshop Lightroom Handbuch

Adobe

Adobe DEVICE CENTRAL CS4 - READ ME Leitfaden

Adobe

Adobe 26001360 - Illustrator CS - PC Bedienungsanleitung

Adobe

Adobe 65030083 - Technical Communication Suite Bedienungsanleitung

Adobe

Adobe 29180155 - Photoshop Elements 4.0 Bedienungsanleitung

Beliebte Software Handbücher anderer Marken

COMPRO

COMPRO COMPROFM Bedienungsanleitung

Muratec

Muratec OFFICEBRIDGE ONLINE Bedienungsanleitung

Oracle

Oracle Contact Center Anywhere 8.1 Bedienungsanleitung

Avaya

Avaya NULL One-X for RIM Blackberry Bedienungsanleitung

HP ProLiant BL420c Bedienungsanleitung

PS Audio

PS Audio PowerPlay Betriebsanleitung

Brady

Brady LOCKOUT PRO 3.0 Service-Handbuch

Avaya

Avaya Interaction Center Bedienungsanleitung

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Handbuch

Novell

Novell GROUPWISE 8 - INTERNET AGENT Bedienungsanleitung

Oracle

Oracle Application 9i Bedienungsanleitung

Acer

Acer RDM Bedienungsanleitung

Canon

Canon Vixia HF21 Bedienungsanleitung

Canon

Canon ZR950 Bedienungsanleitung

Samsung

Samsung Auto Backup Bedienungsanleitung

Polycom

Polycom Vortex EF2201 Montage- und Bedienungsanleitung

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c Bedienungsanleitung

Novell

Novell SP2 - S Bedienungsanleitung