DITA tools - 2 (Authoring)

I am very comfortable with using Notepad to write in DITA. But there are times when I forget if a particular DITA tag can be used at a particular place. For example, I regularly forget if <prereq> should precede <context> or follow. At such times, an XML editor that also validates your tags as you type comes in handy.

XMLmind XML Editor is one such tool and comes bundled with the DITA DTDs and schemas. Its personal edition is free to use for non-commercial purposes and is, thus, great if you want a WYSIWYG DITA editor for your learning and other  personal stuff.  With it, you can visually insert DITA tags, specify the attributes of the DITA elements, type your content, and validate your file (the file is valid by default because you'll be unable to insert invalid tags) - everything that an XML editor generally does.

To see a bigger picture, click the picture

The XML editor can be downloaded from http://www.xmlmind.com/xmleditor/persoedition.html.

 

 

DITA tools - 1 (Planning)

Disclaimer: IBM is my employer. But this blog post is mine own. Entirely.

The IBM Information Architecture Workbench is an Eclipse-based freeware that I find marvellously handy for organising my thoughts and then committing those thoughts to DITA files. With it, I can model my ditamaps, generate DITA stub files* for the ditamap nodes, and edit the DITA files. Plus, if I draw a line from File A to File B, it gets registered in the ditamap's relationship table. All pretty neat and clean. It shows me, visually, how my topics are arranged in my book (and lets me move around files with a drag-and-drop action). It also shows me orphan files - those nodes that I created but did not link anywhere. And, I can edit the DITA attributes very easily in the Properties view.

To see a larger picture, click on the picture

One can use this workbench for other assorted activities like Hierarchial Task Analysis diagrams and Role and Goal models but I confess I haven't been there yet. I use it as just an authoring tool. The workbench also has an inbuilt client for CVS, so I can have a multi-author scenario for my files too.

The workbench can be downloaded from https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?lang=en_US&source=swg-iiaw. To download, you need an IBM ID. Anyone can create an IBM ID for oneself - all that's asked is an email address and (I think - have forgotten) a name.

---

*Stub file: A stub file is a DITA topic file created for each of the nodes in the ditamap. Depending on the kind of file you specified while creating the node, the stub file has basic DITA tags for that topic type. The stub files can be opened with the workbench text editor, and edited like any other file. Thus, the workbench doubles up as an authoring software.

Quick and rude guide to DITA - Part 3 of 3

In Part 2 of this series, you created some DITA files. If you are a technical writer working in an organisation that's already using DITA for authoring, you wouldn't really need to bother with transforms and outputs - there will already be a system in place with which you can do a click-and-generate-output (well, almost). You need not, therefore, really bother yourself with this part (Part 3, last of the series) unless you're really eager to see how your DITA files look in HTML. If that's the case, read on.

1. In your root directory, create a subdirectory named Sample.
   
2. In the Sample directory, create three subdirectories, and name them ant_scripts, topics, and out.
   
3. In the Sample > topics directory, put your DITA files. Your DITA files must have dita as the file extension.
   
4. In the Sample directory, put your ditamap file. The file extension of your ditamap file must be ditamap. If needed, edit the ditamap file to correct the filepath reference of your dita files (because now they reside one directory lower than your ditamap).
   
5. Download and install the DITA Open Toolkit (DITA-OT1.4.2.1_full_easy_install_bin.zip).
   
6. Download and install the DITA sample garage files (ditaotug131-18042007-garage.zip).
   
7. Go to the DITA sample garage installation directory and thence to the ant_scripts subdirectory. Look for a file called garage_hierarchy_all.xml, and copy it to your Sample > ant_scripts directory. Rename the copied file to build.xml.
   
8. Edit this build.xml file as follows:
   
   • Replace all instances of DITASAMPLE_GARAGE_OUTPUT with out.
   • Replace all instances of hierarchy.ditamap with the name of your ditamap file.
     
   
   
9. Go to the DITA OT installation directory, look for a file called startcmd.bat, and double-click the file.
   
10. At the DOS command prompt, run the following command: ant -f build.xml dits2xhtml
    If your build.xml file is in a different directory than the DITA OT installation directory, specify the full path of the build.xml file. Your DITA files start getting transformed to XHTML and placed in the out directory you specified in the build.xml file. Wait for the command to complete.
    
11. Quit the DOS prompt, return to Windows Explorer, and go to the out directory. The index.html file is the landing page for all your DITA files.

That's it. You wrote some stuff in DITA, and created an HTML output. You're DITA ready :)

But wait! There's actually an easier option to convert your files to HTML without having to go through the 11 steps I listed. To create your transforms with just one single step, one single command at the DOS prompt, see this excellent article: http://www.ibm.com/developerworks/library/x-tipditajavacmd.html.

 

 

Quick and rude guide to DITA - Intermission

<task>
<title>Celebrating the World Umbrella Day</title>

<shortdesc>To celebrate the World Umbrella Day, which, according to radio reports, falls on Feb 10, 2010, get yourself an umbrella and follow the steps given in this topic.</shortdesc>

<taskbody>
<prereq>
<ul>
<li>Obtain an umbrella.</li>
<li>Navigate to a sufficiently windy place. A place that measures 5 or more on the WindScale is sufficient for the purpose of this task.</li>
</ul>
<prereq>

<context>
<note outputclass="caution">Following the steps listed below might make you lose your possessions including, but not limited to, your umbrella.</note>
</context>

<steps>
<step><cmd>Stand on firm ground and open your umbrella.</cmd></step>
<step><cmd>Watch your umbrella fly away. Simultaneously, sing at the top of your voice <userinput>Chhatri udi, ud ke chali</userinput></cmd></step>
</steps>

<postreq>Acquire a new umbrella.</postreq>
</taskbody>

<related-links>
<link><linktext>http://writing-technical.blogspot.com/2010/01/quick-and-rude-guide-to-dita-part-1.html</linktext></link>
<link><linktext>http://writing-technical.blogspot.com/2010/01/quick-and-rude-guide-to-dita-part-2.html</linktext></link>
</related-links>

<task>