From fa8618f99be8a56b4b65e19a578ead769fd9ad98 Mon Sep 17 00:00:00 2001
From: Roger Sheen <roger@infotexture.net>
Date: Thu, 5 Dec 2024 01:35:46 +0100
Subject: [PATCH] Edit configuration.properties for blank keyrefs

Signed-off-by: Roger Sheen <roger@infotexture.net>
---
 parameters/configuration-properties-file.dita |  8 ++++++--
 release-notes/index.dita                      | 13 +++++++------
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/parameters/configuration-properties-file.dita b/parameters/configuration-properties-file.dita
index cdd6ef9c..d984b97f 100644
--- 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
index 30f2c889..43e23358 100644
--- 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>