DITA tools - 3 (Transforming)

To transform dita files to a publishable output, such as XHTML or PDF, we need to run ANT builds, and we do it through the DOS command line. Another option is to use a GUI. I find the WinAntEchidna GUI, developed by HyperText, to be very handy.

The first time that you use WinAntEchidna, it asks you for the installation directory of the DITA OT (this, like all parameters, can be changed any time). Thereafter, every time you run WinAntEchidna, all you need to do is specify your ditamap file, your output folder, and your output type.

WinAntEchidna can be downloaded from http://sourceforge.net/projects/winant-echidna/.

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.

Writing in DITA - Tip #1 alternate solution

The problem statement is this: Cannot put link text inside <xref>.

An alternate solution is here:

Cartoon created with http://www.makebeliefscomix.com.

Writing in DITA - Tip #2

You are writing a procedure. You are, therefore, using <steps> for your list of actions that your reader needs to follow to complete the task. You have in mind something like this:

Because DITA tags are semantic, you want to enclose db2iauto -on <instance name> within a <codeblock> tag. But you hit a roadblock. You cannot include a <codeblock> tag within a <step> tag, says the DITA language specification.

What do you do now?
Insert an <info> tag after the mandatory <cmd> tag in the <step> tag. Then, insert <codeblock> within the <info> tag.
The <info> tag is pretty useful - it can contain paragraphs, lists, notes, images, ...

 

 

Writing in DITA - Tip #1

Problem statement

Theoretically, the <xref> tag can contain plain text. It must therefore be possible to write something like:

<xref format="html" href="http://publib.boulder.ibm.com/infocenter/c8bi/v8r4m0/topic/com.ibm.swg.im.cognos.ug_fm.8.4.0.doc/ug_fm_id21834Troubleshooting.html#Troubleshooting" scope="external">Troubleshooting guide</xref>

The authoring tool we use at work (Arbortext Editor) very decidedly does not think so.

So, the resulting output looks, er, ugly.

Workaround

Step 1: Insert a <desc> tag inside the <xref> tag, type something within the <desc> tag (it shows up as hovertext in transformed output), and then type something just outside the <desc> tag but still within the <xref> tag. Like this:

Step 2 (optional): Delete the <desc> tag.
Step result

Musings

I am fairly sure the problem is not a DITA bug but an Arbortext Editor bug. Anyone seen anything similar?

Post script,2 days after original post

See an alternate solution here.

Another post script, 20 days after the original post

The Arbortext people found this blog post and offered to help but by that time I had already found a solution. I am impressed by their follow-up - they are really trying to keep track of user pain points and minimising the attendant frustration. Thank you Arbortext (and Liz Fraley).
I'm still not sure, though, if it's not an Arbortext bug. The error message box is captioned "Arbortext..." and it has a bug number. The problem was I couldn't find a list of error messages (and possible resolutions) in the Arbortext help. Per my understanding, the problem seems to be - text selected within an xref tag cannot be overwritten; it can be removed only if it is not selected AND some other text is typed in AND the "generate referenced text" button clicked again. Maybe it's not a bug. But as far as I know, a standard method of deleting text is by overwriting it.  Maybe an error message section in the help docs would help?

DITA and DITA-OT

My attempt to answer a question that keeps coming my way at regular intervals: isn't DITA-OT the same as DITA?
Short answer: No. Longer answer: Read on.

	DITA	DITA-OT
What is the full form	Darwin Information Type Architecture	DITA Open Toolkit
What is it	A standard. An XML-based architecture for authoring, producing, and delivering technical information	A set of Java-based, open-source tools for processing DITA files
What is the latest stable version	1.1	1.5
Where is it	OASIS DITA Technical Committee	Sourceforge
Who owns it	OASIS DITA Technical Committee	Err, nobody. It's an open-source implementation licenced under CPL 1.0 and Apache Licence v2.0
When's the next update	1.2, under development since 2007 (track what's happening)	1.5.1, planned as a point release for DITA 1.2 and to coincide with the DITA 1.2 release

 

Help and its Usability

A verbose version of this wishlist was published in the Jan-Feb 2010 issue of STC India's newsletter INDUS.

What if my Help was not at all like the Help as we usually see it?

What if every menu option had a tiny Help button with a hovertext that tells me the consequences of a click-through.

What if there was no ToC? What if, instead of a tree of topics, I am shown only one topic? The topic that I reached by clicking the tiny Help button on the options on the menu bar?

What if every Help topic helps me orient myself with a You-Are-Here clickable flow-diagram.

What if all UI fields had examples?

What if the Help button on a UI field opened for me a page that shows the results of a predefined search – a search based on the UI screen I was at (and related to the task I was doing) when I clicked the question mark?

What if the UI had embedded cheat sheets that guide me along.

What if I had On-the-spot troubleshooting where an error message, instead of telling me what went wrong, pops up a wizard with which I can do that which should have been done in the first instance?

What if wishes were horses? Why, I'd gallop along on my tasks with nary a roadblock in sight.