source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/readme/creating-an-ant-build-script.dita@ 99012

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="creating-an-ant-build-script">
    <title>Creating an Ant build script</title>
    <shortdesc>Instead of typing the DITA-OT parameters at the command prompt, you might want to
        create an Ant build script that contains all of the parameters.</shortdesc>
    <taskbody>
        <steps>
            <step>
                <cmd>Create an XML file that contains the following content:</cmd>
                <info>
                    <codeblock>&lt;?xml version="1.0" encoding="UTF-8" ?>
&lt;project name="@project-name@" default="@default-target@" basedir=".">

  &lt;property name="dita.dir" location="@path-to-DITA-OT@"/>
 
  &lt;target name="@target-name@">
    &lt;ant antfile="${dita.dir}${file.separator}build.xml">
      &lt;property name="args.input" value="@DITA-input@"/>
      &lt;property name="transtype" value="xhtml"/>
    &lt;/ant>
  &lt;/target>

&lt;/project></codeblock>
                </info>
                <info>You will replace the placeholder content (indicated by the @ signs) with
                    content applicable to your environment.</info>
            </step>
            <step>
                <cmd>Specify project information:</cmd>
                <substeps>
                    <substep>
                        <cmd>Set the value of the @name attribute to X.<draft-comment
                                author="Kristen James Eberlein" time="11 August 2012">What does X
                                need to be? Does it really matter? I tend to set this attribute to
                                the string that I use for the name of the Ant
                                script.</draft-comment></cmd>
                    </substep>
                    <substep>
                        <cmd>Set the value of the @default attribute to the name of a target in the
                            build script.</cmd>
                        <info>If the build script is invoked without specifying a target, this
                            target will be run.</info>
                    </substep>
                </substeps>
            </step>
            <step>
                <cmd>Set the value of the <parmname>dita.dir</parmname> property to the location of
                    the DITA-OT.</cmd>
                <info>This can be a fully qualified path, or you can specify it relative to the
                    location of the Ant build script that you are writing. </info>
            </step>
            <step>
                <cmd>Create the Ant target:</cmd>
                <substeps>
                    <substep>
                        <cmd>Set the value of the @name attribute.</cmd>
                    </substep>
                    <substep>
                        <cmd>Specify the value for the <parmname>args.input</parmname>
                            property.</cmd>
                    </substep>
                    <substep>
                        <cmd>Specify the value of the <parmname>transtype</parmname> property.</cmd>
                    </substep>
                </substeps>
            </step>
            <step>
                <cmd>Save the build script.</cmd>
            </step>
        </steps>
        <example>
            <p>The following Ant build script generates CHM and PDF output for the
                    <filepath>userguide.ditamap</filepath>
                file.<codeblock>&lt;?xml version="1.0" encoding="UTF-8" ?>
&lt;project name="Toolkit-documentation" default="all" basedir=".">
    
    &lt;property name="dita.dir" location="C:\DITA-OT1.6.M5"/>
    
    &lt;target name="all" description="build CHM and PDF" depends="chm,pdf"/>
    
    &lt;target name="chm" description="build CHM">
        &lt;ant antfile="${dita.dir}\build.xml">
            &lt;property name="args.input" value="C:\dita-ot\src\main\doc\userguide.ditamap"/>
            &lt;property name="args.gen.task.lbl" value="YES"/>   
            &lt;property name="output.dir" value="C:\kje\temp\out"/>
            &lt;property name="transtype" value="htmlhelp"/>
        &lt;/ant>
    &lt;/target>
    
    &lt;target name="pdf" description="build PDF">
        &lt;ant antfile="${dita.dir}\build.xml">
            &lt;property name="args.input" value="C:\dita-ot\src\main\doc\userguide.ditamap"/>
            &lt;property name="args.gen.task.lbl" value="YES"/>   
            &lt;property name="args.rellinks" value="nofamily"/>   
            &lt;property name="output.dir" value="C:\kje\temp\out"/>
            &lt;property name="transtype" value="pdf"/>
        &lt;/ant>
    &lt;/target>
    
&lt;/project></codeblock></p>
            <p>In addition to the mandatory parameters (<parmname>args.input</parmname> and
                    <parmname>transtype</parmname>), the chm and pdf targets each specify some
                optional parameters:<ul>
                    <li>The <parmname>args.gen.task.lbl</parmname> property is set to YES, which
                        ensures that headings are automatically generated for the sections of task
                        topics.</li>
                    <li>The <parmname>output.dir</parmname> property specifies where the DITA OT
                        writes the output   of the transformations.</li>
                </ul></p>
            <p>The pdf target also specifies that related links should be generated in the PDF, but
                only those links that are created by relationship tables and &lt;link> elements.</p>
            <p>Finally, the all target simply specifies that both the chm and pdf target should be
                run.</p>
        </example>
        <postreq>Another resource for learning about Ant scripts are the files in the
                <filepath>samples/ant_samples</filepath> directory. This directory contains the Ant
            build files used by the demo build, as well as templates that you can use to create Ant
            scripts.</postreq>
    </taskbody>
</task>