From b65431ca5e12a475ba7cf68afb63edb070c2ce08 Mon Sep 17 00:00:00 2001
From: Thomas Munro
Date: Fri, 7 May 2021 21:47:08 +1200
Subject: Doc: Update notes about libc collation versions.

The per-index collation version tracking feature was reverted, but we
still have the ability to ask Windows (352f6f2d) and FreeBSD
(ca051d8b) for collation versions to store in pg_collation.collversion.
So, from the reverted patch, take a few words of documentation about
libc on all three supported OSes to replace the pre-existing note that
mentioned only glibc.

Discussion: https://postgr.es/m/CA%2BhUKGLhj5t1fcjqAu8iD9B3ixJtsTNqyCCD4V0aTO9kAKAjjA%40mail.gmail.com
---
 doc/src/sgml/ref/alter_collation.sgml | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml
index af9ff2867b7..9bcb91e8ff9 100644
--- a/doc/src/sgml/ref/alter_collation.sgml
+++ b/doc/src/sgml/ref/alter_collation.sgml
@@ -129,12 +129,24 @@ HINT:  Rebuild all objects affected by this collation and run ALTER COLLATION pg
    correctly.
   </para>
   <para>
-   When using collations provided by <literal>libc</literal> and
-   <productname>PostgreSQL</productname> was built with the GNU C library, the
-   C library's version is used as a collation version.  Since collation
-   definitions typically change only with GNU C library releases, this provides
-   some defense against corruption, but it is not completely reliable.
+   When using collations provided by <literal>libc</literal>, version
+   information is recorded on systems using the GNU C library (most Linux
+   systems), FreeBSD and Windows.
   </para>
+  <note>
+   <para>
+    When using the GNU C library for collations, the C library's version
+    is used as a proxy for the collation version.  Many Linux distributions
+    change collation definitions only when upgrading the C library, but this
+    approach is imperfect as maintainers are free to back-port newer
+    collation definitions to older C library releases.
+   </para>
+   <para>
+    When using Windows for collations, version information is only available
+    for collations defined with BCP 47 language tags such as
+    <literal>en-US</literal>. 
+   </para>
+  </note>
   <para>
    Currently, there is no version tracking for the database default collation.
   </para>
-- 
cgit v1.2.3