From 4301c5467495cfec40f4256c038122044093566e Mon Sep 17 00:00:00 2001
From: Michael Kay <mike@saxonica.com>
Date: Wed, 22 Jan 2025 17:00:27 +0000
Subject: [PATCH] Apply post-acceptance changes from review

---
 .../src/xpath-datamodel.xml                   |  2 +-
 .../src/function-catalog.xml                  | 27 ++++++++++++++-----
 specifications/xquery-40/src/query-prolog.xml | 14 ++++------
 3 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/specifications/xpath-datamodel-40/src/xpath-datamodel.xml b/specifications/xpath-datamodel-40/src/xpath-datamodel.xml
index 1753e6acc..cbf407236 100644
--- a/specifications/xpath-datamodel-40/src/xpath-datamodel.xml
+++ b/specifications/xpath-datamodel-40/src/xpath-datamodel.xml
@@ -766,7 +766,7 @@ therefore can also be contained within sequences.</p>
     
     <p>The <code>dm:iterate-sequence</code> accessor calls the supplied <code>$action</code>
       function once for each item in <code>$input</code>, in order,
-      and returns the sequence concenation of the results. The <code>$action</code> function
+      and returns the sequence concatenation of the results. The <code>$action</code> function
       is called with two arguments. The first argument is an item in <code>$input</code>,
       and the second is the 1-based ordinal position of the item within <code>$input</code>.</p>
       
diff --git a/specifications/xpath-functions-40/src/function-catalog.xml b/specifications/xpath-functions-40/src/function-catalog.xml
index c84649fd4..9e3e0f5e2 100644
--- a/specifications/xpath-functions-40/src/function-catalog.xml
+++ b/specifications/xpath-functions-40/src/function-catalog.xml
@@ -23103,7 +23103,7 @@ xs:QName('xs:double')</eg></fos:result>
                   <!--<fos:option key="retain-order">
                      <fos:meaning>Determines the 
                         <xtermref spec="DM40" ref="dt-entry-order">entry order</xtermref> of the
-                        entries in the returned map, as well as the value of the map's 
+                        entries in the returned map, as well as the value of the map’s 
                         <xtermref spec="DM40" ref="dt-map-ordered">ordered</xtermref> property.
                      </fos:meaning>
                      <fos:type>xs:boolean</fos:type>
@@ -23147,7 +23147,7 @@ let $combine := fn($A as map(*), $B as map(*), $deduplicator as fn(*)) {
     else map:put($z, $k, $B($k))
   })
 }
