I found this DITA Tip-Where to Put Your Files the other day and it’s a nice explanation of not only how to set up the file storage for DITA topics but also an explanation of why it’s convenient and what are the advantages to this set up. I think that the hows for DITA are readily available but the whys are a little bit behind. Everyone working on DITA knows about this general lack, though, and I think the gap is being closed. I actually think bloggers can close this gap somewhat. Take a look at the DITA category for martin’s blog for an example of where he discusses real-world tips for DITA.
Environment setup
I also followed the environment variable setup found in the Open Toolkit documentation (if you install the toolkit, the Windows instructions are in DITA-OT1.2.2/doc/installguide/settingenvironmentvariables.html) and found it really valuable. It doesn’t always say why you might use Xalan, or ANT_OPS, for example, so I’m not sure whether to bother setting those up if I don’t know the intended use. I guess I can’t expect too much from what is essentially a reference topic, and not a conceptual one. But, here is what I have gathered from reading the surrounding documentation:
- Setting CLASSPATH for c:\ditaot\lib\dost.jar is optional but useful if you want to get logging information or debugging information. I believe that file was added in the DITA Open Toolkit 1.2 release timeframe. I went ahead and set it.
- If you’ll use Saxon for XSLT processing, set up an ANT_OPTS variable containing -Djavax.xml.transform.TransformerFactory=com.icl.saxon.TransformerFactoryImpl.
- Some settings conflict with others, so if you use Saxon for XSLT processing, remove all references to Xalan jars (another XSLT processor)from your classpath.
Which platforms work – plus the interdependencies
The DITA Open Toolkit 1.2.2 is tested on Java 1.4.2, Ant 1.6.5, FOP 0.20.5, and Saxon 6.5.3 releases. It ought to work with Java 1.5 but testing has shown that Java 1.5 works with Saxon but not Xalan. The whole toolkit won’t work yet with Saxon 8.x which supports XSLT 2.0. It also works with Xalan-J 2.6 but if you have Saxon jar files in your CLASSPATH, remove the Saxon jars before adding the relevant Xalan jars. In addition, to use Xalan, you’d have to ensure you’re using Java 1.4. (Yahoo dita-users group message reference) Whew! So many dependencies.
Set this, set that
One thing I’ve noticed on the dita-user group is that people will respond with, oh you need to set your this or that, but don’t always say where to set it. I found that often times people are referring to settings in the build.xml file that are properties that are defined in the doc/DITA-antscript.html file that comes with the Open Toolkit. For example, if all your topid files are .dita instead of .xml, this is the place you’d need to change to .dita in your build.xml file:
<property name=”dita.extname” value=”.xml“/>
Another observation is that oddly enough, in this case online install documentation has a huge advantage over printed because I can copy and paste URLs for downloading and environment variables to ensure accuracy. I had a tough time accurately typing \lib\avalon-framework-cvs-20020806.jar when glancing down at an open book. Plus, when I look at a printed book, I have to wonder if it’s really up-to-date, especially when versions and URLs are involved.
Troubleshooting
One great thing about this latest release of the Open Toolkit is a troubleshooting topic has been added to the help. So far there are only three common problems, and I’m having trouble with the third — Failed to load message file. However, so far, the suggested fix hasn’t worked. Still digging. I’ll keep you posted on my progress, though, in hopes of bridging that gap.