Diff for Publishing with the DITA Open Toolkit

--- Thu, 2008-05-01 13:48 by robander
+++ Wed, 2010-07-07 14:55 by robander
 <p>
 <br />
-The DITA Open Toolkit, or dita-ot for short, is a set of Java-based, open source tools that provide a &quot;reference implementation&quot; for processing DITA maps and topical content. You
+The DITA Open Toolkit, or DITA-OT for short, is a set of Java-based, open source tools that provide processing for DITA maps and topical content. You
-can download the OT and install it for free on your computer, to get started
+can download the DITA-OT and install it for free on your computer, or you may already have a copy bundled together with your authoring tool or CMS.
-with topic-based writing and publishing.
 </p>
 <p>
-The DITA Open Toolkit is a modest publishing system. The Toolkit
+The DITA-OT transforms DITA content (maps and topics) into publishing deliverable
-transforms DITA content (maps and topics) into publishing deliverable
+formats such as web (XHTML), print (PDF), and Help (CHM and Eclipse). Output files are generated in your file system, in a directory of your choosing. During the publishing process, the toolkit runs a set of &quot;pre-process&quot; routines that resolve conref, keyref, and implement several other standard DITA behaviors.
-formats such as web (XHTML), print (PDF), and Help (CHM and Eclipse). Your
-output files are simply generated in your file system. It is up to you
-to move them to your website, or into your print publishing process.
 </p>
+<p>
+If you do not have a tool that embeds the toolkit, you will need to install it first; instructions are available here: [[Installing the DITA Open Toolkit]].
+</p>
+<h2>How to publish with the toolkit</h2>
+<h3> </h3>
+<h3>Using your help authoring tool to publish <br />
+</h3>
 <p>
 The OT is integrated into many authoring tools (<em>e.g.,FrameMaker</em>, <em>&lt;oXygen/&gt;</em>, <em>XMetaL</em>) and
-content management systems (e.g., <em>Astoria, Bluestream, IXIASOFT, XyEnterprise</em>).
+content management systems (e.g., <em>Astoria, Bluestream, IXIASOFT, XyEnterprise</em>). Most of these tools provide their own menus or GUIs to interact with the toolkit. Consult your tool's documentation to find out if such tools are available.
+</p>
+<h3>Publishing with other GUI tools<br />
+</h3>
+<p>
+There are currently two external GUI tools that may be used to run a toolkit build. These tools are not maintained by the DITA-OT developers; they are created and maintained by users outside of the core development team.
+</p>
+<ul>
+	<li>&quot;DITA Open Toolkit GUI&quot; is a simple, open source Java-based GUI that allows you to select an input map, DITAVAL filter file, output directory, and transform type. The tool is hosted at SourceForge: http://sourceforge.net/projects/ditaotgui/ </li>
+	<li>WinANT Echidna is a Windows-only tool that provides access to many more toolkit options. It also allows selection of different skins, so that common sets of options or style branding may be saved or reused. This tool is not open source, but the binary is available for free at SourceForge: http://sourceforge.net/projects/winant-echidna/</li>
+</ul>
+<h3>Publishing with Ant</h3>
+<p>
+For those not using a GUI or authoring tool, the best long term approach to builds is to use Ant. An Ant build file provides you with an easily repeatable build; the time investment is entirely in the initial definition of the build file.
+</p>
+<p>
+The toolkit includes several sample Ant files in the samples/ant_sample/ directory. When creating your first Ant build, it's a good idea to copy the most appropriate build file to a new location, edit it to change the input file and base directories, and add any additional options as needed. A good current resource for available Ant parameters is the &quot;Ant Quick Start Guide&quot; (http://sourceforge.net/projects/antquickstartgu/); that information is currently being updated and should be integrated into the DITA-OT's doc/ directory sometime in July or August 2010.
+</p>
+<h3>Publishing using the Ant Demo</h3>
+<p>
+The toolkit also comes with a demo Prompted Build using Ant; this method prompts for the input file, output directory, and transform type, but does not allow access to any other options. To run the demo, run the following command from a DOS prompt in the root directory of the toolkit:
+</p>
+<p>
+ant -f build_demo.xml
 </p>
+<h3>Publishing with the Java command line</h3>
 <p>
-If you find installing the OT too difficult, consider a free running
+The final way to run a build is with the Java command line. This is simply a Java based wrapper that takes in a list of parameters, creates an Ant build file, and then runs an Ant build as described above. The primary purpose of this build method is for one-time builds or for getting to know the toolkit, because it allows access to most processing options without the need to create an Ant file. Of course this method may be used to run any number of builds, but those concerned about memory usage should know that this is no different than running an Ant build together with a small extra Java process.
-version of the DITA Open Toolkit provided as an online
-software-as-a-service by the <a rel="nofollow" href="http://www.ditausers.org/">DITA Users</a>
-organization.
 </p>
 <p>
-There you can have an online workspace folder with DITA
+To get a list of all options available to the Java command line, run the following from the root directory of the toolkit:
-docsets from IBM and Comtech Services. Edit the files and build/publish them as
-web (XHTML), print (PDF), and Help (Eclipse). All your work can be
-browsed on the web by your colleagues as a portfolio of your DITA work
-with the OT.
 </p>
 <p>
-The home page of the DITA Open Toolkit is <a href="http://dita-ot.sourceforge.net/">http://dita-ot.sourceforge.net/</a>. The DITA Open Toolkit Installation Guide, which is on that page, contains a list of supporting open-source software to download, together with a set of versions that are known to be compatible.
+java -jar lib/dost.jar
 </p>
 <p>
