Monday, March 22, 2010

Quick and rude guide to DITA OT installation

The install guide that comes with the DITA OT package is good (really, no sarcasm) but it sometimes assumes I am more of a techie than I really am. Last week, I changed my computer. It was while setting up my DITA environment that I remembered again that if I just follow these instructions to the T (see picture), I am more than likely to stumble.
So, I am writing up this blog post as a note to (i) myself, should I need to do this all over again (ii) everyone of you who wants to set up a DITA environment with minimal fuss. (<aside>I know; "minimal" is subjective.</aside>)

I use a Windows machine; these instructions are for a Windows setup (64-bit).
  1. Download JDK. The latest version is JDK 6 Update 18 and can be downloaded from http://java.sun.com/javase/downloads/index.jsp. The file I downloaded is called jdk-6u18-windows-i586.exe.
  2. Install JDK to a directory of your choice. To do so, double-click the jdk-6u18-windows-i586.exe file and follow the onscreen instructions. Stick to the default options. For the remaining part of this procedure, let's assume the JDK installation directory is C:\Program Files (x86)\Java\jdk1.6.0_18.
  3. Download HTML Help Workshop. The file is called htmlhelp.exe and can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en.
  4. Install HTML Help Workshop. To do so, double-click the htmlhelp.exe file and follow the onscreen instructions. Stick to the default options.
  5. Download the full DITA OT package. The latest stable version is 1.5 and can be downloaded from http://sourceforge.net/projects/dita-ot. The file I downloaded is called DITA-OT1.5.1_full_easy_install_bin.zip.
  6. Extract the contents of the DITA OT package to any directory of your choice. For the remaining part of this proceudre, let's assume this directory to be C:\Work_Area\DITA.
  7. In the C:\Work_Area\DITA directory, look for a file called startcmd.bat, and double-click it.
  8. In the command line window that opens, set the JAVA_HOME environment variable by running the following command: set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.6.0_18
  9. In the same command line window, test your DITA OT installation by running the following command (which is an ANT command for transforming DITA files): ant samples.web -f build_demo.xml Wait for the command to get over.
  10. Return to Windows Explorer and, in the C:\Work_Area\DITA directory, look for a folder called out. This folder was created as a result of the previous step and contains the transformed files. If you cannot find this folder, something went wrong with the installation :-(
Notes for subsequent transforms: Set the Java environment variables every time you run an ANT build, and do it from the directory where the ANT build is being run.

Related posts
Now that DITA OT is installed, you might want to get yourself an authoring tool? See this blogpost: DITA authoring tool.
Next, you might want to run your transforms, no, not through the command line, but through a GUI? My next blog post is about such a transform tool: DITA tools - 3 (Publishing).

Post script
The procedure I wrote contains several inline links, and references to specific software versions and local directories. As any writer knows, these are maintenance headaches. Whether docs can (or, should) really have such specific info, and, if yes, how to include such info with minimal maintenance overheads is explored in this blog post: Writing in DITA - Tip #3.

8 comments:

Gallagher said...

This makes so much more sense! I wish there was something like this for people using Mac too!

Anindita said...

:) Thank you.
I am hoping someone with a Mac reads this and responds.

Sandy said...

These instructions made it so much easier. Thank you!!!

Alan-A said...

One small point - isn't the directory you specify in step 8 specific to computers that a 64-bit operating system?
(The comparable directory on my XP 32-bit machine is: C:\Programme\Java\jdk1.6.0_23 - ok, I've got a German version and my JDK is newer than yours was as you posted but it was the 'x86' that threw me for a minute or so).

Much more important, however, is to say thanks for providing a half-way up to date set of installation instructions for the OT package - those instructions available on dita.xml.org and source forge are so out of date I found it difficult to trust them.

Good luck with your book!

Anindita said...

Thank you, Alan, for your wishes.

You're right, these instructions are for a 64-bit machine. I spent several frustrating hours trying to get my OT install right so I thought maybe putting them out in a blog would help somebody :)

Anindita said...

I'll edit this post to include that missing info (Windows 64-bit)

Alan-A said...

Hallo again,
in between times I've read your 'Post script' to your article and take back my comment about your links.
Thanks for your comments above, too - it's nice to know you follow up what you write.
And you're right when you wrote "... maybe putting them out in a blog would help somebody ..."!
I'll get in touch if I manage to crack some other questions such as why you need to "Set the Java environment variables every time you run an ANT build ....".
Best wishes,
A.

Anne said...

This post is a lifesaver! Thank you :)