🚧 Draft 4.2.4 docs

parameters/ant-parameters-details.dita

@@ -121,6 +121,16 @@
           </plentry>
           <plentry id="args.rellinks">
             <pt><parmname>args.rellinks</parmname></pt>
+            <pd conaction="pushreplace" conref="parameters-base.dita#base/args.rellinks.desc"> Specifies which related
+              links to include in the output. The following values are supported:
+              <ul>
+                <li><option>none</option> – No links are included.</li>
+                <li><option>all</option> – All links are included.</li>
+                <li><option>noparent</option> – Ancestor and parent links are not included.</li>
+                <li><option>nofamily</option> – Parent, ancestor, child, descendant, sibling, next, previous, and cousin
+                  links are not included.</li>
+              </ul>
+            </pd>
             <pd conaction="mark" conref="parameters-base.dita#base/args.rellinks.desc"/>
             <pd conaction="pushafter">
               <p>For PDF output, the default value is <option>nofamily</option>. Other formats include all link roles
@@ -132,7 +142,11 @@
                 <indexterm>HTML5
                   <indexterm>related links</indexterm>
                   <indexterm>args.rellinks</indexterm></indexterm>
-              </p></pd>
+              </p>
+              <note type="tip">For more precise control over related links output, set the internal Ant property
+                <xref keyref="internal-ant-properties">
+                  <codeph>include.rellinks</codeph></xref> and specify which link roles to include.</note>
+            </pd>
           </plentry>
           <plentry id="args.resources">
             <pt><parmname>args.resources</parmname></pt>

parameters/configuration-properties-file.dita

@@ -73,6 +73,18 @@
         configuration in the <codeph>dost-configuration.jar</codeph> file when the plug-in integration process runs. The
         following properties are typically set in this file:</p>
       <parml>
+        <plentry id="compatibility-keyref-treat-blank-as-empty">
+          <pt><parmname>compatibility.keyref.treat-blank-as-empty</parmname></pt>
+          <pd>
+            <p>When set to <codeph>true</codeph>, this property enables a compatibility mode that processes key
+              references that contain only whitespace characters like earlier versions of DITA-OT (prior to version
+              4.2.4). This behavior is not correct according to the DITA specification, but this setting ensures that
+              existing content that relies on this behavior will be processed in the same way as in earlier versions.
+              Set this property to <codeph>false</codeph> to skip these references as intended in the DITA
+              specification.</p>
+            <note type="warning">This property can only be set in
+                <filepath>configuration.properties</filepath>.</note></pd>
+        </plentry>
         <plentry id="default-cascade">
           <pt><parmname>default.cascade</parmname></pt>
           <pd>

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 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

@@ -34,9 +34,12 @@
   </prolog>
   <refbody>
     <example>
-      <p>For example, if you always use the same rendering engine to produce PDF output for all of your projects, you
-        could create a <filepath>local.properties</filepath> file in the root directory of your DITA-OT installation to
-        set the <parmname>pdf.formatter</parmname> parameter and additional options for the XSL processor:</p>
+      <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>
+      <p>If you always use the same rendering engine to produce PDF output for all of your projects, you could create a
+          <filepath>local.properties</filepath> file in the root directory of your DITA-OT installation to set the
+          <parmname>pdf.formatter</parmname> parameter and additional options for the XSL processor:</p>
       <codeblock
         outputclass="language-properties normalize-space show-line-numbers show-whitespace"
       ># Use RenderX XEP Engine for PDF output

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

@@ -26,14 +26,72 @@
     </refbody>
   </reference>
 
-  <reference id="v4.2.3" outputclass="mark">
+  <reference id="v4.2.4" outputclass="mark">
     <title>DITA-OT <keyword keyref="maintenance-version"/>
-      <ph outputclass="small text-muted">released May 5, 2024</ph>
+      <!--<ph outputclass="small text-muted">released mmmm D, yyyy</ph>-->
     </title>
     <refbody>
       <section id="bugs">
         <p>DITA Open Toolkit <keyword keyref="maintenance-version"/> is a maintenance release that includes the
           following bug fixes.</p>