-return fold-left($maps, dm:empty-map($options?ordering otherwise "undefined"),
+return fold-left($maps, {},
   $combine(?, ?, $duplicates-handler($options?duplicates otherwise "use-first"))
 )        
       </fos:equivalent>
@@ -23263,8 +23263,8 @@ return fold-left($maps, dm:empty-map($options?ordering otherwise "undefined"),
             </fos:test>
            
             <fos:test>
-               <fos:expression><eg>map:merge(({ "red": 0 }, { "green": 1}, { "blue": 2 }),
-    { "retain-order": true() } => map:keys()</eg></fos:expression>
+               <fos:expression><eg>map:merge(({ "red": 0 }, { "green": 1}, { "blue": 2 })) 
+                  => map:keys()</eg></fos:expression>
                <fos:result>"red", "green", "blue"</fos:result>
             </fos:test>
 
@@ -23319,7 +23319,7 @@ return fold-left($maps, dm:empty-map($options?ordering otherwise "undefined"),
             <!--<fos:option key="retain-order">
                <fos:meaning>Determines the 
                   <xtermref spec="DM40" ref="dt-entry-order">entry order</xtermref> of the
-                  entries in the returned map, as well as value of the map's
+                  entries in the returned map, as well as value of the map’s
                   <xtermref spec="DM40" ref="dt-map-ordered">ordered</xtermref> property.
                </fos:meaning>
                <fos:type>xs:boolean</fos:type>
@@ -23446,13 +23446,28 @@ map:build($input, map:get(?, 'key'), map:get(?, 'value'), $combine)
                <fos:postamble>The keys are returned in the order supplied.</fos:postamble>
             </fos:test>
             
+            <fos:test>
+               <fos:expression><eg>{ "red": 0, "green": 1, "blue": 2 }
+                  => map:pairs() => sort(keys := fn{ ?key }) => map:of-pairs()) 
+        => map:keys()</eg></fos:expression>
+               <fos:result>"blue", "green", "red"</fos:result>
+               <fos:postamble>Takes any map and produces a map with the same entries, but sorted by key.</fos:postamble>
+            </fos:test>
+            
             <fos:test>
                <fos:expression><eg>map:of-pairs((map:pair("red": 0), map:pair("green": 1), map:pair("blue": 2 )) 
         => map:put("yellow": -1) => map:keys()</eg></fos:expression>
                <fos:result>"red", "green", "blue", "yellow"</fos:result>
+               <fos:postamble>New entries are added at the end.</fos:postamble>
             </fos:test>
 
          </fos:example>
+         
+         <fos:example>
+            <p>The following expression takes an existing map and sorts its entries into key order:</p>
+            <eg>map:of-pairs(map:pairs($M) => sort(keys:=fn{?key}))</eg>
+            
+         </fos:example>
       </fos:examples>
       <fos:changes>
          <fos:change><p>New in 4.0</p></fos:change>
@@ -24644,7 +24659,7 @@ else map:put($map, $key, $action(()))
                   <!--<fos:option key="retain-order">
                      <fos:meaning>Determines the 
                         <xtermref spec="DM40" ref="dt-entry-order">entry order</xtermref>, of the
-                        entries in the returned map, and the value of the returned map's 
+                        entries in the returned map, and the value of the returned map’s 
                         <xtermref spec="DM40" ref="dt-map-ordered">ordered</xtermref> property.
                      </fos:meaning>
                      <fos:type>xs:boolean</fos:type>
diff --git a/specifications/xquery-40/src/query-prolog.xml b/specifications/xquery-40/src/query-prolog.xml
index 6fe55d247..fd607f0dc 100644
--- a/specifications/xquery-40/src/query-prolog.xml
+++ b/specifications/xquery-40/src/query-prolog.xml
@@ -2129,18 +2129,14 @@ local:depth(doc("partlist.xml"))
       <p>implicitly defines the function:</p>
        
        <eg>declare function cx:complex($r as xs:double, $i as xs:double := 0) as cx:complex {
-  map:merge((
-    { "r": $r },
-    { "i": $i }
-  ), { "retain-order" : true() })
+  map:merge(( { "r": $r }, { "i": $i } ))
 };
        </eg>
       
       <p>So the call <code>cx:complex(3, 2)</code> produces the value <code>{ "r": 3e0, "i": 2e0 }</code>,
       while the call <code>cx:complex(3)</code> produces the value <code>{ "r": 3e0, "i": 0e0 }</code></p>
       
-      <p>The resulting map has its <xtermref spec="DM40" ref="dt-map-ordered"/> property set to
-      <code>true</code>, so the order of entries corresponds
+      <p>The order of entries in the map corresponds
       to the order of field declarations in the record type. This means, for example, that when
       the map is serialized using the JSON output method, the order of entries in the output will
       correspond to the order of field declarations.</p>
@@ -2192,13 +2188,13 @@ local:depth(doc("partlist.xml"))
     { "last": $last },
     $options
   ),
-  { "duplicates": "use-first", "retain-order" : true() }
+  { "duplicates": "use-first" }
  };
       </eg>
       
       <p>The effect of the <code>duplicates</code> option here is that when two values are supplied for the same field,
       one as a direct argument in the function call and the other in the <code>options</code> map, the value supplied
-      as a direct argument is used in preference. The effect of the <code>ordering</code> option is that the resulting
+      as a direct argument is used in preference. The resulting
       map has an <xtermref spec="DM40" ref="dt-entry-order"/> in which the named fields appear first, in order of
       declaration, followed by the extension entries supplied in <code>$options</code>, retaining the 
         <xtermref spec="DM40" ref="dt-entry-order"/> of the <code>$options</code> map.</p>
@@ -2251,7 +2247,7 @@ local:depth(doc("partlist.xml"))
            <item><p>The optional final subexpression, if present, takes the form <code>$options</code>,
            where <code>$options</code> is the name allocated to the final parameter.</p></item>
            <item><p>The second argument in the call of the function <code>map:merge</code>
-           is the map <code>{ "duplicates": "use-first", "retain-order": true() }</code>.</p></item>
+           is the map <code>{ "duplicates": "use-first" }</code>.</p></item>
          </ulist>
        </item>