Installing the FO plugin

Today I struggled with installing and successfully generating PDF output using the FO plug-in. Once again, the problem was with the documentation. I started with the following documents:

• Pages from the Lone-DITA DITA Tutorial
• The readme for the Idiom FO plug-in

When I generated PDF output, I just got the default rendering -- no spiffy appearance and the ubiquitous RenderX graphic in the footer for each page. I checked the log out put and noticed that it contained the following message:

transform.fo2pdf:

transform.fo2pdf.xep:
[java] java.lang.NoClassDefFoundError: com/renderx/xep/lib/Logger
[java] Exception in thread "main"
[java] Java Result: 1

I finally gave up and posted to the dita-user mailing list. Immediately afterwards I thought to check and see and see if XEP Personal Edition came with any documentation; it does, and the readme file told me how to start the XEP installation from a command line. Silly me -- when I had read the instructions in the plug-in readme, which states "Install XEP personal edition and license into demo/fo/lib/xep," I had thought it sufficient to simply copy the JAR and license.xml files to the specified directory.

It's just a little too complicated, I think. I've written a task topic that covers the necessary steps, but I need to test it by running the installation on another system.

The PDF output is much prettier no, 'tho :)

Installing the DITA Open Toolkit 1.4.2.1

I downloaded and installed version 1.4.2.1 of the DITA Open Toolkit today. Every version of the Toolkit has gotten easier to install, but I still experienced some pain this go-around -- all centered around the documentation:

• The user documentation page at the DITA Open Toolkit Project home pointed me to the DITA Open Toolkit User Guide, published December 2007, by Anna van Raaphorst and Dick Johnson. I prefer reading Eclipse help, so I jump to Bob Doyle's DITA infocenter and skim the section on "Installing and upgrading DITA Open Toolkit." I'm mainly interested in finding out what level of Java SDK is required. OK, according to this site, it is 1.4.2.x.
  
• Next I look at the "Installing the DITA Open Toolkit" Wiki page at dita.xml.org. It points me to the DITA Open Toolkit User Guide, Don Day's Resources page for the DITA Open Toolkit, and Lone-DITA tutorial. I get a 404 error for the Lone-DITA tutorial, but remember that one of Bob Doyle's DITA newsletters mentioned a link from which one could download a PDF of the tutorial. So I grab the PDF and print the few relevant pages, which also mention JDK 1.4.2.
• I download and unzip the DITA OT 1.4.2.1 to the root of my c drive. I find and open EvaluateOT.html, which is titled "Evaluating the DITA Open Toolkit (fullpackage version)". There's no mention of what JDK is required.

OK, so I download and install JDK 1.4.2.18, set my JAVA_HOME environment variable, and add the location of the Java executable to my CLASSPATH environment. I restart my system for good measure, run startcmd.bat, and try to run some of the samples. The build fails, with a "java.lang.UnsupportedClassVersionError: org/dita/dost/invoker/AntInvoker (Unsupported major.minor version 49.0)" message. Arggh.

I surf over the dita-users group on Yahoo! and try to search the archives, but the search mechanism is temporarily broken. When I eventually search my e-mail locally, I find a thread that lets me know that JDK 1.5.x is required. Once this JDK is installed, the samples run as they should. I know enough Ant to quickly add a few targets to the build_demo.xml and generate the CHM and PDF files that I wanted.

But ... This should not have been this difficult. And I think it would have been a show stopper for someone who didn't know to search dita-users for the answer. Or who didn't know how to check the level of Java running on a system or how to set an environment variable. Or who hadn't previously installed the DITA Open Toolkit several times.

I am a member of the new OASIS DITA Adoption Committee. At the last meeting we talked about barriers to adoption; I think that poor documentation for the Toolkit is a definite barrier :(