Note: Significant ANT refactoring was done in the 1.3 and 1.3.1 versions of the toolkit, so this information no longer reflects the current design. Up to date information on the toolkit can be found here: The DITA Open Toolkit

Requirement/Problem:
Currently, in the toolkit, it is difficult to pick out specific targets to use. Most of the targets depend on other tasks, which depend on other tasks. For example - most of the output processing depends on the target "dita-preprocess". This target depends on many other targets. One of those, "preprocess", depends on many more targets. When users are debugging a problem, or when they want to add an additional step, it is very difficult to find which task to modify. Also, it is difficult to change the preprocess for one type of transform, but let the others use the normal build.

The ANT code is difficult to understand because there is no easy way to see what steps are performed during a transform. There is also no easy way to modify the middle of a transform.


Design Description:

1. ANT "all" task in build.xml
Below is the current Ant "all" tast structure:
all: demo, doc, samples, docbook
demo: demo.book, demo.elementref, demo.enote, demo.faq, demo.langref
doc: doc.langref.web, doc.articles.web, doc.readme.web, doc.installguide.chm
samples: samples.web, samples.eclipse, samples.javahelp, samples.htmlhelp, samples.pdf
docbook

The main usage of Ant "all" task is used to validate the correctness of installation, I think we just need to keep the demo and samples tasks in it.
Suggest changes:
remove demo.langref (langref need long time to build)
remove doc
remove docbook

2. Reorganize ANT tasks in conductor.xml, ditatargets.xml, pretargets.xml
2.1 Create build scripts by steps
1. build_init.xml
move all properties, taskdefs definition and "use-init", "check-arg", "start-process", "output-deprecated-msg", "output-css-warn-message", "init-logger" tasks from conductor.xml.

2. build_preprocess.xml
move all tasks from pretargets.xml

3. build_general.xml
move dita.topics.xhtml from ditatargets.xml
create dita.topics.html base on dita.topics.javahelp

4. build_dita2xhtml.xml
import build_init.xml, build_preprocess.xml, build_general.xml
move "dita2xhtml", "map2xhtml" from conductor.xml
move "dita.map.xhtml" from ditatargets.xml

5. build_dita2pdf.xml
import build_init.xml, build_preprocess.xml
move "dita2pdf", "topic2pdf", "map2pdf" from conductor.xml
move "dita.topic.fo", "dita.fo2pdf", "dita.map.fo", "dita.fo2pdf" from ditatargets.xml

6. build_dita2htmlhelp.xml
import build_init.xml, build_preprocess.xml, build_general.xml
move "dita2htmlhelp" from conductor.xml
move "dita.map.htmlhelp", "compile.HTML.Help" from ditatargets.xml
move "dita.topics.htmlhelp" from ditatargets.xml, clear it's content and let it depends on dita.topics.html, mark it as deprecated and remove it in a later release

7. build_dita2javahelp.xml
import build_init.xml, build_preprocess.xml, build_general.xml
move "dita2javahelp" from conductor.xml
move "dita.map.javahelp", "compile.Java.Help" from ditatargets.xml
move "dita.topics.javahelp" from ditatargets.xml, clear it's content and let it depends on dita.topics.html, mark it as deprecated and remove it in a later release

8. build_dita2eclipsehelp.xml
import build_init.xml, build_preprocess.xml, build_general.xml
move "dita2eclipsehelp" from conductor.xml
move "dita.topics.eclipse", "dita.map.eclipse", "dita.map.plugin" from ditatargets.xml
move "dita.topics.eclipse" from ditatargets.xml, clear it's content and let it depends on dita.topics.xhtml, mark it as deprecated and remove it in a later release

9. build_dita2eclipsecontent.xml
import build_init.xml, build_preprocess.xml
move "dita2eclipsecontent" from conductor.xml
move "dita.map.eclipse.content",  "dita.topics.eclipse.content" from ditatargets.xml

10. build_dita2wordrtf.xml
import build_init.xml, build_preprocess.xml
move "dita2wordrtf", "map2wordrtf", "topic2wordrtf" from conductor.xml
move "dita.topic.rtf", "dita.map.rtf" from ditatargets.xml

