Info for the dita command, properties files, migrating ant builds

dita-ot · Jan 31, 2016 · 454303b · 454303b
1 parent c464d74
commit 454303b
Show file tree

Hide file tree

Showing 20 changed files with 448 additions and 102 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,8 @@
 out/
 temp/
 build/
+logs/
+samples/properties/template.properties
 
 ## Autogenerated files created by the build process
 platform.ditaval

diff --git a/build.xml b/build.xml
@@ -11,9 +11,15 @@
   </condition>
 
   <property name="dita.home" location="${env.DITA_HOME}"/>
-  <condition property="doc.out.dir" value="${dita.home}/doc" else="${basedir}/out">
+  <condition property="toolkit.build" value="true" else="false">
     <available file="${basedir}/../lib/dost.jar" type="file"/>
   </condition>
+  <condition property="doc.out.dir" value="${dita.home}/doc" else="${basedir}/out">
+    <istrue value="${toolkit.build}"/>
+  </condition>
+  <condition property="doc.samples.dir" value="${dita.home}/docsrc/samples" else="${basedir}/samples">
+    <istrue value="${toolkit.build}"/>
+  </condition>
 
   <macrodef name="dita-ot">
     <attribute name="transtype"/>
@@ -90,7 +96,7 @@
   <target name="generate-properties-file" depends="init" description="Regenerate annotated .properties file">
     <property name="propfile.xsl" location="${basedir}/resources/properties-file.xsl"/>
     <property name="propfile.input" location="${resource.dir}/plugins.xml"/>
-    <property name="propfile.output" location="${doc.out.dir}/samples/template.properties"/>
+    <property name="propfile.output" location="${doc.samples.dir}/properties/template.properties"/>
     <xslt in="${propfile.input}" out="${propfile.output}" style="${propfile.xsl}" force="yes"/>
   </target>
 

diff --git a/getting-started/getting-started.ditamap b/getting-started/getting-started.ditamap
@@ -6,7 +6,11 @@
   <title>Getting started</title>
   <topicref href="index.dita" collection-type="sequence">
     <topicref href="../user-guide/installing-client.dita" copy-to="installing-client.dita"/>
-    <topicref href="../user-guide/using-dita-command.dita" copy-to="using-dita-command.dita">
+    <topicref href="../user-guide/using-dita-command.dita" copy-to="using-dita-command.dita"
+      keys="first-build-using-dita-command">
+      <topicmeta>
+        <navtitle>Building output</navtitle>
+      </topicmeta>
       <ditavalref href="../resources/novice.ditaval">
         <ditavalmeta>
           <dvrResourcePrefix>first-build-</dvrResourcePrefix>

diff --git a/parameters/dita-command-arguments.dita b/parameters/dita-command-arguments.dita
@@ -110,13 +110,13 @@
     </section>
     <section>
       <title>Options</title>
-      <parml>
+      <parml id="dita_build_options">
         <plentry>
           <pt><parmname>-o</parmname>, <parmname>-output</parmname>
             <varname>dir</varname></pt>
-          <pd id="output.dir.desc">Specifies the path of the output directory; the path can be absolute or relative to
-            the current directory. By default, the output is written to the <filepath>out</filepath> subdirectory of the
-            current directory.</pd>
+          <pd id="output.dir.desc">Specifies the path of the output directory; the path can be
+            absolute or relative to the current directory. By default, the output is written to the
+              <filepath>out</filepath> subdirectory of the current directory.</pd>
         </plentry>
         <plentry>
           <pt><parmname>-filter</parmname>
@@ -142,20 +142,20 @@
           <pd>Write logging messages to a file.</pd>
         </plentry>
         <plentry>
-          <pt><parmname>-D</parmname><varname>property</varname>=<varname>value</varname></pt>
-          <pd>Specify a value for a parameter. Supported parameters are the same as Ant parameters and are
-            transformation type specific.</pd>
+          <pt><parmname>-D</parmname><varname>parameter</varname>=<varname>value</varname></pt>
+          <pd>Specify a value for a DITA-OT or Ant build parameter. <p>Parameters not implemented by
+              the specified transformation type or referenced in a <filepath>.properties</filepath>
+              file are ignored.</p><note conref="../resources/conref-task.dita#ID/pass-input-dir"
+            /></pd>
         </plentry>
         <plentry>
           <pt><parmname>-propertyfile</parmname>
             <varname>file</varname></pt>
