DITA Europe trip: Day two

I slept late (almost to 9 AM!) and then dragged myself downstairs for breakfast. Usually I love German breakfasts, but this was disappointing and not anywhere as good as the 12-euro buffet at King's Hotel Center, where I stayed in June. I'm not going to have any problem convincing myself to pass by breakfast in the hotel this trip, thankfully.

Then I went out and walked for an hour or so, getting my bearings. The hotel is about two blocks away from the Mullerishes Volksbad! I brought my swimming gear with me, so I have no excuse for not exercising while I am in Munich. Ironically, I think I walked by the Volksbad when I was here in June, and I didn't even realize it.

Despite making an extra trip up to my hotel room to retrieve my camera, I didn't take any pictures; the battery had run down. I'll either need to purchase a second battery or a charger or rely on my iPhone. I did find a large camera store on Zweibruckenstrasse on my way back from Marienplatz. (Note: I need to remember how to type umlauts.)

So, I am back in my room, drinking tea, and stalling working on my session for tomorrow.

I did listen to the tape I made on the S8, and I think the voice was saying "Bitte Entfahrt Richtung Links Aus Steigen," which might translate to "Please, the exit direction is to the left; get off." I initially misheard einfahrt for entfahrt, and auf steigen for aus steigen ... This is an object lesson in what it is like to be somewhere and not speak the primary language well, comparable to the experience of most ESL speakers confronted with technical documentation written in English.

DITA Europe trip: Day one

It's after midnight, and I am typing away in bed. The last 24 hours were spent in travel. I took the Friday 8:35 PM American flight from RDU to Heathrow, enjoyed a three-hour layover and a crayfish and rocket sandwich (arugula to us Yanks), and then grabbed a British Air flight on to Munich.

Both the new terminal 2 in RDU and terminal 5 at Heathrow are very nice, BTW. I wish I had taken some photos, but as usual, I didn't. One of my side goals for this trip to is to actually use my camera and not just drag it around.

As I took the S8 to Rosenheimer Platz, I had an insight into my new job. Before every stop, a voice announced "Next stop: ... " and then a phrase that I never quite completely caught, despite the fact that I listened carefully each time. It reminded me of my new job, where I am trying to learn a new work culture, new product family, new line of technology, and all sorts of stuff at the same time. Sometimes no matter how hard I listen the first time, I just can't get the meaning. This is especially difficult in meetings where I can't hear well or can't interrupt to ask for clarification.

Anyhow, by the time I checked into my hotel, I was quite tired. I unpacked, went out for some quick grocery shopping, and was asleep by 9 PM, albeit if only for a few hours.

Now I am going to shut down the computer, have a night cap, and hopefully get back to sleep. Ideally, I will manage to get going on Munich time tomorrow ...

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 :(