Design document for SourceForge Patch #1326450 "Make ${basedir} mine"

NOTE: This design is for a patch that was included in the DITA-OT several releases ago. This should no longer be considered the latest information.

Design Description:

Basically, this patch will issue an interface change, all the directories relevant with input, output, and temp, will base on the ${basedir} specified in user's script by default. For example, currently, the ${basedir} of the transformation is set to the toolkit's root directory, input, output, and temp directories will base on this ${basedir} if they are relevant directory, after this change, user can specify their ${basedir} directory in their ant script, then input, output, and temp directories will base on this directory, rather not the toolkit's root directory.

To ensure the toolkit function correctly after this change, our testing should focus on below interfaces that the toolkit provide to the user:
1. The user runs the toolkit use Ant script created base on the sample scripts in "ant/template_*.xml".
2. The user runs the toolkit user Ant script they created by importing the "conductor.xml", as described in this SF Patch 1326450.
3. The user runs the toolkit by calling the Java command line.

The testcases designed for this change need to cover all of the above interfaces.

To apply this patch, we need to do code changes to below files:
1. In conductor_template.xml
The ant property ${dita.dir} should be set to the root directory of the toolkit, by following below procedures:

<dirname property="ant.file.DOST.dir" file="${ant.file.DOST}"/>

<!-- First try to initialize ${dita.dir} using the special
property passed by Ant's import task. -->
<condition property="dita.dir" value="${ant.file.DOST.dir}">
<and>
<isset property="ant.file.DOST"/>
<not>
<isset property="dita.dir"/>
</not>
</and>
</condition>

<!-- Try to initialize ${dita.dir} again if it was not set. -->
<condition property="dita.dir" value="${basedir}">
<not>
<isset property="dita.dir"/>
</not>
</condition>

2. In conductor_template.xml, ditatargets.xml, pretargets.xml
All the paths used to refer to the internal files or directories, including resource, script, catalog, classpath should base on ${dita.dir}.
All the paths used for user relevant files or directories, including input, output, and temp, should base on ${basedir}.

3. In ant/sample_*.xml, ant/template_*.xml
These ant scripts will be updated to show user that now the basedir of these ant scripts won't need to point to the toolkit's root directory, by adding a new property "${dita.dir}" with the toolkit's absolute root directory as the value.

Note: No changes are needed for those old scripts created base on these samples and templates.

4. Changes to the user interfaces
By applying this patch, now the toolkit also enable the user to specify "basedir" and "dita.dir" as parameters in their Ant command, so "/basedir" and "/ditadir" will also needs to be added into the Java command line interface to allow the Java command line user to specify them base on their needs.

Note: This change has no impact of old ant scripts and java command line, their behavior is the same as before.

• Add two parameters "/basedir" and "/ditadir" to the Java command line interface.
• Add two parameters "basedir" and "dita.dir" to the ant scripts.

Parameter	Description	Required
/basedir:{basedir}	parameters.The path of the working directory for transformations, it will be the base of relative paths specified by other	No.
/ditadir:{dita.dir}	The absolute path of the toolkit's home directory.	No.

5. Changes to Java modules
Due to Java modules can't use Ant's ${basedir} as the default path for file handling operations directly, some changes need to be applied to Java modules to ensure that all the file handling operations are absolute paths.

To below two Java moduels, a new parameter for ${basedir} is needed for them to handle the file operations use the basedir as default directory.
GenMapAndTopicListModule
IndexTermExtractModul