-          <pd>Load all properties from a file. Properties specified with the <parmname>-D</parmname> option take
-            precedence.</pd>
+          <pd>Use build parameters defined in the referenced <filepath>.properties</filepath> file.
+              <p>Build parameters specified on the command line override those set in the
+                <filepath>.properties</filepath> file.</p></pd>
         </plentry>
       </parml>
     </section>
   </refbody>
-  <related-links>
-    <link href="parameters_intro.dita"/>
-  </related-links>
 </reference>
diff --git a/parameters/reference.ditamap b/parameters/reference.ditamap
@@ -4,7 +4,7 @@
 
 <map>
   <title>Reference</title>
-  <topicref href="parameters_intro.dita">
+  <topicref href="parameters_intro.dita" keys="dita-ot-params">
     <topicref href="parameters-base.dita" navtitle="Common"/>
     <topicref href="parameters-base-html.dita" navtitle="HTML-based output formats">
       <topicref href="generate-copy-outer.dita" toc="no"/>
@@ -20,10 +20,10 @@
     <topicref href="parameters-pdf.dita" navtitle="PDF"/>
     <topicref href="ant-parameters-details.dita" processing-role="resource-only" toc="no"/>
   </topicref>
-  <topicref href="dita-command-arguments.dita"/>
+  <topicref href="dita-command-arguments.dita" keys="dita-command-arguments"/>
   <topicref href="configuration-properties.dita">
     <topicref href="lib-plugin-properties.dita"/>
     <topicref href="lib-configuration-properties.dita" navtitle="lib/configuration.properties file"/>
   </topicref>
-  <topicref href="internal-ant-properties.dita"/>
+  <topicref href="internal-ant-properties.dita" keys="internal-ant-properties"/>
 </map>
diff --git a/resources/conref-task.dita b/resources/conref-task.dita
@@ -5,36 +5,60 @@
 <task id="ID">
   <title>Conref file for tasks</title>
   <taskbody>
+    <context>
+      <dl>
+        <dlentry>
+          <dt>Standard Path / Directory Names</dt>
+          <dd><filepath id="ot-dir"><varname>dita-ot-dir</varname></filepath></dd>
+          <dd><filepath id="dita-cmd"
+              ><varname>dita-ot-dir</varname>/bin/<cmdname>dita</cmdname></filepath></dd>
+          <dd><filepath id="samples-dir"
+            ><varname>dita-ot-dir</varname>/docsrc/samples</filepath></dd>
+        </dlentry>
+      </dl>
+    </context>
     <steps>
       <step>
         <cmd id="open-terminal">Open a command prompt or terminal session, and then change to the directory where the
           DITA Open Toolkit is installed.</cmd>
         <info>
           <ul id="basic-variables">
-            <li><varname>install-dir</varname> is the DITA-OT installation directory path.</li>
+            <li id="novice-variables-1"><filepath conref="#ID/ot-dir"/> is the DITA-OT installation
+              directory.</li>
             <li><varname>input-file</varname> is the DITA map or DITA file that you want to process.</li>
-            <li><varname>format</varname> is the output format (transformation type).</li>
-            <li audience="expert"><varname>parameter-name</varname> is the name of an optional parameter.</li>
-            <li audience="expert"><varname>value</varname> is an applicable value for the optional parameter.</li>
-            <li><varname>output-dir</varname> is the output directory path for generated output.</li>
-          </ul>
-          <ul id="basic-variables-novice">
-            <li><varname>install-dir</varname> is the DITA-OT installation directory path.</li>
-            <li><varname>input-file</varname> is the DITA map or DITA file that you want to process.</li>
-            <li><varname>format</varname> is the output format (transformation type).</li>
-            <li><varname>output-dir</varname> is the output directory path for generated output.</li>
+            <li id="novice-variables-last"><varname>format</varname> is the output format
+              (transformation type). Use the same values available for the
+                <parmname>transtype</parmname> build parameter, for example, <codeph>html5</codeph>
+              or <codeph>pdf</codeph>.</li>
+            <li id="options"><varname>options</varname> include the following optional build
+                parameters:<parml
+                conref="../parameters/dita-command-arguments.dita#dita-command-properties/dita_build_options">
+                <plentry>
+                  <pt/>
+                  <pd/>
+                </plentry>
+              </parml></li>
           </ul>
         </info>
         <stepresult id="running-ditaot-results">
