DITA OT Overview
The files in the DITA OT fall into five fundamental categories:
- Ant project files that drive the DITA OT processing. These are XML files found in the root folder (ditaot) and in the ditaot/ant folder.
- DTD and related files that describe the DITA architecture, including content models and attributes. These files are stored in the ditaot/dtd folder. If you use DITA plugins, additional DTDs might exist in the ditaot/demo/<my-plugin>/dtd or ditaot/plugins/<my-plugin>/dtd subfolders. The name <my-plugin> is a placeholder for a plugin name. (This paper describes how to create your own DITA plugin under Packacking up your overrides.)
- XSL stylesheets that transform the source XML files into deliverables. These XSL files are typically found in the ditaot/xsl folder. If you use DITA plugins, additional stylesheets might exist in the ditaot/demo/<my-plugin>/xsl or ditaot/plugins/<my-plugin>/xsl subfolders.
- Documentation and examples for the DITA OT. These include sample Ant project files in the ditaot/ant folder, documentation (in DITA and output formats) in the ditaot/doc folder, and DITA example files in the ditaot/samples folder.
- Miscellaneous support files that provide processing assistance (ditaot/css, ditaot/lib and ditaot/tools folders) or support various output formats (ditaot/resources).
Running the DITA OT
The DITA OT requires that you have the Java SDK (JDK) version 1.5 or 1.6 installed. Download the “full easy install” version of the DITA OT and uncompress the file to a folder. The path to the folder should not contain spaces, so use something like c:\ditaot rather than c:\dita ot. This paper refers to the folder ditaot, which represents the directory in which the DITA OT is installed. You might choose a different file name. This is just a reference point.
You begin running the DITA OT by running a script or batch file that creates some environment variables. In Windows, the file is ditaot/startcmd.bat; in UNIX or Linux, the file is startcmd.sh.
In addition to creating the environment variables, these scripts open a command window. From the command prompt, you enter Ant commands that run the DITA OT. The top level of the ditaot folder contains a number of Ant project files that you can use to test the DITA OT installation. However, the Ant project files that you need to modify are in the ditaot/ant folder.
The examples in this white paper use the sample files from the ditaot/samples folder. The sample Ant file ditaot/ant/sample_xhtml.xml is already set up to process ditaot/samples/hierarchy.ditamap into XHTML output, so it’s a good file to use as the basis for your modifications. Make a copy of the file ditaot/ant/sample_xhtml.xml and name it something like my_xhtml.xml to make a custom test file.
When you first open my_xhtml.xml for editing, there are several locations to note in the file.
<?xml version="1.0" encoding="UTF-8" ?>
<!-- This file is part of the DITA Open Toolkit project hosted
on
Sourceforge.net. See the accompanying license.txt file for
applicable licenses.-->
<!-- (c) Copyright IBM Corp. 2004, 2006 All Rights Reserved.
-->
... ➊ ➋
<project name="sample_xhtml" default="sample2xhtml" basedir=".">
<!-- dita.dir should point to the toolkit's root directory
-->
<property name="dita.dir" value="${basedir}${file.separator}.."/>
➌
<!-- if file is a relative file name, the file name will be
resolved
relative to the importing file -->
<import file="${dita.dir}${file.separator}integrator.xml"/>
➍
<target name="sample2xhtml" depends="integrate">
<ant antfile="${dita.dir}${file.separator}build.xml" target="init">
<!-- please refer to the toolkit's document for supported
parameters, and
specify them base on your needs -->
<property name="args.input"
value="${dita.dir}${file.separator}samples${file.separator}hierarchy.ditamap"/>
<property name="output.dir"
value="out${file.separator}samples${file.separator}xhtml"/>
<property name="transtype" value="xhtml"/>
</ant>
</target>
</project>
The callouts in the sample indicate places where you make changes to this file, as explained here:
|
➊ |
Change the project name sample_xhtml to my_xhtml, so that it matches the file name. |
|
➋ and ➍ |
It’s not essential to change the name of the default target (sample2xhtml), but if you do, make sure you change it both in the project declaration as well as in the target declaration. |
|
➌ |
Later sections in this paper describe how to add additional <property> directives. This is the best place to add them. |
Save your changes and run the Ant project from the command line that was opened by the startcmd script. The Ant command to run this modified project file is:
ant -f ant/my_xhtml.xml
You’ll get lots and lots of output. If the project created its output correctly, the next to last line should say:
BUILD SUCCESSFUL
To view the output, use a web browser to open the file ditaot/ant/out/samples/xhtml/index.html.
Some who start working with the DITA OT are surprised or disappointed to realize they’re back to the “old DOS prompt.” If you are in this group, note that the command line is just a starting point; you can build scripts or batch files that set up environment variables and run Ant projects. Additionally, several -commercial tools are available that hide the command-line interface from users, such as XMetaL Author and oXygen.
Next Page:
CSS changes