From f8ce9ed220b5edd8ba751706bbcdbcc5b64be66e Mon Sep 17 00:00:00 2001
From: Alexander Korotkov <akorotkov@postgresql.org>
Date: Tue, 26 Aug 2025 12:49:44 +0300
Subject: Further clarify documentation for the initcap function

This is a follow-up for commit c2c2c7e225.  It further clarifies the
following in the initcap function documentation:

 * Document that title case is used for digraphs in specific locales,
 * Reference particular ICU function used,
 * Add note about the purpose of the function.

Discussion: https://postgr.es/m/804cc10ef95d4d3b298e76b181fd9437%40postgrespro.ru
Author: Oleg Tselebrovskiy <o.tselebrovskiy@postgrespro.ru>
Co-authored-by: Alexander Korotkov <aekorotkov@gmail.com>
Reviewed-by: Jeff Davis <pgsql@j-davis.com>
Reviewed-by: Peter Eisentraut <peter@eisentraut.org>
---
 doc/src/sgml/func/func-string.sgml | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/func/func-string.sgml b/doc/src/sgml/func/func-string.sgml
index 3eec93eb339..01cc94c234e 100644
--- a/doc/src/sgml/func/func-string.sgml
+++ b/doc/src/sgml/func/func-string.sgml
@@ -693,12 +693,21 @@
         <returnvalue>text</returnvalue>
        </para>
        <para>
-        Converts the first letter of each word to upper case and the
-        rest to lower case. When using the <literal>libc</literal> locale
-        provider, words are sequences of alphanumeric characters separated
-        by non-alphanumeric characters; when using the ICU locale provider,
-        words are separated according to
-        <ulink url="https://www.unicode.org/reports/tr29/#Word_Boundaries">Unicode Standard Annex #29</ulink>.
+        Converts the first letter of each word to upper case (or title case
+        if the letter is a digraph and locale is <literal>ICU</literal> or
+        <literal>builtin</literal> <literal>PG_UNICODE_FAST</literal>)
+        and the rest to lower case. When using the <literal>libc</literal> or
+        <literal>builtin</literal> locale provider, words are sequences of
+        alphanumeric characters separated by non-alphanumeric characters;
+        when using the ICU locale provider, words are separated according to
+        <ulink url="https://unicode-org.github.io/icu-docs/apidoc/dev/icu4c/ustring_8h.html#a47602e2c2012d77ee91908b9bbfdc063">u_strToTitle ICU function</ulink>.
+       </para>
+       <para>
+        This function is primarily used for convenient
+        display, and the specific result should not be relied upon because of
+        the differences between locale providers and between different
+        ICU versions. If specific word boundary rules are desired,
+        it is recommended to write a custom function.
        </para>
        <para>
         <literal>initcap('hi THOMAS')</literal>
-- 
cgit v1.2.3