-          <p>If processing is successful, nothing is printed in the terminal window.</p>
-          <p>If you do not specify an output directory, the <cmdname>dita</cmdname> command writes output to the
-              <filepath>out</filepath> subdirectory of the current directory.</p>
-          <note id="dita-in-path" type="tip">If you add the absolute path for the DITA-OT
-                <filepath><varname>install-dir</varname>/bin</filepath> directory to the <varname>PATH</varname>
-            environment variable, you can run the <cmdname>dita</cmdname> command from any location on the file
-            system.</note>
+          <p>If processing is successful, nothing is printed in the terminal window. The built
+            output is written to the specified output directory (by default, in the
+              <filepath>out</filepath> subdirectory of the current directory).</p>
+          <note id="dita-in-path" type="tip">Add the absolute path for <filepath conref="#ID/ot-dir"
+              /><filepath>/bin</filepath> to the <varname>PATH</varname> environment variable to run
+            the <cmdname>dita</cmdname> command from any location on the file system without typing
+            the path.</note>
         </stepresult>
       </step>
     </steps>
+    <postreq>
+      <note type="tip" id="template-properties">Copy <filepath conref="#ID/samples-dir"
+          /><filepath>/properties/template.properties</filepath>; this template describes each of
+        the properties you can set.</note>
+      <note type="tip" id="pass-input-dir">If you are building in different environments where the
+        location of the input files is not consistent, set <option>args.input.dir</option> with the
+          <cmdname>dita</cmdname> command  and reference its value with
+          <codeph>${args.input.dir}</codeph> in your <filepath>.properties</filepath> file.</note>
+    </postreq>
   </taskbody>
 </task>
diff --git a/samples/ant_sample/build-chm-pdf-hybrid.xml b/samples/ant_sample/build-chm-pdf-hybrid.xml
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<project name="build-chm-pdf-hybrid" default="all" basedir=".">
+  <description>An Ant build that calls the dita command</description>
+
+  <include file="dita-cmd.xml"/><!-- defines the <dita-cmd> macro -->
+
+  <target name="all" depends="pre,main,post"/>
+
+  <target name="pre">
+    <description>Preprocessing steps</description>
+  </target>
+
+  <target name="main">
+    <description>Build the CHM and PDF with the dita command</description>
+    <dita-cmd input="../sequence.ditamap" format="htmlhelp" propertyfile="../properties/chm.properties"/>
+    <dita-cmd input="../taskbook.ditamap" format="pdf" propertyfile="../properties/pdf.properties"/>
+  </target>
+
+  <target name="post">
+    <description>Postprocessing steps</description>
+  </target>
+
+</project>
diff --git a/samples/ant_sample/build-chm-pdf.xml b/samples/ant_sample/build-chm-pdf.xml
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<project name="build-chm-pdf" default="all" basedir=".">
+
+  <property name="dita.dir" location="${basedir}/../../.."/>
+
+  <target name="all" description="build CHM and PDF" depends="chm,pdf"/>
+
+  <target name="chm" description="build CHM">
+    <ant antfile="${dita.dir}/build.xml">
+      <property name="args.input" location="../sequence.ditamap"/>
+      <property name="transtype" value="htmlhelp"/>
+      <property name="output.dir" location="../out/chm"/>
+      <property name="args.gen.task.lbl" value="YES"/>
+      <property name="args.breadcrumbs" value="yes"/>
+    </ant>
+  </target>
+
+  <target name="pdf" description="build PDF">
+    <ant antfile="${dita.dir}/build.xml">
+      <property name="args.input" location="../taskbook.ditamap"/>
+      <property name="transtype" value="pdf"/>
+      <property name="output.dir" location="../out/pdf"/>
+      <property name="args.gen.task.lbl" value="YES"/>   
+      <property name="args.rellinks" value="nofamily"/>   
+    </ant>
+  </target>
+
+</project>
diff --git a/samples/ant_sample/dita-cmd.xml b/samples/ant_sample/dita-cmd.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project basedir="." name="dita-cmd">
+  <description>Defines a dita-cmd macro you can use in your Ant builds.
+  See build-chm-pdf-hybrid.xml for usage.</description>
+
+  <property name="dita.dir" location="${basedir}/../../.."/>
+
+  <macrodef name="dita-cmd">
+    <attribute name="input"/>
+    <attribute name="format"/>
+    <attribute name="propertyfile"/>
+    <sequential>
+      <exec executable="${dita.dir}/bin/dita">
+        <arg line="-i @{input} -f @{format} -propertyfile @{propertyfile}"/>
+      </exec>
+    </sequential>
+  </macrodef>
+
+</project>
diff --git a/samples/css/style.css b/samples/css/style.css
@@ -94,3 +94,14 @@ a:hover {
 	float: left;
 }
 