+        <!-- https://github.com/dita-ot/dita-ot/issues?q=milestone%3A4.2.4+is%3Aclosed+label%3Abug+sort%3Acreated-asc -->
+        <ul>
+          <li id="4525">On Windows, earlier versions of the <cmdname>dita.bat</cmdname> command failed when options were
+            specified with straight quotation marks (<codeph>" "</codeph>). The batch script syntax has been updated to
+            enable delayed expansion, which ensures that quotation marks are parsed correctly.
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4525" format="html" scope="external">#4525</xref>,
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4545" format="html" scope="external">#4545</xref>
+          </li>
+          <li id="4526">The bundled <tm trademark="Apache Commons IO" tmtype="tm">Apache Commons IO</tm> library has
+            been upgraded to version 2.14.0, which includes security updates to mitigate the vulnerability described in
+            <xref
+              href="https://nvd.nist.gov/vuln/detail/CVE-2024-47554"
+              format="html"
+              scope="external"
+            >CVE-2024-47554</xref>, a possible denial of service attack on untrusted input to
+              <codeph>XmlStreamReader</codeph>.
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4526" format="html" scope="external">#4526</xref>
+          </li>
+          <li id="4532">In previous releases, the HTML5 transformation did not provide a mechanism for creating HTML5
+            metadata from <xmlelement>data</xmlelement>, <xmlelement>data-about</xmlelement>, and
+              <xmlelement>resourceid</xmlelement> elements. In this release, no metadata is created for these elements
+            by default, but placeholders have been added to the <codeph>getMeta</codeph> processing mode to allow custom
+            plug-ins to override the placeholders and generate metadata for these elements as needed.
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4532" format="html" scope="external">#4532</xref>,
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4533" format="html" scope="external">#4533</xref>
+          </li>
+          <li id="4540">Earlier versions did not generate links in HTML output when software elements such as
+              <xmlelement>cmdname</xmlelement> and <xmlelement>msgnum</xmlelement> were used in key references.
+            These elements are now processed as keywords to ensure that links are created as expected.
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4540" format="html" scope="external">#4540</xref>,
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4547" format="html" scope="external">#4547</xref>
+          </li>
+          <li id="4543">Previous versions of DITA-OT incorrectly processed key references that contain only whitespace
+            characters, where the DITA specification requires them to be skipped. This bug has been fixed, but the fix
+            is not yet enabled. The incorrect behavior is retained for backwards compatibility to ensure that existing
+            content that relies on this behavior will be processed in the same way as in earlier versions.
+              A new <codeph>compatibility.keyref.treat-blank-as-empty</codeph> property can be set in
+            <xref keyref="configuration-properties-file">configuration.properties</xref> to switch off the incorrect
+            behavior. The fix will be enabled by default in the next minor or major version.
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4543" format="html" scope="external">#4543</xref>,
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4544" format="html" scope="external">#4544</xref>
+          </li>
+          <li id="4551">The order of arguments in the <cmdname>dita</cmdname> command scripts has been adjusted to allow
+            the content of the <codeph>ANT_OPTS</codeph> environment variable to override CLI parameters.
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4545" format="html" scope="external">#4545</xref>,
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4551" format="html" scope="external">#4551</xref>
+          </li>
+        </ul>
+      </section>
+    </refbody>
+  </reference>
+
+  <reference id="v4.2.3">
+    <title>DITA-OT 4.2.3 <ph outputclass="small text-muted">released May 5, 2024</ph>
+    </title>
+    <refbody>
+      <section id="bugs">
+        <p>DITA Open Toolkit 4.2.3 is a maintenance release that includes the following bug fixes.</p>
         <!-- https://github.com/dita-ot/dita-ot/issues?q=milestone%3A4.2.3+is%3Aclosed+label%3Abug+sort%3Acreated-asc -->
         <ul>
           <li id="4449">DITA-OT 4.2.2 included a regression bug that caused the map-first pre-processing routine to fail
@@ -46,7 +104,7 @@
       </section>
     </refbody>
   </reference>
-  
+
   <reference id="v4.2.2">
     <title>DITA-OT 4.2.2
       <ph outputclass="small text-muted">released March 24, 2024</ph>
@@ -171,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
@@ -487,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/key-definitions.ditamap

@@ -26,7 +26,7 @@
   <keydef keys="maintenance-version">
     <topicmeta>
       <keywords>
-        <keyword>4.2.3</keyword>
+        <keyword>4.2.4</keyword>
       </keywords>
     </topicmeta>
   </keydef>

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"/>

samples/docker/Dockerfile

@@ -1,5 +1,5 @@
 # Use the latest DITA-OT image ↓ as parent:
-FROM ghcr.io/dita-ot/dita-ot:4.2.3
+FROM ghcr.io/dita-ot/dita-ot:4.2.4
 
 # Install a custom plug-in from a remote location:
 RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/master.zip