This is the third installment in A DITA Adventure. The first two installments covered downloading and installing the DITA Open Toolkit and installing the DITA Open Toolkit on Linux. This installment is my first attempt to build content outside the demo package, and it has been a less than happy experience.
I started out by reading the documentation in ditaot/doc/index.html, where ditaot is the directory where you installed the DITA Open Toolkit (that installation is described in the first installment). The description is in the section titled: Building DITA output with Ant.
Right off the bat, I’m in a little trouble. The documentation does not match the files. The docs say there are four files to work with: conductor.xml, pretargets.xml, ditatargets.xml and catalog-dita.xml. Turns out that the first three have been combined into a standard ant build.xml file, which is not documented.
Getting frustrated with the inconsistencies, I did a Google search and found DITA Open Toolkit User Guide (Release 1.3.1), which is significantly newer than the docs shipped with the toolkit. This was better, and I was able to build small projects and the html version of the DITA 1.1 Reference, but I hit the wall with pdf. BTW, this is not the fault of the User’s Guide, which does a good job of describing 1.3.1.
Rather than take you through every step of my misadventures with 1.4.3, I will skip ahead. I decided to start over with DITA-OT 1.5, which is available in the same place as 1.4.3 (it is the version now shown in the green box on the Source Forge DITA-OT page). The latest documentation still seems to be at dita-ot.sourceforge.net, though I also got some useful help from Jennifer Linton and Kyleen Bruski’s Introduction to DITA.
The key to getting going was to copy sample ant scripts from the directory ditaot/samples/ant_sample. You can then edit the sample files (I used sample_xhtml.xml and sample_pdf.xml) and set dita.dir to point to ditaot (same as above), args.input to point to your ditamap, and output.dir to point to your output directory.
After that, xhtml worked fine, but pdf was still a problem. Trying to convert the 500+ page DITA language reference to pdf works ok until the process hits the fo to pdf stage (for newbies, the typical XML to PDF process for DITA and DocBook is a two step process that first generates a dialect of XML called FO, for formatting objects, then transforms the FO into PDF). At that point, the processor the toolkit uses (FOP) generates pages of errors and then fails with an out of memory error. Good news is that the process leaves a .fo file, which the XEP fo processor (a commercial product) converts to pdf with no problem. So far, though, I haven’t that integrated into the ant scripts.
Overall assessment so far; the Open Toolkit is still really only for people who are fully comfortable with ant, command line processing, and creative problem-solving. If you are a neophyte, you may want to look into something easier to use, for example, the oXygen XML editor, which has the DITA Open Toolkit built in. I will continue to plow along using the toolkit as is, but only because I’m a stubborn guy.
I’ll try to get pdf fully working in the next installment.
