From 182de3bf87f46f5c3f321a304ec2e39112a972b9 Mon Sep 17 00:00:00 2001
From: Jeff Davis <jeff@j-davis.com>
Date: Mon, 19 Feb 2024 15:21:39 -0800
Subject: [PATCH v18 1/6] Documentation update for Standard Collations.

---
 doc/src/sgml/charset.sgml | 79 ++++++++++++++++++++++++---------------
 1 file changed, 48 insertions(+), 31 deletions(-)

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 74783d148f..4422b0cc92 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -788,55 +788,72 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
     <title>Standard Collations</title>

    <para>
-    On all platforms, the collations named <literal>default</literal>,
-    <literal>C</literal>, and <literal>POSIX</literal> are available.  Additional
-    collations may be available depending on operating system support.
-    The <literal>default</literal> collation selects the <symbol>LC_COLLATE</symbol>
-    and <symbol>LC_CTYPE</symbol> values specified at database creation time.
-    The <literal>C</literal> and <literal>POSIX</literal> collations both specify
-    <quote>traditional C</quote> behavior, in which only the ASCII letters
-    <quote><literal>A</literal></quote> through <quote><literal>Z</literal></quote>
-    are treated as letters, and sorting is done strictly by character
-    code byte values.
-   </para>
-
-   <note>
-    <para>
-     The <literal>C</literal> and <literal>POSIX</literal> locales may behave
-     differently depending on the database encoding.
-    </para>
-   </note>
-
-   <para>
-    Additionally, two SQL standard collation names are available:
+    On all platforms, the collations following collations are supported:

     <variablelist>
      <varlistentry>
-      <term><literal>unicode</literal></term>
+      <term><literal>UNICODE</literal></term>
       <listitem>
        <para>
-        This collation sorts using the Unicode Collation Algorithm with the
-        Default Unicode Collation Element Table.  It is available in all
-        encodings.  ICU support is required to use this collation.  (This
-        collation has the same behavior as the ICU root locale; see <xref
+        This SQL standard collation sorts using the Unicode Collation
+        Algorithm with the Default Unicode Collation Element Table.  It is
+        available in all encodings.  ICU support is required to use this
+        collation, and behavior may change if Postgres is built with a
+        different version of ICU.  (This collation has the same behavior as
+        the ICU root locale; see <xref
         linkend="collation-managing-predefined-icu-und-x-icu"/>.)
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
-      <term><literal>ucs_basic</literal></term>
+      <term><literal>UCS_BASIC</literal></term>
       <listitem>
        <para>
-        This collation sorts by Unicode code point.  It is only available for
-        encoding <literal>UTF8</literal>.  (This collation has the same
-        behavior as the libc locale specification <literal>C</literal> in
-        <literal>UTF8</literal> encoding.)
+        This SQL standard collation sorts by Unicode code point.  Behavior is
+        efficient and stable across all versions.  Case mapping and pattern
+        matching behavior is based on simple ASCII semantics.  It is only
+        available for encoding <literal>UTF8</literal>.  (This collation has
+        the same behavior as the libc locale specification
+        <literal>C</literal> in <literal>UTF8</literal> encoding.)
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><literal>C</literal> (equivalent to <literal>POSIX</literal>)</term>
+      <listitem>
+       <para>
+        The <literal>C</literal> and <literal>POSIX</literal> collations both
+        specify <quote>traditional C</quote> behavior, in which only the ASCII
+        letters <quote><literal>A</literal></quote> through
+        <quote><literal>Z</literal></quote> are treated as letters, and
+        sorting is done strictly by character code byte values.  Case mapping
+        and pattern matching behavior is based on simple ASCII
+        semantics.  Behavior is efficient and stable across all versions for a
+        given database encoding, but behavior may vary between different
+        database encodings.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><literal>default</literal></term>
+      <listitem>
+       <para>
+        The <literal>default</literal> collation selects the locale specified
+        at database creation time.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
+
+   <para>
+    Additional collations may be available depending on operating system
+    support.  The efficiency and stability of these additional collations
+    depend on the collation provider, the provider version, and the locale.
+   </para>
   </sect3>

   <sect3 id="collation-managing-predefined">
-- 
2.34.1