Incremental DITA Builds

Eric Armstrong

DITA builds can be so much better! In particular, it should be possible to do incremental builds, instead of having to rebuild every document, every time. The mechanism for identifying the dependencies is really rather simple, in concept:

Use the Ruby-based Rake build engine, rather than ANT.
That task is on my "someday" list, right next to several other tools I can see building for DITA. Of course, I would use Raven (which can access ANT tasks), and run it on JRuby. But that's a detail.

Benefits of Rake:

  1. Really nice build syntax. Like Make, but without the whitespace sensitivity.

  2. Access to the Ruby language whenever you need it. (Loops, modules, functions? No problem.)

  3. (This is the biggie). You can define your own dependencies--and you can add dependencies to a task at multiple stages.

    (For more, see Rake Rocks!)

Point #3 provides the real power. My plan (should I ever get to the point of implementation) is to use Ruby's REXML parser to read the maps and identify the source files for conrefs (taking into account any ditaval settings), dynamically adding dependencies as I go.

Rake defines a task method. A specialized DITA version of that method would produce a specification that looks something like this:

  dita_task :aDeliverable => [aMap, aValuesFile] do
    ...Invoke the Open ToolKit here...
dita_task is the method that does the work
:aDeliverable is the name of the task (a symbol) that you invoke from the command line: rake aDeliverable
=> defines a hash table, wherein you list the dependencies (a map and optional values file, which would be parsed and used to add dependencies, as appropriate
do..end is the body of the method, where you could invoke the open toolkit to do the processing
(but if we're clever, it may not be necessary to code that).