Minor changes following review of diff rendition

specifications/xpath-datamodel-40/src/xpath-datamodel.xml

@@ -1511,7 +1511,7 @@ must equal the function’s arity.
   <changes>
     <change issue="1335" date="2024-07-20">Constructors are added, and the single accessor function
     is now an iterator over the key/value pairs in the map.</change>
-    <change issue="564" PR="1609" date="2024-11-25">Ordered maps are introduced.</change>
+    <change issue="1651" PR="1703" date="2025-01-14">Ordered maps are introduced.</change>
   </changes>
 
 <p><termdef term="map item" id="dt-map-item">A <term>map item</term>

specifications/xpath-functions-40/src/function-catalog.xml

@@ -12795,7 +12795,7 @@ else QName("", $value)</eg>
             instance of <code>xs:NCName</code>. For the default namespace, which has no prefix, the key is
             the zero-length string as an instance of <code>xs:string</code>.</p>
 
-         <p>The ordering of the returned map is <termref def="implementation-dependent"/>.</p>
+         <p>The order of entries in the returned map is <termref def="implementation-dependent"/>.</p>
 
       </fos:rules>
       <fos:notes>
@@ -16521,8 +16521,7 @@ declare function equal-strings(
                      </olist>
                   </item>
                </olist>
-               <note><p>It is not required that both maps have the same <code>ordering</code> property, 
-                  nor that the order of entries matches.</p></note>
+               <note><p>It is not required that the order of entries in the two maps should be the same.</p></note>
              </item>
             <item>
                <p>All the following conditions are true:</p>
@@ -23339,8 +23338,7 @@ map:build($input, map:get(?, 'key'), map:get(?, 'value'), $combine)
 
       <fos:notes>
          <p>If the input is an empty sequence, the result is an empty map.</p>
-         <p>Except when <code>ordering=sorted</code>, 
-            there is no requirement that the supplied key-value pairs should have the same or compatible
+         <p>There is no requirement that the supplied key-value pairs should have the same or compatible
             types. The type of a map (for example <code>map(xs:integer, xs:string)</code>) is
             descriptive of the entries it currently contains, but is not a constraint on how the map
             may be combined with other maps.</p>
@@ -24068,7 +24066,7 @@ declare function map:find($input as item()*,
          </fos:example>
       </fos:examples>
       <fos:changes>
-         <fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
+         <fos:change  issue="1651" PR="1703" date="2025-01-14"><p>Enhanced to allow for ordered maps.</p></fos:change>
       </fos:changes>
    </fos:function>
 
@@ -24138,7 +24136,7 @@ declare function map:find($input as item()*,
          <p>There is no requirement that the type of <code>$key</code> and <code>$value</code> be consistent with the types
          of any existing keys and values in the supplied map.</p>
 
-         <p>With an ordered map, you can force the new entry to go at the end of the sequence by calling
+         <p>It is possible to force the new entry to go at the end of the sequence by calling
          <code>map:remove</code> before calling <code>map:put</code>.</p>
 
       </fos:notes>
@@ -24175,7 +24173,7 @@ declare function map:find($input as item()*,
          </fos:example>
       </fos:examples>
       <fos:changes>
-         <fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
+         <fos:change  issue="1651" PR="1703" date="2025-01-14"><p>Enhanced to allow for ordered maps.</p></fos:change>
       </fos:changes>
    </fos:function>
 
@@ -24356,7 +24354,7 @@ map:filter($map, fn($k, $v) { not(some($keys, atomic-equal($k, ?))) })
          </fos:example>
       </fos:examples>
       <fos:changes>
-         <fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
+         <fos:change  issue="1651" PR="1703" date="2025-01-14"><p>Enhanced to allow for ordered maps.</p></fos:change>
       </fos:changes>
    </fos:function>
    <fos:function name="for-each" prefix="map">
@@ -24440,7 +24438,7 @@ return <box>{
          </fos:example>
       </fos:examples>
       <fos:changes>
-         <fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
+         <fos:change  issue="1651" PR="1703" date="2025-01-14"><p>Enhanced to allow for ordered maps.</p></fos:change>
       </fos:changes>
    </fos:function>
 
@@ -24509,7 +24507,7 @@ map:for-each($map, fn($key, $value) {
          <fos:change issue="1171" PR="1182" date="2024-05-07">
             <p>The <code>$predicate</code> callback function may return an empty sequence (meaning <code>false</code>).</p>
          </fos:change>
-         <fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
+         <fos:change  issue="1651" PR="1703" date="2025-01-14"><p>Enhanced to allow for ordered maps.</p></fos:change>
       </fos:changes>
    </fos:function>
 
@@ -27398,7 +27396,7 @@ return document {
                </fos:values>
             </fos:option>
 
-            <fos:option key="retain-order">
+            <!--<fos:option key="retain-order">
                <fos:meaning>Determines whether maps resulting from parsing of JSON objects should retain the input order.</fos:meaning>
                <fos:type>xs:boolean</fos:type>
                <fos:default>false</fos:default>
@@ -27410,7 +27408,7 @@ return document {
                      <xtermref spec="DM40" ref="dt-entry-order">entry order</xtermref> retains the order
                   of entries in the input.</fos:value>
                </fos:values>
-            </fos:option>
+            </fos:option>-->
 
             <fos:option key="escape">
                <fos:meaning>Determines whether special characters are represented in the XDM output in backslash-escaped form.</fos:meaning>
@@ -27540,7 +27538,7 @@ return document {
                      <code>{ "x": 2, "y": 5 }</code>.</p>
                <p>If duplicate keys are encountered in a JSON <emph>object</emph>, they are handled
                   as determined by the <code>duplicates</code> option defined above.</p>
-               <p>The order of entries is retained if the <code>retain-order</code> option is set to true.</p>
+               <p>The order of entries is retained.</p>
             </item>
             <item>
                <p>A JSON <emph>array</emph> is transformed to an array whose members are the result of converting
@@ -27698,8 +27696,8 @@ return document {
             specification gave the default value as <code>true</code>, but this appears to have been an error,
             since it was inconsistent with examples given in the specification and with tests in the test suite.</p>
          </fos:change>
-         <fos:change issue="564" PR="1609" date="2024-11-27">
-            <p>An option is provided to retain the order of entries in maps.</p>
+         <fos:change issue="1651" PR="1703" date="2025-01-14">
+            <p>The order of entries in maps is retained.</p>
          </fos:change>
       </fos:changes>
    </fos:function>

specifications/xpath-functions-40/src/xpath-functions.xml

@@ -7662,7 +7662,7 @@ return <table>
             <head>Ordering of Maps</head>
 
             <changes>
-               <change issue="564" PR="1609" date="2024-11-25">Ordered maps are introduced.</change>
+               <change issue="1651" PR="1703" date="2025-01-14">Ordered maps are introduced.</change>
             </changes>
 
             <p>In 4.0, the entries in a map are ordered. The <xtermref spec="DM40" ref="dt-entry-order">entry order</xtermref> of a map
@@ -7774,7 +7774,7 @@ return <table>
             <head>Formal Specification of Maps</head>
             <p>The XDM data model (<bibref ref="xpath-datamodel-40"/>) defines three primitive operations on maps:</p>
             <ulist>
-               <item><p><code>dm:empty-map</code> constructs an empty map with a given ordering property.</p></item>
+               <item><p><code>dm:empty-map</code> constructs an empty map.</p></item>
                <item><p><code>dm:map-put</code> adds or replaces an entry in a map.</p></item>
                <item><p><code>dm:iterate-map</code> applies a supplied function to every entry in a map.</p></item>
             </ulist>
@@ -7786,7 +7786,7 @@ return <table>
             to be specified by reference to this function library, without risk of circularity.</p>
 
             <p>There is one exception to this rule: for convenience, the notation <code>{}</code> is used to represent
-            an empty map, in preference to a call on <code>dm:empty-map(ordering := 'undefined')</code>.</p>
+            an empty map, in preference to a call on <code>dm:empty-map()</code>.</p>
 
             <p>The formal equivalents are not intended to provide a realistic way of implementating the
             functions (in particular, any real implementation might be expected to implement <function>map:get</function>

specifications/xquery-40/src/expressions.xml

@@ -19194,7 +19194,7 @@ processing with JSON processing.</p>
             <head>Maps</head>
 
             <changes>
-               <change issue="564" PR="1609" date="2024-11-25">Ordered maps are introduced.</change>
+               <change issue="1651" PR="1703" date="2025-01-14">Ordered maps are introduced.</change>
             </changes>
 
             <p>
@@ -19219,18 +19219,11 @@ processing with JSON processing.</p>
             see <xspecref spec="FO40" ref="maps"/>.</p>
 
             <note>
-               <p>Maps in &language; have a property called <xtermref spec="DM40" ref="dt-map-ordered"/>,
-               which takes the value <code>true</code> or <code>false</code>; a map
-                  is accordingly said to be <term>ordered</term> or <term>unordered</term>.
+               <p>Maps in &language; are ordered.
                   The effect of this property is explained 
-                  in <xspecref spec="DM40" ref="map-items"/>. In summary:</p>
-               <ulist>
-                  <item><p>In an unordered map, the order of entries
-                  in the map is <termref def="dt-implementation-dependent"/>; it may, for example,
-                  be the result of a randomized hashing algorithm.</p></item>
-                  <item><p>In an ordered map, the order of entries is predictable
-                  and depends on the order in which they were added to the map.</p></item>
-               </ulist>
+                  in <xspecref spec="DM40" ref="map-items"/>. 
+                  In an ordered map, the order of entries is predictable
+                  and depends on the order in which they were added to the map.</p>
             </note>
 
             <div4 id="id-map-constructors">
@@ -19242,7 +19235,7 @@ processing with JSON processing.</p>
                      <code>map { 0: false(), 1: true() }</code> can now be written <code>{ 0: false(), 1: true() }</code>,
                      provided it is used in a context where this creates no ambiguity.
                   </change>
-                  <change issue="564" PR="1609" date="2024-11-25">The order of key-value
+                  <change issue="1651" PR="1703" date="2025-01-14">The order of key-value
                      pairs in the map constructor is now retained in the constructed map.</change>
                </changes>
 
@@ -20578,13 +20571,12 @@ return $array?[count(.) ge 2]</eg>
                for each entry in the map, with the context value set to an item of type
                <code>record(key as xs:anyAtomicType, value as item()*)</code>, in which the <code>key</code>
                and <code>value</code> fields represent the key and value of the map entry. 
-               The context position is the position of the entry in the map (in an arbitrary ordering),
+               The context position is the position of the entry in the map 
+               (in <xtermref spec="DM40" ref="dt-entry-order"/>),
                and the context size is the number of entries in the map. The result
                of the expression is a map containing those entries of the input map for which
                the <termref def="dt-predicate-truth-value"/> of the <code><var>FILTER</var></code> expression is true.
-               The <code>ordered</code> property of the result is the same as the <code>ordered</code>
-               property of the input map, and in the case of an ordered map, the relative order of 
-               entries in the result retains the relative order of entries in the input.
+               The relative order of entries in the result retains the relative order of entries in the input.
             </p>
 
             <p>For example, the following expression:</p>
@@ -20597,11 +20589,9 @@ return $map?[?key ge 2]</eg>
             <eg>{ 2: "beta", 3: "gamma" }</eg>
 
             <note>
-               <p>Filtering of maps based on numeric positions is not generally useful when
-                  the map is unordered, because the order of entries is unpredictable; but it is available 
-                  in the interests of orthogonality.</p>
-               <p>With an ordered map, a filter expression such as <code>$map?[last()-1, last()]</code>
-                  might be used to return the last two entries.</p>
+               <p>A filter expression such as <code>$map?[last()-1, last()]</code>
+                  might be used to return the last two entries of a map in
+                  <xtermref spec="DM40" ref="dt-entry-order"/>.</p>
             </note>
          </div3>
 

specifications/xslt-40/src/xslt.xml

@@ -35560,9 +35560,9 @@ the same group, and the-->
                   now raises error XTSE3185 (rather than XTSE3280) if both a <code>select</code>
                   attribute and a sequence constructor are present.
                </change>
-
-
-               <change issue="564" PR="1609" date="2024-11-25">Ordered maps are introduced.</change>
+               <change issue="1651" PR="1703" date="2025-01-14">
+                  Ordered maps are introduced.
+               </change>
              </changes>
 
             <p>Two instructions are added to XSLT to facilitate the construction of maps.</p>

specifications/xslt-xquery-serialization-40/src/xslt-xquery-serialization.xml

@@ -3408,6 +3408,9 @@ is described in <specref ref="serdm"/>.</p>
     <change issue="1471" date="2024-10-15">
       Added the <code>json-lines</code> parameter for JSON serialization.
     </change>
+    <change issue="1651" PR="1703" date="2025-01-14">
+      The serialization of maps retains the order of entries.
+    </change>
   </changes>
 
   <p>The JSON output method serializes the <termref diff="chg" at="2023-11-01" def="dt-input-tree"/>
@@ -3727,6 +3730,12 @@ according to the <bibref ref="JSON-LINES"/> format and as described in <specref
 
 <div1 id="adaptive-output">
 <head>Adaptive Output Method</head>
+
+  <changes>
+    <change issue="1651" PR="1703" date="2025-01-14">
+      The serialization of maps retains the order of entries.
+    </change>
+  </changes>
 
   <p>The Adaptive output method serializes the <termref diff="chg" at="2023-11-01" def="dt-input-tree"/> 
 into a human readable form for the purposes of debugging query results.