Re: Explanations not clear

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>