From 9de49cad0cbe22a2c0aebb48a529aa2bc9b1afdb Mon Sep 17 00:00:00 2001
From: Roger Sheen <roger@infotexture.net>
Date: Sun, 1 Oct 2023 00:10:33 +0200
Subject: [PATCH] Group & describe map-first preprocessing issues

Signed-off-by: Roger Sheen <roger@infotexture.net>
---
 release-notes/index.dita | 69 +++++++++++++++++++++++-----------------
 1 file changed, 40 insertions(+), 29 deletions(-)

diff --git a/release-notes/index.dita b/release-notes/index.dita
index d487438c..9d822a21 100644
--- a/release-notes/index.dita
+++ b/release-notes/index.dita
@@ -36,20 +36,46 @@
           following bug fixes.</p>
         <ul>
           <!-- https://github.com/dita-ot/dita-ot/issues?q=milestone%3A4.1.2+is%3Aclosed+sort%3Acreated-asc -->
-          <li id="2420">Can no longer use conref in keydef metadata [DOT 2.3]
-            <xref href="https://github.com/dita-ot/dita-ot/issues/2420" format="html" scope="external">#2420</xref>
-          </li>
-          <li id="3007">NullPointerException in AbstractReaderModule
-            <xref href="https://github.com/dita-ot/dita-ot/issues/3007" format="html" scope="external">#3007</xref>
-          </li>
-          <li id="3281">Preprocess2 does not report validation error
-            <xref href="https://github.com/dita-ot/dita-ot/issues/3281" format="html" scope="external">#3281</xref>
-          </li>
-          <li id="3446">PDF - Stage "preprocess2" does not report not resolved conrefs
-            <xref href="https://github.com/dita-ot/dita-ot/issues/3446" format="html" scope="external">#3446</xref>
-          </li>
-          <li id="3514">preprocess2 is not compatible with chunk=to-content
-            <xref href="https://github.com/dita-ot/dita-ot/issues/3514" format="html" scope="external">#3514</xref>
+          <li id="4237">Various issues in map-first preprocessing have been resolved in this release.
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4237" format="html" scope="external">#4237</xref>
+            <ul>
+              <li id="2420">Earlier versions failed to expand content references that were specified in key definitions.
+                In <codeph>preprocess2</codeph>, content references are now expanded before key references to ensure
+                that all topics are available when the map is processed.
+                <xref href="https://github.com/dita-ot/dita-ot/issues/2420" format="html" scope="external">#2420</xref>,
+                <xref href="https://github.com/dita-ot/dita-ot/issues/4258" format="html" scope="external">#4258</xref>,
+                <xref href="https://github.com/dita-ot/dita-ot/issues/4261" format="html" scope="external">#4261</xref>
+              </li>
+              <li id="3007">In earlier versions, key references to duplicate topics created via <xmlatt>copy-to</xmlatt>
+                attributes caused builds to fail. This issue was initially resolved for the original preprocessing
+                routine in DITA-OT 3.1.1. The original source information is now also correctly recorded for copy-to
+                targets in <codeph>preprocess2</codeph>, allowing builds to continue.
+                <xref href="https://github.com/dita-ot/dita-ot/issues/3007" format="html" scope="external">#3007</xref>,
+                <xref href="https://github.com/dita-ot/dita-ot/issues/3015" format="html" scope="external">#3015</xref>
+              </li>
+              <li id="3281">Earlier versions failed to catch certain validation errors in <codeph>preprocess2</codeph>.
+                Map-first preprocessing has been updated to validate files correctly.
+                <xref href="https://github.com/dita-ot/dita-ot/issues/3281" format="html" scope="external">#3281</xref>
+              </li>
+              <li id="3446">Earlier versions of map-first preprocessing failed to report unresolved content references
+                to topics that were not referenced in the map. In the past, this issue could be avoided by adding
+                content reference targets to the map with the <xmlatt>processing-role</xmlatt> attribute set to
+                  <codeph>resource-only</codeph>, but this workaround is no longer necessary. Unresolved references
+                should now be reported even if the target topics are not referenced in the map.
+                <xref href="https://github.com/dita-ot/dita-ot/issues/3446" format="html" scope="external">#3446</xref>
+              </li>
+              <li id="3514">Earlier versions of map-first preprocessing set incorrect values for the
+                  <xmlpi>path2project</xmlpi>, <xmlpi>path2project-uri</xmlpi>, and <xmlpi>path2rootmap-uri</xmlpi>
+                processing instructions. In <codeph>preprocess2</codeph>, they are now set with correct values that
+                match the original preprocess output.
+                <xref href="https://github.com/dita-ot/dita-ot/issues/3514" format="html" scope="external">#3514</xref>,
+                <xref href="https://github.com/dita-ot/dita-ot/issues/4252" format="html" scope="external">#4252</xref>
+              </li>
+              <li id="4268">The map-first preprocessing test code has been simplified to use the same expected output
+                for the original preprocessing routines and <codeph>preprocess2</codeph>.
+                <xref href="https://github.com/dita-ot/dita-ot/issues/4268" format="html" scope="external">#4268</xref>
+              </li>
+            </ul>
           </li>
           <li id="3546">@keyref isn't resolved when contained in @conref
             <xref href="https://github.com/dita-ot/dita-ot/issues/3546" format="html" scope="external">#3546</xref>
