Sunday, February 21, 2010

Quick and rude guide to DITA - Part 3 of 3

In Part 2 of this series, you created some DITA files. If you are a technical writer working in an organisation that's already using DITA for authoring, you wouldn't really need to bother with transforms and outputs - there will already be a system in place with which you can do a click-and-generate-output (well, almost). You need not, therefore, really bother yourself with this part (Part 3, last of the series) unless you're really eager to see how your DITA files look in HTML. If that's the case, read on.
  1. In your root directory, create a subdirectory named Sample.
  2. In the Sample directory, create three subdirectories, and name them ant_scripts, topics, and out.
  3. In the Sample > topics directory, put your DITA files. Your DITA files must have dita as the file extension.
  4. In the Sample directory, put your ditamap file. The file extension of your ditamap file must be ditamap. If needed, edit the ditamap file to correct the filepath reference of your dita files (because now they reside one directory lower than your ditamap).
  5. Download and install the DITA Open Toolkit (
  6. Download and install the DITA sample garage files (
  7. Go to the DITA sample garage installation directory and thence to the ant_scripts subdirectory. Look for a file called garage_hierarchy_all.xml, and copy it to your Sample > ant_scripts directory. Rename the copied file to build.xml.
  8. Edit this build.xml file as follows:
    • Replace all instances of DITASAMPLE_GARAGE_OUTPUT with out.
    • Replace all instances of hierarchy.ditamap with the name of your ditamap file.

  9. Go to the DITA OT installation directory, look for a file called startcmd.bat, and double-click the file.
  10. At the DOS command prompt, run the following command: ant -f build.xml dits2xhtml
    If your build.xml file is in a different directory than the DITA OT installation directory, specify the full path of the build.xml file. Your DITA files start getting transformed to XHTML and placed in the out directory you specified in the build.xml file. Wait for the command to complete.
  11. Quit the DOS prompt, return to Windows Explorer, and go to the out directory. The index.html file is the landing page for all your DITA files.
That's it. You wrote some stuff in DITA, and created an HTML output. You're DITA ready :)

But wait! There's actually an easier option to convert your files to HTML without having to go through the 11 steps I listed. To create your transforms with just one single step, one single command at the DOS prompt, see this excellent article:



No comments: