Just Write Click

Technical writing with Continuous Integration and docs-as-code

You are here: Home / DITA / A watched folder for publishing from DITA source files

by

A watched folder for publishing from DITA source files

I’ve figured out a way to automate DITA builds where you just drop a zip file of your DITA source files into a “watched folder” and PDF and CHM files are automatically built

This post describes creating a watched folder that runs DITA transforms on content that is copied into the folder on a shared server. It also gives instructions for using this “transform engine” to output both PDF and CHM files using the default DITA Open Toolkit transform files. I devised this set up so that we could test our prototypes while we model our existing content, and I wanted to share it with others who are getting started with DITA on a small scale.

Now for the disclaimers! To many, reading my batch file coding will be like watching amateur mic night at an improv comedy club, but I welcome suggestions and improvements to this system. I offer it without warranty and fully disclose that the batch files actually delete files on your system (in a space-saving effort) and may very well fill up your hard drive with generated PDF and CHM files. So don’t say I didn’t warn you! I tell you, use at your own risk.

Now that I’ve disclaimed appropriately, I want to say that I think it offers a bootstrap automation effort for DITA builds and I wanted to give it out in case it helps others.

Prerequisites

Ensure that WinZip can be run within a batch file (command line).
 The batch files for the server-based transform engine call WinZip using DOS commands. In order to ensure that the version of WinZip that the server is using supports command-line calls, download and install the Winzip Command Line Support Plug-In from this link.

Ensure that the DITA Open Toolkit works properly

The DITA Open Toolkit must be installed and running correctly on a Windows computer by installing all the pre-requisites and testing transforms. Refer to the documentation accompanying the DITA Open Toolkit to meet this prerequisite. Basically, you’ll need the DITA Open Toolkit, available at http://sourceforge.net/project/showfiles.php?group_id=132728. Download and unpackage the zip on your hard drive. The full packages of the DITA Open Toolkit contain all the sub-tools that you need for full evaluation from authoring to building output. Most of these tools require the Java Platform, so, Java is a prerequisite to using the DITA Open Toolkit. Download and install the Java Platform Standard Edition (SE) 5.0, available at http://java.sun.com/j2se/index.jsp.

Ensure that the Idiom Plug-in works properly

To run PDF2 transforms, follow these instructions to install the pre-requisites for it and install the plug-in itself. http://dita-ot.sourceforge.net/doc/ot-userguide13/xhtml/plugins/installing_fo.html. For some reason, this detailed-level topic has been eliminated from the 1.3.1 documentation, and I couldn’t find another detailed installation topic like this one, so, that’s why I’m linking to an outdated topic in the DITA Open Toolkit.

Download the bootstrap automation files

Download this zip of batch files, ant files, and a custom css file that make up the “transform engine.” The “engine” consists of five batch files and three Ant build files. They are currently set to work in a DITA-base directory named c:\DITA-OT1.3.1 but you can rename the DITA-base directory as needed.

Installing the transform engine on a shared server

  1. In the DITA Open Toolkit working directory, create a dita_in directory. For example, c:\dita-ot\dita_in.
  2. Unzip the batch files and Ant build files into the <dita-ot>\dita_in directory.
  3. Unzip the CSS file into the <dita-ot>\css directory.
  4. Edit the files if needed to match your directory structure. For example, the DITA working directory is set to C:\DITA-OT1.3.1 and you might need to change that in every file to match your environment.
  5. Enable sharing for the dita_in folder.
  6. In the DITA Open Toolkit working directory, create a dita_out directory.
  7. Enable sharing for the dita_out folder.
  8. Copy the bmc_dita_chm.css file to the DITA Open Toolkit working directory in the css directory, for example C:\DITA-OT1.3.1\css. The ant CHM build file uses this CSS file to substitute a Verdana-font-based CSS file instead of the default DITA CSS.
  9. Create a Windows Scheduled Task to run the dita_in\buildDITA.bat file every 10 minutes.

Submitting DITA maps to be transformed

  1. Place all topic files, graphics files, and the ditamap file in a folder, ensuring that the map file has the .ditamap extension and is in the root directory.
  2. Zip the folder into a zip file. Be sure to check the Save full path info option.
    You can name the zip file anything.
  3. Copy the zip file into the \\serverName\dita_in folder.
    The next time the buildDITA.bat scheduled task starts, it will kick off the transforms.
  4. Wait at least 10-12 minutes for the transform to complete.
    Note: The transform itself should not take this long, but the timing of the watched batch file to run is scheduled on 10 minute intervals.
  5. Once the transforms are complete, copy the PDF and CHM files from the \\serverName\dita_out\htmlhelp and \\serverName\dita_out\pdf or \pdf2 folders.Thanks to the renameOutputFiles.bat batch file, the file names will have a time/date stamp with the following notation: yymmdd_hhmmss.pdf. Example: 052507_101540.pdf. Also, extra files that are generated during the transform are deleted with this batch file, so you can modify that batch file if you want to keep dita.list and other precursor files.

That’s all there is to it. Please let me know your feedback and suggestions for improvement.