+/* Inline Table of Contents */
+nav[role='toc'] {
+    float: right;
+    max-width: 200px;
+    font-size: small;
+    border-left: 1px solid #70A300;
+    margin-left: 1em;
+}
+nav[role='toc'] > ul {
+    margin-top: 0;
+}
diff --git a/samples/properties/chm.properties b/samples/properties/chm.properties
@@ -0,0 +1,3 @@
+output.dir = out/chm
+args.gen.task.lbl = YES
+args.breadcrumbs = yes
diff --git a/samples/properties/pdf.properties b/samples/properties/pdf.properties
@@ -0,0 +1,3 @@
+output.dir = out/pdf
+args.gen.task.lbl = YES
+args.rellinks = nofamily
diff --git a/samples/properties/sequence-html5.properties b/samples/properties/sequence-html5.properties
@@ -0,0 +1,7 @@
+args.gen.task.lbl = NO
+args.cssroot = ${args.input.dir}/css/
+args.css = style.css
+args.copycss = yes
+args.csspath = branding
+nav-toc = full
+args.xhtml.toc = toc
diff --git a/user-guide/creating-an-ant-build-script.dita b/user-guide/creating-an-ant-build-script.dita
@@ -32,11 +32,14 @@
         <cmd>Specify project information:</cmd>
         <substeps>
           <substep importance="optional">
-            <cmd>Set the value of the @name attribute to the name of your project.</cmd>
+            <cmd>Set the value of the <xmlatt>name</xmlatt> attribute to the name of your
+              project.</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>
+            <cmd>Set the value of the <xmlatt>default</xmlatt> 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>
@@ -49,7 +52,7 @@
         <cmd>Create the Ant target:</cmd>
         <substeps>
           <substep>
-            <cmd>Set the value of the @name attribute.</cmd>
+            <cmd>Set the value of the <xmlatt>name</xmlatt> attribute.</cmd>
           </substep>
           <substep>
             <cmd>Specify the value for the <parmname>args.input</parmname> property.</cmd>
@@ -64,34 +67,8 @@
       </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-ot"/>
-
-  &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:\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:\temp\out"/>
-      &lt;property name="transtype" value="pdf"/>
-    &lt;/ant>
-  &lt;/target>
-
-&lt;/project></codeblock></p>
+      <p>The following Ant build script generates CHM and PDF output for the sample DITA
+        maps.<codeblock><coderef href="../samples/ant_sample/build-chm-pdf.xml"/></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>
@@ -100,12 +77,14 @@
           <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>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 <xmlelement>link</xmlelement>
+        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>docsrc/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>
+    <postreq>Another resource for learning about Ant scripts are the files in the <filepath
+        conref="../resources/conref-task.dita#ID/samples-dir"/><filepath>/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>
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,8 @@ @@
     out/
     temp/
     build/
+    logs/
+    samples/properties/template.properties
     ## Autogenerated files created by the build process
     platform.ditaval
@@ Expand Down @@