Re: [PGdocs] fix description for handling pf non-ASCII characters

On Wed, Sep 27, 2023 at 11:59 PM Karl O. Pinc <kop@karlpinc.com> wrote:
>
> On Wed, 27 Sep 2023 12:58:54 +0000
> "Hayato Kuroda (Fujitsu)" <kuroda.hayato@fujitsu.com> wrote:
>
> > > Should the committer be interested, your patch applies cleanly
> > > and the docs build as expected.
> >
> > Yeah, but cfbot accepted previous version. Did you have anything in
> > your mind?
>
> No.  I'm letting the committer know everything I've checked
> so that they can decide what they want to check.
>
> > Hmm, what you said looked right. But as Peter pointed out [1], the
> > fix seems too much. So I attached three version of patches. How do
> > you think? For me, type C is best.
> >
> > A. A patch which completely follows your comments. The name is
> > "v3-0001-...patch". Cfbot tests it.
> > B. A patch which completely follows Peter's comments [1]. The name is
> > "Peter_v3-....txt".
> > C. A patch which follows both comments. Based on
> > b, but some comments (Don't use the future tense, "Other
> > characters"->"The bytes of other characters"...) were picked. The
> > name is "Both_v3-....txt".
>
> I also like C.  Fewer words is better.  So long
> as nothing is left unsaid fewer words make for clarity.
>
> However, in the last hunk, "of other than" does not read well.
> Instead of writing
> "and the bytes of other than printable ASCII characters"
> you want "and the bytes that are not printable ASCII characters".
> That would be my suggestion.
>

I also prefer Option C, but...

~~~

+        <varname>application_name</varname> value.
+        The bytes of other characters are replaced with
+        <link linkend="sql-syntax-strings-escape">C-style escaped hexadecimal
+        byte values</link>.

V

+        <varname>cluster_name</varname> value.
+        The bytes of other characters are replaced with
+        <link linkend="sql-syntax-strings-escape">C-style escaped hexadecimal
+        byte values</link>.

V

+      <symbol>NAMEDATALEN</symbol> characters and the bytes of other than
+      printable ASCII characters are replaced with <link
+      linkend="sql-syntax-strings-escape">C-style escaped hexadecimal byte
+      values</link>.


IIUC all of these 3 places can have exactly the same wording change
(e.g. like Karl's last suggestion [1]).

SUGGESTION
Any bytes that are not printable ASCII characters are replaced with
<link linkend="sql-syntax-strings-escape">C-style escaped hexadecimal
byte values</link>.

======
[1] https://www.postgresql.org/message-id/20230927085924.4198c3d2%40slate.karlpinc.com

Kind Regards,
Peter Smith.
Fujitsu Australia