Edit configuration.properties for blank keyrefs

Signed-off-by: Roger Sheen <[email protected]>
dita-ot · Dec 5, 2024 · fa8618f · fa8618f
1 parent d7dd4f5
commit fa8618f
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 8 deletions.
diff --git a/parameters/configuration-properties-file.dita b/parameters/configuration-properties-file.dita
@@ -76,8 +76,12 @@
         <plentry id="compatibility-keyref-treat-blank-as-empty">
           <pt><parmname>compatibility.keyref.treat-blank-as-empty</parmname></pt>
           <pd>
-            <p>Enables compatibility mode that incorrectly processes key references that have only whitespace
-            content.</p>
+            <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>

diff --git a/release-notes/index.dita b/release-notes/index.dita
@@ -67,12 +67,13 @@
             <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 keyreffing elements 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.
-              A new <codeph>compatibility.keyref.treat-blank-as-empty</codeph> property can be used to switch off the
-            incorrect behavior. The fix will be enabled by default in the next minor or major version.
+          <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>