From 34078f1348e667715a821b34bc460b5f820d8a6b Mon Sep 17 00:00:00 2001
From: Michael Kay <mike@saxonica.com>
Date: Fri, 3 Jan 2025 20:05:52 +0000
Subject: [PATCH] Expound on the capabilities of collations

---
 .../src/function-catalog.xml                  | 20 +++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/specifications/xpath-functions-40/src/function-catalog.xml b/specifications/xpath-functions-40/src/function-catalog.xml
index 3b44fb539..198583d80 100644
--- a/specifications/xpath-functions-40/src/function-catalog.xml
+++ b/specifications/xpath-functions-40/src/function-catalog.xml
@@ -24828,7 +24828,7 @@ return map:build($titles/title, fn($title) { $title/ix })
       <fos:signatures>
          <fos:proto name="collation-available" return-type="xs:boolean">
             <fos:arg name="collation" type="xs:string"/>
-            <fos:arg name="usage" type="enum('equality', 'sort', 'substring')*" 
+            <fos:arg name="usage" type="enum('compare', 'key', 'substring')*" 
                                   default="()"/>
          </fos:proto>
       </fos:signatures>
@@ -24838,7 +24838,8 @@ return map:build($titles/title, fn($title) { $title/ix })
          <fos:property>focus-independent</fos:property>
       </fos:properties>
       <fos:summary>
-         <p>Asks whether a collation URI is recognized by the implementation.</p>
+         <p>Asks whether a collation URI is recognized by the implementation,
+            and whether it has required properties.</p>
       </fos:summary>
       <fos:rules>
          <p>The first argument is a candidate collation URI.</p>
@@ -24847,12 +24848,12 @@ return map:build($titles/title, fn($title) { $title/ix })
             is a sequence containing zero or more of the following:</p>
          
          <ulist>
-            <item><p><code>equality</code> indicates that the intended purpose of the collation
-            URI is to compare strings for equality, for example in functions such as 
-            <function>fn:index-of</function> or <function>fn:deep-equal</function>.</p></item>
-            <item><p><code>sort</code> indicates that the intended purpose of the collation
-            URI is to sort or compare different strings in a collating sequence, for example
-            in functions such as <function>fn:sort</function> or <function>fn:max</function>.</p></item>
+            <item><p><code>compare</code> indicates that the intended purpose of the collation
+            URI is to compare strings for equality or ordering, for example in functions such as 
+            <function>fn:index-of</function>, <function>fn:deep-equal</function>, 
+               <function>fn:compare</function>, and <function>fn:sort</function>.</p></item>
+            <item><p><code>key</code> indicates that the intended purpose of the collation
+            URI is to obtain collation keys for strings using the <function>fn:collation-key</function>.</p></item>
             <item><p><code>substring</code> indicates that the intended purpose of the collation
             URI is to establish whether one string is a substring of another, for example
             in functions such as <function>fn:contains</function> or <function>fn:starts-with</function>.</p></item>
@@ -24986,6 +24987,9 @@ return map:build($titles/title, fn($title) { $title/ix })
          where <code>$collation</code> allows the collation to be chosen dynamically.</p>
          <p>Note that <code>xs:base64Binary</code> becomes an ordered type
          in XPath 3.1, making binary collation keys possible.</p>
+         
+         <p>The <function>fn:collation-available</function> can be used to ask whether a particular
+         collation is capable of delivering collation keys.</p>
 
       </fos:notes>
       <fos:examples>