A DITA Adventure: A Linux Diversion

Part Two in the continuing saga of installing and using the DITA Open Toolkit. Part One (check it out first if you haven’t, yet) followed the initial download and installation of the DITA Open Toolkit, version 1.4. With a few minor caveats, that worked just fine, so I decided to try the same thing on Linux, since that’s my main system. If all goes well, I will work with the Windows and Linux installs in parallel. I am running Ubuntu 8.10 (Intrepid Ibex) and the Java 1.6 runtime.

I started with the package I used for Windows (DITA-OT1.4.3_full_easy_install_bin.tar.gz), and unzipped it into a directory I’ll call “ditaot.” For Linux, instead of startcmd.bat, there’s startcmd.sh, which failed. startcmd.sh has Windows line endings, which bash didn’t like. Using dos2ux, I converted the line endings, but also had to set the DITA_HOME environment variable to the ditaot directory before the script worked correctly. I also edited the startcmd.sh command to used the bash shell instead of the default shell, but that’s probably not essential.

After that, the test command ant samples.web -f build_demo.xml worked fine.

I found it curious that the test build generates more usable html than the included documentation. The test sample puts a table of contents on the left hand side of the screen and the contents of the selected page on the right; simple, but usable. The documentation puts the contents in one window, then opens a new window (or tab) for pages. There is no navigation on those pages, you need to go back to the contents tab to navigate; clumsier.

Next, I ran a longer demo, ant all -f build_demo.xml, which runs a bunch of tests, generating html help, java help, html, and pdf. That worked ok, though I didn’t verify the html help and java help examples. Finally, I ran a DITA to DocBook test (ant docbook -f build_demo.xml). This generated valid looking DocBook, but seemed to be missing some pieces. That needs more investigation.

Overall, again I was impressed that the basics worked well. There were a few more glitches in the Linux setup (mostly due to the startcmd.sh file), but I was pleased that all the pieces fit together and ran without clobbering my existing setup (on Linux I have an extensive environment for processing XML, and I was concerned that the toolkit would try to re-install or even clobber existing tools).

To be continued

1 comment to A DITA Adventure: A Linux Diversion

  • Rachel

    I’m a technical writer looking for a new doc system. I was surprised at how ‘dubious’ the DITA OT documentation was, especially considering the Linux setup.

    They should hire a new technical writer.