Feedback-ID: ie0a040ee:Fastmail
Message-ID: <9beecdf7-e8c8-4eab-adc7-fa225c2feefd@eisentraut.org>
Date: Tue, 14 May 2024 09:38:07 +0200
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: Explanations not clear
To: Jeff Davis <pgsql@j-davis.com>, florian.murat.koch@gmail.com,
 pgsql-docs@lists.postgresql.org
References: <171501838010.704.2474442958031349608@wrigleys.postgresql.org>
 <dbdfcb5f-282c-4426-b67e-56f4d1588a36@eisentraut.org>
 <20d80bfbbec3874d430691fec37465fb7c4cb277.camel@j-davis.com>
Content-Language: en-US
From: Peter Eisentraut <peter@eisentraut.org>
In-Reply-To: <20d80bfbbec3874d430691fec37465fb7c4cb277.camel@j-davis.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
Archived-At: 
 <https://www.postgresql.org/message-id/9beecdf7-e8c8-4eab-adc7-fa225c2feefd%40eisentraut.org>
Precedence: bulk

On 13.05.24 21:10, Jeff Davis wrote:
> On Wed, 2024-05-08 at 08:52 +0200, Peter Eisentraut wrote:
>>> I created a collation specifying the ks-level3 setting and with
>>> deterministic set to false. But when I compare "a_b" to "a-b" with
>>> this
>>> collation I get false. According to the table 24.1 it should yield
>>> true.
>>> Only after adding ka-shifted this comparison becomes true. The
>>> interactions
>>> of the different options are not very clear.
>>
>> I think table 24.1 is somewhat incorrect in the sense that
>> punctuation
>> is only level 4 if you use ka-shifted, otherwise it's level 1.  This
>> should perhaps be clarified.
> 
> One option is to just include 3 levels (plus "identic") in the table,
> and then later document that ka-shifted creates a fourth level and
> moves punctuation character differences into that level. That explains
> the mechanism but detracts from the examples.
> 
> Another option is to say that all the examples in the table are using
> ka-shifted for illustration purposes. I like this option, but it's a
> bit awkward because it refers to something that hasn't been explained
> yet. It's also only relevant for the 'x-y' = 'x_y' example, which might
> be slightly confusing.
> 
> Thoughts?

Maybe with a forward reference in a footnote, like this:

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index daf671e6205..10c12adf634 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -1320,7 +1320,7 @@ <title>ICU Collation Levels</title>
          </row>
          <row>
           <entry>level4</entry>
-         <entry>Punctuation</entry>
+         <entry>Punctuation<footnote><para>only with 
<literal>ka-shifted</literal>; see <xref 
linkend="icu-collation-settings-table"/></para></footnote></entry>
           <entry><literal>true</literal></entry>
           <entry><literal>true</literal></entry>
           <entry><literal>false</literal></entry>