When you click the Build button, oXygen (or more precisely, the the oXygen plugin for Eclipse) launches the Java runtime environment (java.exe), and passes it a ton of arguments (these can also be passed manually from the command line).
Build Log
When you build the docs, you’ll see a verbose version of the build log displayed in the Text window. Copy it (Ctrl+a, Ctrl+c) to the clipboard, and then paste it into your text editor (EditPad Pro). Save this as a text file, and view it as a “Python Script” (because the color coding makes it easier to discern its parts).
This file contains two functional parts:
Build Command
The first part (labelled “Executing:”) is the Build Command, and oXygen executes it to launch the build process (I think you could run a new build just by pasting this into a command prompt & pressing Enter).
With all of its flags, arguments, and properties (about a paragraph’s worth), this command is huge! Since it appears on one line, you can only see about 2% of it. To see it in its entirely, turn on “Word Wrap.”
The Build Command is easier to study if you copy it into a new file in your text editor. I found it helpful to turn on Auto Indent, and then break the command line up (by introducing paragraph breaks) so that similar parts lined up. I found it helpful to enter a quotation mark into the search field because EditPad Pro highlights all of the quotes, so all you can easily match them up, and then break the line after each end quote.
Building Stage Log
Besides setting Xerces as the XML parser, and passing it a configuration file, launches Ant and passes it the Ant build file (build.xml) to processes; which takes the ditamap as its prime argument.
To generate a particular “flavor” of the docs (e.g., webhelp, pdf, etc.), Ant processes a sequence of targets that are specific to that flavor. Since every doc type is a specialized form of a more rudimentary doc type, execution sequences always start with targets for general tasks, and they always end with the most specialized target for that doc type.
Case in point, the DITA Map XHTML docs are further processed to produce the Webhelp docs.
oXygen uses Ant to guide the build process, and Ant applies particular XSL transformations inside Targets.
One reply on “Understanding the Build Chain”
Major thankies for the article. Really looking forward to read more. Cool. Amata Torr Jacklyn