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

From: "Hayato Kuroda (Fujitsu)" <kuroda(dot)hayato(at)fujitsu(dot)com>
To: "'Karl O(dot) Pinc'" <kop(at)karlpinc(dot)com>, Peter Smith <smithpb2250(at)gmail(dot)com>
Cc: jian he <jian(dot)universality(at)gmail(dot)com>, Postgres hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Subject: RE: [PGdocs] fix description for handling pf non-ASCII characters
Date: 2023-09-28 02:48:28
Message-ID: TYAPR01MB5866DD962CA4FC03E338C6BBF5C1A@TYAPR01MB5866.jpnprd01.prod.outlook.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Dear Karl,

Thank you for giving comments! PSA new version.
I attached two patches - one is for HEAD, and another one is for REL_16_STABLE
branch. As shown below, PG16 has the same behavior.

```
psql (16beta3)
Type "help" for help.

postgres=# SET application_name TO 'あああ';
SET
postgres=# SHOW application_name ;
application_name
--------------------------------------
\xe3\x81\x82\xe3\x81\x82\xe3\x81\x82
(1 row)
```

> > > > 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.

Okay, basically I used C.

> > >
> > > 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>.
>
> I don't see the utility in having exactly the same phrase everywhere,
> especially since the last hunk is modifying the end of a long
> sentence. (Apologies if I'm mis-reading what Peter wrote above.)

Right, here we cannot use exactly the same sentence.

>
> I like short sentences. So I prefer "The bytes of other characters"
> rather than "Any bytes that are not printable ASCII characters"
> for the first 2 hunks. In context I don't see the need to repeat
> the whole "printable ASCII characters" part that appears in the
> preceding sentence of both hunks. "Other" is clear, IMHO.

Based on the suggestion [1], I removed the word "byte".
(Sorry, but a comment from senior members has higher priority)

>
> But because I like short sentences I now think that it's a good
> idea to break the long sentence of the last hunk into two.
> Add a period and use the Peter's SUGGESTION above as the
> text for the second sentence.

Right, the sentence is separated into two.

[1]: https://www.postgresql.org/message-id/803569.1695863971%40sss.pgh.pa.us

Best Regards,
Hayato Kuroda
FUJITSU LIMITED

Attachment Content-Type Size
REL_16_v4-0001-Fix-description-for-handling-of-non-printable-ASC.patch application/octet-stream 3.8 KB
v4-0001-Fix-description-for-handling-of-non-printable-ASC.patch application/octet-stream 3.8 KB

In response to

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Hayato Kuroda (Fujitsu) 2023-09-28 02:50:55 RE: [PGdocs] fix description for handling pf non-ASCII characters
Previous Message Andrey Lepikhov 2023-09-28 02:32:46 Re: RFC: Logging plan of the running query