Documentation update for Standard Collations.

Correct out-of-date text that said the "default" collation is always
based on LC_COLLATE and LC_CTYPE.

Also reformat into a list to make it easier to understand and compare
the available collations, and briefly document the stability
characteristics of each one.

Discussion: https://postgr.es/m/4a69d067374d2f6bfb66f5bfb2ab9a020493d49f[email protected]

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 74783d148fef221ec0b87d2a8997b6930192e1bf..4fc143025ef5440cf60b42cc9682316907fe4d09 100644 (file)
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -788,37 +788,19 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
     Standard Collations
 
    
-    On all platforms, the collations named default,
-    C, and POSIX are available.  Additional
-    collations may be available depending on operating system support.
-    The default collation selects the LC_COLLATE
-    and LC_CTYPE values specified at database creation time.
-    The C and POSIX collations both specify
-    traditional C behavior, in which only the ASCII letters
-    A through Z
-    are treated as letters, and sorting is done strictly by character
-    code byte values.
-   
-
-   
-    
-     The C and POSIX locales may behave
-     differently depending on the database encoding.
-    
-   
-
-   
-    Additionally, two SQL standard collation names are available:
+    On all platforms, the following collations are supported:
 
     
      
       unicode
       
        
-        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 
+        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 
         linkend="collation-managing-predefined-icu-und-x-icu"/>.)
        
       
@@ -828,15 +810,51 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
       ucs_basic
       
        
-        This collation sorts by Unicode code point.  It is only available for
-        encoding UTF8.  (This collation has the same
+        This SQL standard collation sorts using the Unicode code point values
+        rather than natural language order, and only the ASCII letters
+        A through
+        Z are treated as letters.  The
+        behavior is efficient and stable across all versions.  Only available
+        for encoding UTF8.  (This collation has the same
         behavior as the libc locale specification C in
         UTF8 encoding.)
        
       
      
+
+     
+      C (equivalent to POSIX)
+      
+       
+        The C and POSIX collations are
+        based on traditional C behavior.  They sort by byte
+        values rather than natural language order, and only the ASCII letters
+        A through
+        Z are treated as letters.  The
+        behavior is efficient and stable across all versions for a given
+        database encoding, but behavior may vary between different database
+        encodings.
+       
+      
+     
+
+     
+      default
+      
+       
+        The default collation selects the locale specified
+        at database creation time.
+       
+      
+     
     
    
+
+   
+    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.
+