Add topic on runtime configuration file: .ditaotrc

Signed-off-by: Roger Sheen <[email protected]>

parameters/configuration-properties.dita

@@ -35,6 +35,8 @@
         <li>Any property passed to Ant from the command line with <parmname>-Dproperty</parmname> or
             <parmname>--property</parmname>=<option>value</option></li>
         <li>A custom property file passed with <parmname>--propertyfile</parmname></li>
+        <li>A <filepath>.ditaotrc</filepath> configuration file in the current directory or any ancestor directory, in
+          the user’s home directory, or in the root directory of the DITA-OT installation</li>
         <li>A <filepath>local.properties</filepath> file in the root directory of the DITA-OT installation</li>
         <li>The <filepath>lib/org.dita.dost.platform/plugin.properties</filepath> file</li>
         <li>The <filepath>configuration.properties</filepath> file</li>
@@ -43,7 +45,7 @@
         property are ignored.</p>
       <p>You can use this mechanism to override DITA-OT default settings for your environment by passing parameters to
         the <cmdname>dita</cmdname> command with <parmname>--property</parmname>=<option>value</option>, or using
-        entries in <filepath>.properties</filepath> files.</p>
+        entries in runtime configurations or <filepath>.properties</filepath> files.</p>
     </section>
   </refbody>
 </reference>

parameters/dot-ditaotrc-file.dita

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
+<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
+<reference id="ditaotrc">
+  <title>The <filepath>.ditaotrc</filepath> configuration file</title>
+  <titlealts>
+    <navtitle><filepath>.ditaotrc</filepath></navtitle>
+  </titlealts>
+  <shortdesc>As of DITA-OT 4.2, new files can be used to store DITA-OT runtime configurations in multiple places to
+    support fine-grained configuration layers.</shortdesc>
+  <prolog>
+    <metadata>
+      <keywords>
+        <indexterm>files
+          <indexterm>.ditaotrc</indexterm></indexterm>
+        <indexterm><filepath>.ditaotrc</filepath> file</indexterm>
+      </keywords>
+    </metadata>
+  </prolog>
+  <refbody>
+    <section>
+      <p>DITA-OT now looks for <filepath>.ditaotrc</filepath> configuration files in the current directory or any
+        ancestor directory first, then in the user’s home directory, and finally in the root directory of the DITA-OT
+        installation. These files are read in order and combined with the contents of the
+          <filepath>local.properties</filepath> file in the toolkit directory.</p>
+      <p>The first occurrence of a property takes precedence. This approach can be used to define multiple layers of
+        configuration, so personal defaults that apply to multiple projects can be stored in the home folder, with local
+        overrides in project folders.</p>
+    </section>
+    <example>For example, if the current directory includes a <filepath>.ditaotrc</filepath> file that sets
+      <codeblock outputclass="language-properties">pdf.formatter=fop</codeblock> and the user’s home directory has a
+        <filepath>.ditaotrc</filepath> file with the following content,
+      <codeblock outputclass="language-properties">pdf.formatter=xep
+args.grammar.cache=no</codeblock> DITA-OT will be run as if the following options were set on the command line: 
+      <codeblock outputclass="language-bash">--pdf.formatter=fop --args.grammar.cache=no</codeblock>
+      <note type="tip">As of DITA-OT 4.2, any configurations in
+        <xref keyref="local-properties-file"><filepath>local.properties</filepath> files</xref> should be migrated to
+          <filepath>.ditaotrc</filepath> files.</note>
+    </example>
+  </refbody>
+</reference>

parameters/local-properties-file.dita

@@ -58,6 +58,9 @@ axf.cmd=C:\\Program Files\\Antenna House\\AHFormatterV62</codeblock>
     <section>
       <note>This file can only be used to set Ant property values that can be passed as argument parameters to the
         command line. The DITA-OT Java code does not read this file.</note>
+      <note type="attention">The <filepath>local.properties</filepath> file is still supported for backwards
+        compatibility, but as of DITA-OT 4.2, any local configurations should be migrated to
+        <xref keyref="dot-ditaotrc-file"><filepath>.ditaotrc</filepath> configuration files</xref>.</note>
     </section>
   </refbody>
 </reference>

parameters/parameters.ditamap

@@ -20,6 +20,7 @@
     <topicref keyref="ant-parameters-details" keys="parameters-push" processing-role="resource-only" toc="no"/>
   </topicref>
   <topicref keyref="configuration-properties">
+    <topicref keyref="dot-ditaotrc-file"/>
     <topicref keyref="local-properties-file"/>
     <topicref keyref="plugin-properties-file"/>
     <topicref keyref="configuration-properties-file"/>

release-notes/index.dita

@@ -229,9 +229,10 @@
       </section>
 
       <section id="ditaotrc">
-        <title>New configuration file</title>
-        <p>A new <filepath>.ditaotrc</filepath> configuration file can be used to store DITA-OT runtime configurations
-          in multiple places.</p>
+        <title>New runtime configurations</title>
+        <p>New
+          <xref keyref="dot-ditaotrc-file"><filepath>.ditaotrc</filepath> configuration files</xref> can be used to
+          store DITA-OT runtime configurations in multiple places.</p>
         <p>DITA-OT now looks for this file in the current directory or any ancestor directory first, then in the user’s
           home directory, and finally in the root directory of the DITA-OT installation. These files are read in order
           and combined with the contents of the <filepath>local.properties</filepath> file in the toolkit directory. The
@@ -545,6 +546,8 @@
             <xref keyref="error-messages"/></li>
           <li>
             <xref keyref="migrating-to-4.2"/></li>
+          <li>
+            <xref keyref="dot-ditaotrc-file"/></li>
         </ul>
         <p>For additional information on documentation issues resolved in DITA Open Toolkit Release <keyword
             keyref="release"

resources/source-files.ditamap

@@ -50,6 +50,7 @@
   <keydef keys="dita2pdf" href="../topics/dita2pdf.dita"/>
   <keydef keys="dita2xhtml" href="../topics/dita2xhtml.dita"/>
   <keydef keys="docs-dita-features" href="../reference/docs-dita-features.dita"/>
+  <keydef keys="dot-ditaotrc-file" href="../parameters/dot-ditaotrc-file.dita"/>
   <keydef keys="eclipsehelp-processing" href="../reference/eclipsehelp-processing.dita"/>
   <keydef keys="enabling-debug-mode" href="../topics/enabling-debug-mode.dita"/>
   <keydef keys="error-messages messages" href="../topics/error-messages.xml"/>