@@ -60,12 +86,6 @@
           <li id="4064">Chunk to content on DITA Map fails when the DITA Map has spaces in file name
             <xref href="https://github.com/dita-ot/dita-ot/issues/4064" format="html" scope="external">#4064</xref>
           </li>
-          <li id="4237">Fix preprocess2 bugs
-            <xref href="https://github.com/dita-ot/dita-ot/issues/4237" format="html" scope="external">#4237</xref>
-          </li>
-          <li id="4252">Fix PI generation in preprocess2
-            <xref href="https://github.com/dita-ot/dita-ot/issues/4252" format="html" scope="external">#4252</xref>
-          </li>
           <li id="4254">HTML5: Teletype output contains inline style attributes
             <xref href="https://github.com/dita-ot/dita-ot/issues/4254" format="html" scope="external">#4254</xref>
           </li>
@@ -75,24 +95,15 @@
           <li id="4257">Fix getting file name from URI with space in file name #4064
             <xref href="https://github.com/dita-ot/dita-ot/issues/4257" format="html" scope="external">#4257</xref>
           </li>
-          <li id="4258">Fix conref in keydef value in preprocess2
-            <xref href="https://github.com/dita-ot/dita-ot/issues/4258" format="html" scope="external">#4258</xref>
-          </li>
           <li id="4259">Improve preprocess unit tests
             <xref href="https://github.com/dita-ot/dita-ot/issues/4259" format="html" scope="external">#4259</xref>
           </li>
-          <li id="4261">Process map conref during preprocess2 topic stage before keyref
-            <xref href="https://github.com/dita-ot/dita-ot/issues/4261" format="html" scope="external">#4261</xref>
-          </li>
           <li id="4264">Add preprocess integration test for subject scheme
             <xref href="https://github.com/dita-ot/dita-ot/issues/4264" format="html" scope="external">#4264</xref>
           </li>
           <li id="4267">Move teletype styling to Sass partial
             <xref href="https://github.com/dita-ot/dita-ot/issues/4267" format="html" scope="external">#4267</xref>
           </li>
-          <li id="4268">Clean preprocess2 tests
-            <xref href="https://github.com/dita-ot/dita-ot/issues/4268" format="html" scope="external">#4268</xref>
-          </li>
           <li id="4269">Footnote in <xmlelement>title</xmlelement>, footnote text appears in <xmlelement
             >xref</xmlelement>
             <xref href="https://github.com/dita-ot/dita-ot/issues/4269" format="html" scope="external">#4269</xref>