Introducing WinANT

Contents

• The Genesis
• Apache Ant
• Ant and DITA
• The DITA OT Publishing Process
• The Problem
• WinANT Functionality
• WinANT at Swinburne University of Technology
• Extensions
• Where Do You Get It?

The Genesis     

I am old enough to have worked in a DOS world. My first interest in online documentation and Help systems was piqued in the 1980s by the online Help for the Wang WP+ word processing system, running on a Wang VS "minicomputer". When WinHelp appeared in the early 1990s, I was impressed by its speed, features and interface. As an early adopter, I soon had to face the arcane RTF markup required to create the source documents, and the archaic, DOS command line compiling process.

A decade later, as a (relatively) early adopter of DITA, I experienced a sense of deja vu . Marking up DITA documents in text-based XML editors reminded me of the old RTF markup, and using the Ant build tool in the DITA Open Toolkit (OF) to publish DITA collections - from a command line - was like the Help compiler all over again. Only the Ant build process was probably more complicated and less repeatable than the Help compiler.

I didn't feel any fondness for those "good old days", so I decided to simplify the DITA publishing process for myself by building a Windows interface to Ant.

Apache Ant     

Apache Ant is a Java-based "build tool", developed by the Apache Software Foundation (a not-for-profit organisation that supports a number of open-source software projects, including the Apache Web Server).

A build tool is used to automate a series of software commands.

In the programming field (and in Java programming especially), build tools and build file scripts are commonplace.

Ant was developed to allow programmers to write a simple build file in an XML format, and then process that XML file with the Ant build software.

What now? The Ant user interface.

Ant and DITA     