-The instructions on how to install and use the OT are maintained by Anna van Raaphorst and Dick Johnson as the <a rel="nofollow" href="http://dita-ot.sourceforge.net/SourceForgeFiles/doc/user_guide2.html">DITA Open Toolkit User Guide</a>. Note that there are multiple packages available for the toolkit; if you are trying it out for the first time, you probably want to get the &quot;full&quot; package (now called &quot;full easy install&quot;) that comes with other required software, and requires less manual setup.
+A full build using the shipped sample files would look something like this, which uses the /i parameter for the input file, /outdir for the output directory, and /transtype to select an output type of XHTML:
 </p>
 <p>
-Don Day maintains a <a rel="nofollow" href="http://www.ditaopentoolkit.org/">DITA Open Toolkit Resources Page</a>.
+java -jar lib/dost.jar /i:samples/hierarchy.ditamap /outdir:out /transtype:xhtml
 </p>
-<br />
+<h3>Other resources:
-<h2>See also:<br />
+</h3>
-</h2>
 <ul>
 	<li>Overview page for information about [[The DITA Open Toolkit]]</li>
-	<li><a href="/DebugTipsForPdf2">Tips for debugging PDF2 plugin PDF issues</a></li>
+	<li>Descriptions of the available [[DITA-OT Packages]]</li>
 	<li><a href="/wiki/installing-the-dita-open-toolkit">Installing the DITA Open Toolkit</a></li>
+	<li><a href="/DebugTipsForPdf2">Tips for debugging PDF issues</a></li>
 </ul>

Revision of Wed, 2010-07-07 14:55:

Publishing with the DITA Open Toolkit

The DITA Open Toolkit, or DITA-OT for short, is a set of Java-based, open source tools that provide processing for DITA maps and topical content. You can download the DITA-OT and install it for free on your computer, or you may already have a copy bundled together with your authoring tool or CMS.

The DITA-OT transforms DITA content (maps and topics) into publishing deliverable formats such as web (XHTML), print (PDF), and Help (CHM and Eclipse). Output files are generated in your file system, in a directory of your choosing. During the publishing process, the toolkit runs a set of "pre-process" routines that resolve conref, keyref, and implement several other standard DITA behaviors.

If you do not have a tool that embeds the toolkit, you will need to install it first; instructions are available here: Installing the DITA Open Toolkit.

How to publish with the toolkit

Using your help authoring tool to publish

The OT is integrated into many authoring tools (e.g.,FrameMaker, <oXygen/>, XMetaL) and content management systems (e.g., Astoria, Bluestream, IXIASOFT, XyEnterprise). Most of these tools provide their own menus or GUIs to interact with the toolkit. Consult your tool's documentation to find out if such tools are available.

Publishing with other GUI tools

There are currently two external GUI tools that may be used to run a toolkit build. These tools are not maintained by the DITA-OT developers; they are created and maintained by users outside of the core development team.

"DITA Open Toolkit GUI" is a simple, open source Java-based GUI that allows you to select an input map, DITAVAL filter file, output directory, and transform type. The tool is hosted at SourceForge: http://sourceforge.net/projects/ditaotgui/
WinANT Echidna is a Windows-only tool that provides access to many more toolkit options. It also allows selection of different skins, so that common sets of options or style branding may be saved or reused. This tool is not open source, but the binary is available for free at SourceForge: http://sourceforge.net/projects/winant-echidna/

Publishing with Ant

For those not using a GUI or authoring tool, the best long term approach to builds is to use Ant. An Ant build file provides you with an easily repeatable build; the time investment is entirely in the initial definition of the build file.

The toolkit includes several sample Ant files in the samples/ant_sample/ directory. When creating your first Ant build, it's a good idea to copy the most appropriate build file to a new location, edit it to change the input file and base directories, and add any additional options as needed. A good current resource for available Ant parameters is the "Ant Quick Start Guide" (http://sourceforge.net/projects/antquickstartgu/); that information is currently being updated and should be integrated into the DITA-OT's doc/ directory sometime in July or August 2010.

Publishing using the Ant Demo

The toolkit also comes with a demo Prompted Build using Ant; this method prompts for the input file, output directory, and transform type, but does not allow access to any other options. To run the demo, run the following command from a DOS prompt in the root directory of the toolkit:

ant -f build_demo.xml

Publishing with the Java command line

The final way to run a build is with the Java command line. This is simply a Java based wrapper that takes in a list of parameters, creates an Ant build file, and then runs an Ant build as described above. The primary purpose of this build method is for one-time builds or for getting to know the toolkit, because it allows access to most processing options without the need to create an Ant file. Of course this method may be used to run any number of builds, but those concerned about memory usage should know that this is no different than running an Ant build together with a small extra Java process.

To get a list of all options available to the Java command line, run the following from the root directory of the toolkit:

java -jar lib/dost.jar

A full build using the shipped sample files would look something like this, which uses the /i parameter for the input file, /outdir for the output directory, and /transtype to select an output type of XHTML:

java -jar lib/dost.jar /i:samples/hierarchy.ditamap /outdir:out /transtype:xhtml

Other resources:

Overview page for information about The DITA Open Toolkit
Descriptions of the available DITA-OT Packages
Installing the DITA Open Toolkit
Tips for debugging PDF issues