11. build_dita2docbook.xml
import build_init.xml, build_preprocess.xml
move "dita2docbook", "topic2docbook",  "map2docbook" from conductor.xml
move "dita.map.docbook", "dita.topic.docbook" from ditatargets.xml

12. build_dita2troff.xml
import build_init.xml, build_preprocess.xml
move "dita2troff" from conductor.xml
move "dita.topic.troff" from ditatargets.xml


2.2 Update conductor.xml, ditatargets.xml, pretargets.xml
1. conductor.xml
Remove relevant tasks that have been moved into above ANT scripts, and import all above ANT scripts.
Note: After the refactoring, conductor.xml still can be used as usual, it's a general entry for all the transformations. But the user also use above build_*.xml for their specific transformation without using conductor.xml.

2. ditatargets.xml
No changes to ditatargets.xml, it will be kept for backward compatibility, but conductor.xml will not import it.

3. pretargets.xml
Remove its content and import build_preprocess.xml, it will be kept for backward compatibility, but conductor.xml will not import it.

2.3 Sample build_dita2xhtml.xml

<?xml version="1.0" encoding="UTF-8"?> <project name="dita2xhtml" default="dita2xhtml"> <import file="build_init.xml" />   <import file="build_preprocess.xml" /> <target name="dita2xhtml"     depends="build-init, start-preprocess, clean-temp, gen-list,                      copy-files, debug-filter, move-index-entries, conref, mappull,                      maplink, move-links, topicpull, dita.map.xhtml, copy-revflag,                      copy-css, dita.topics.xhtml">   </target> <target name="dita.topics.xhtml"     description="Build XHTML output from dita topics"     depends="copy-revflag, copy-css">     <condition property="out.ext" value=".html">       <not>         <isset property="out.ext" />       </not>     </condition>     <condition property="args.xsl"       value="${dita.script.dir}${file.separator}dita2xhtml.xsl">       <not>         <isset property="args.xsl" />       </not>     </condition>     <xslt processor="trax" basedir="${dita.temp.dir}"       destdir="${output.dir}" includes="${fullditatopiclist}"       extension="${out.ext}" style="${args.xsl}">       <param name="DITAEXT" expression="${dita.ext}" if="dita.ext" />       <param name="FILTERFILE" expression="${dita.input.valfile}"         if="dita.input.valfile" />       <param name="CSS" expression="${args.css.file}"         if="args.css.file" />       <param name="CSSPATH" expression="${user.csspath}"         if="user.csspath" />       <param name="HDF" expression="${args.hdf}" if="args.hdf" />       <param name="HDR" expression="${args.hdr}" if="args.hdr" />       <param name="FTR" expression="${args.ftr}" if="args.ftr" />       <param name="DRAFT" expression="${args.draft}" if="args.draft" />       <param name="ARTLBL" expression="${args.artlbl}" if="args.artlbl" />       <param name="INDEXSHOW" expression="${args.indexshow}"         if="args.indexshow" />       <param name="OUTEXT" expression="${out.ext}" if="out.ext" />     </xslt>   </target> <target name="dita.map.xhtml" unless="noMap"     description="Build HTML TOC file from ditamap">     <condition property="out.ext" value=".html">       <not>         <isset property="out.ext" />       </not>     </condition>     <condition property="args.xhtml.toc" value="index">       <not>         <isset property="args.xhtml.toc" />       </not>     </condition>     <xslt processor="trax" basedir="${dita.temp.dir}"       destdir="${output.dir}" includes="${user.input.file}"       style="${dita.script.dir}${file.separator}map2htmtoc.xsl">       <param name="DITAEXT" expression="${dita.ext}" if="dita.ext" />       <param name="OUTEXT" expression="${out.ext}" if="out.ext" />       <mapper type="glob" from="*${dita.input.filename}"         to="*${args.xhtml.toc}${out.ext}" />     </xslt>   </target> </project>

3 File Renaming

1. Rename build.xml to build_demo.xml

2. Rename conductor.xml to build.xml

3. Still include the file "conductor.xml" for back-compatibility, and this new conductor.xml file will do nothing except import build.xml

4. Mark the conductor.xml file as deprecated and remove it in a later release.

4. Changes to sample ANT scripts in "/ant" directory

Replace all the references to "conductor.xml" with "build.xml".