collation-icu-rules.patch

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index ed84465996..05d2a61cba 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -1497,6 +1497,53 @@ SELECT 'x-y' = 'x_y' COLLATE level4; -- false
     </para>
    </sect3>
 
+   <sect3 id="icu-tailoring-rules">
+     <title>Tailoring rules</title>
+     <para>
+       The order of individual code points may be changed with tailoring rules, whose syntax is detailed at <ulink url="https://unicode-org.github.io/icu/userguide/collation/customization/"></ulink>.
+       As an example, the following code sets up a collation named <literal>ebcdic</literal> with rules to sort US-ASCII characters in the order of the <ulink url="https://en.wikipedia.org/wiki/EBCDIC">EBCDIC encoding.</ulink>
+<programlisting>
+<![CDATA[
+DO $body$
+DECLARE
+  -- list ASCII letters in the order of the EBCDIC encoding
+  codepage_37 constant text := ' .<(+|&!$*);-/,%_>?`:#@''="'
+    'abcdefghijklmnopqr~stuvwxyz^[]{ABCDEFGHI}JKLMNOPQR'
+    '\STUVWXYZ0123456789';
+  rules text;
+BEGIN
+  -- format the list as a valid set of rules
+  WITH list AS
+   (SELECT CASE WHEN ch<>'''' THEN ch ELSE '\''' END AS c,
+    CASE WHEN ch !~ '[''A-Za-z0-9]' THEN '''' ELSE '' END as q,
+    n
+    FROM regexp_split_to_table(codepage_37, '') WITH ORDINALITY AS x(ch,n)
+    )
+  SELECT '&'||array_to_string(array_agg(concat(q,c,q) order by n),'<')
+    FROM list INTO rules;
+
+  -- create the collation with the rules adequately formatted and quoted
+  EXECUTE format('CREATE COLLATION ebcdic (PROVIDER = ''icu'', LOCALE = ''und'''
+    ', rules = %L)', rules);
+END
+$body$ LANGUAGE plpgsql;
+]]>
+
+SELECT c FROM (VALUES('a'),('b'),('A'),('B'),('1'),('2'),('!'),('^')) AS x(c)
+ORDER BY c COLLATE "ebcdic";
+ c
+---
+ !
+ a
+ b
+ ^
+ A
+ B
+ 1
+ 2
+</programlisting>
+     </para>
+   </sect3>
    <sect3 id="icu-external-references">
     <title>External References for ICU</title>
     <para>
@@ -1528,6 +1575,11 @@ SELECT 'x-y' = 'x_y' COLLATE level4; -- false
        <ulink url="https://unicode-org.github.io/icu/userguide/locale/"></ulink>
       </para>
      </listitem>
+     <listitem>
+      <para>
+       <ulink url="https://unicode-org.github.io/icu/userguide/collation/customization/">Collation customization (tailoring rules)</ulink>
+      </para>
+     </listitem>
      <listitem>
       <para>
        <ulink url="https://unicode-org.github.io/icu/userguide/collation/api.html"></ulink>
diff --git a/doc/src/sgml/ref/create_collation.sgml b/doc/src/sgml/ref/create_collation.sgml
index b86a9bbb9c..5003ae7d38 100644
--- a/doc/src/sgml/ref/create_collation.sgml
+++ b/doc/src/sgml/ref/create_collation.sgml
@@ -165,9 +165,8 @@ CREATE COLLATION [ IF NOT EXISTS ] <replaceable>name</replaceable> FROM <replace
      <listitem>
       <para>
        Specifies additional collation rules to customize the behavior of the
-       collation.  This is supported for ICU only.  See <ulink
-       url="https://unicode-org.github.io/icu/userguide/collation/customization/"/>
-       for details on the syntax.
+       collation.  This is supported for ICU only.
+       See <xref linkend="icu-tailoring-rules"/> for details.
       </para>
      </listitem>
     </varlistentry>
@@ -261,8 +260,8 @@ CREATE COLLATION german_phonebook (provider = icu, locale = 'de-u-co-phonebk');
    <quote>V</quote>, but is treated as a secondary difference similar to an
    accent.  Rules like this are contained in the locale definitions of some
    languages.  (Of course, if a locale definition already contains the desired
-   rules, then they don't need to be specified again explicitly.)  See the ICU
-   documentation for further details and examples on the rules syntax.
+   rules, then they don't need to be specified again explicitly.)  See
+   <xref linkend="icu-tailoring-rules"/> for further details and examples on the rules syntax.
   </para>
 
   <para>
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index b2c8aef1ad..ce7317f81b 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -232,9 +232,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable>
        <para>
         Specifies additional collation rules to customize the behavior of the
         default collation of this database.  This is supported for ICU only.
-        See <ulink
-        url="https://unicode-org.github.io/icu/userguide/collation/customization/"/>
-        for details on the syntax.
+        See <xref linkend="icu-tailoring-rules"/> for details.
        </para>
       </listitem>
      </varlistentry>