Transforming a collection of DITA topics into a deliverable format such as PDF is not a simple, one-step technical process. For example, a ditamap has to be processed against a series of XSL-T files by an XSL-T processor to transform the DITA topics referenced by the map into an XSL-FO document. That XSL-FO document then has to be processed by an XSL-FO processor to turn the XSL-FO document into a PDF file. (And that's the simplified version!)

The need for some sort of automated build process is obvious, and Ant is included in the DITA Open Toolkit for this reason. Ant is an ideal tool for automating the task of publishing DITA content.

The DITA OT Publishing Process     

The DITA publishing process using Ant and the DITA OT is as follows:

1. Write a build file (in Ant's special XML format) to specify the DITA content to transform, the conditional processing to be done, the processor to use, and any other information required by the processors.
2. At the command prompt, run Ant and pass it a command line instructing it which build file to execute.

This can be a quite time-consuming and tricky process. Every time you build an output, you have to re-key the command line (after perhaps tinkering with the build file). The DITA OT includes some sample build files that can be used as 'templates' for your own build files, along with instructions documenting the steps.

The Problem     

Ant provides no facility to manage the build process. While a user can save a build file for later use, the command line has to be re-keyed every time the document is published. A typical command line might be ant -f c:\ditadocs\projecta\userguide.xml.

The creation of the build file is a clumsy task. Normally, an existing template is modified to suit a new document, using a text-based editor. For conditional processing (flagging or excluding content based on metadata attributes), an additional XML file, the ditaval file, must also be prepared (again in a text editor).

I wanted the build process to be a straightforward "wizard" process; I didn't want to be coding XML files, or remembering command lines, or re-entering the same information from build to build. Happily, I have accumulated some Visual Basic programming skills over the years, and was able to start work on a Windows program to simplify the build process. Without terribly much thought, I named the project "WinANT".

WinANT Functionality     

WinANT is a Windows program, build with Microsoft Visual Studio .NET 2003 using VB.NET. It serves as an interface to the Ant build utility, for the sole purpose of processing DITA documents.

WinANT allows a user to select build characteristics using normal Windows interface devices such as dropdown lists, radio buttons, tabs and browse buttons. When all the required settings are in place, the program creates the Ant build file, creates a ditaval file (if required), creates a batch file, and then executes the batch file to trigger the Ant build. When Ant has finished the processing, WinANT displays the generated output file. The settings can be saved (as a build file) and later recalled.

WinANT 1.4 - Main tab

The Ant "arguments" that can be set within WinANT include:

• the folder where the output will be created;
• the type of output;
• a CSS stylesheet to be applied to each output HTML page;
• a file containing HTML code to be added to the <head> section of each output HTML page;
• a file containing HTML code to be added to the top of the <body> section of each output HTML page;
• a file containing HTML code to be added to the bottom of the <body> section of each output HTML page;
• a list of files to be copied to the output folder (or compiled into HTML Help output);
• conditional processing rules;
• images to be used for flagging conditional text;
• the DITA topic file extension used;
• the output HTML file extension to be used;
• whether content marked as draft will be included in the output; and
• the map and alias files to be incorporated into HTML Help output.

Note:

<param name="HELPMAP" />
<param name="HELPALIAS" />

<param name="HELPMAP" expression="${dita.map.filename.root}.h" />
<param name="HELPALIAS" expression="${dita.map.filename.root}.ali" />

Many of the settings, particularly for HTML-based output (on which WinANT is focussed), are automatically populated, and some sample HTML and CSS files make it easy to get up and running quickly.

In the early versions, WinANT would only run if the DITA Open Toolkit files were located in a particular folder, and if the Java environment variables were set a particular way, and if version 1.2 of the OF was being used. In other words, it would only work on my own PC! It was easy to see that the tool would be useful to people other than myself too, so I improved the program so it would work in a variety of environments. I also added the ability to view the Ant log file, a list of files processed, and the build and ditaval files generated.

WinANT 1.4 - Conditional tab

Getting the program to this point was not a quick process. In fact, it had taken close to a year, primarily because once I had the program working on my own PC, it's further development lost priority! I enlisted the help of my daughter, Fióna, who was studying programming with Visual Basic, and that kicked the project along.

WinANT 1.4 - Flags tab

Another area that I was working on separately was controlling the look-and-feel of generated HTML output using CSS and JavaScript. I devised a way to store pre-defined combinations of CSS, head block, header and footer HTML snippets in "skins", which could be easily applied from a WinANT menu.

WinANT 1.4 - Skins menu

WinANT at Swinburne University of Technology     

In August 2007, Swinburne University of Technology (in Melbourne, Australia) introduced a Structured Authoring with DITA subject to its Technical Communication program. I developed the course, and would be the first to deliver it in the classroom.

I wanted students to focus on DITA as a writing approach, and not get bogged down with the intricacies of Ant and the Open Toolkit. Publishing tutorials were therefore build around WinANT, which was installed both in the classroom and on students' home PCs. Although the DITA OT installation created many headaches for students, the WinANT installation ended up being straightforward. The only modification I needed to add was the ability to manually specify the location of the DITA OT folder, and a "resolver" checkbox to cope with slightly different configuration possibilities.

Students found the tool easy to use. Separating the publishing tool (WinANT) from the authoring tool used in class (XMLmind XML Editor) helped reinforce to students the principal of separation of content and form.

WinANT 1.4 - Advanced tab

WinANT is also being used by Allyn Radford from Learnilities; Allyn was very helpful in identifying a number of configuration bugs.

Extensions     

The standard transformers in the DITA OT leave the short description (<shortdesc>) element in the generated output. In most cases, I do not want the short description to appear in the output. To make it easy to choose this option, I added an omit shortdesc option to the interface, which results in an alternative custom XSL file being used for the transformation.

I also added Shawn McKenzie's excellent JavaScript Table of Contents plugin (tocjs) to output type (transtype) selection; this option will only work if the user has installed that plugin. I intend doing the same with Deborah Pickett's htmlhelp2 context-sensitive Help demonstration and xhtml1 single HTML output plugins.

Where Do You Get It?     

WinANT can be downloaded without charge on a "take it as it comes" basis from http://www.helpml.com/winant_setup.exe. If you find the tool useful, I'd be grateful for feedback.