public inbox for [email protected]
help / color / mirror / Atom feedFrom: Karl O. Pinc <[email protected]>
To: Peter Smith <[email protected]>
Cc: Hayato Kuroda (Fujitsu) <[email protected]>
Cc: jian he <[email protected]>
Cc: Postgres hackers <[email protected]>
Cc: Tom Lane <[email protected]>
Subject: Re: [PGdocs] fix description for handling pf non-ASCII characters
Date: Wed, 27 Sep 2023 19:30:36 -0500
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAHut+PsfF5vTcgB3gTEkZPsbs-WGN4ENdKhz_G2YpMx3P8s02A@mail.gmail.com>
References: <TYAPR01MB586631D0961BF9C44893FAB1F523A@TYAPR01MB5866.jpnprd01.prod.outlook.com>
<CACJufxFkp8c0ap6YhyXRpVkjsB8pwZjWH9Hqc1tVF0aNWFRzFA@mail.gmail.com>
<TYAPR01MB58662BC412E1290FC3348973F525A@TYAPR01MB5866.jpnprd01.prod.outlook.com>
<CACJufxHn1=Phy6E=1PDO0AMXhP1S+XrP5Cioa_rynYpO7gC+=g@mail.gmail.com>
<TYAPR01MB5866CD2A823B196FBE7F19B9F52EA@TYAPR01MB5866.jpnprd01.prod.outlook.com>
<[email protected]>
<TYAPR01MB586607D53C42E59DBB00FD9AF5C3A@TYAPR01MB5866.jpnprd01.prod.outlook.com>
<[email protected]>
<TYAPR01MB58663EB061888B2715A39217F5C2A@TYAPR01MB5866.jpnprd01.prod.outlook.com>
<[email protected]>
<CAHut+PsfF5vTcgB3gTEkZPsbs-WGN4ENdKhz_G2YpMx3P8s02A@mail.gmail.com>
On Thu, 28 Sep 2023 09:49:03 +1000
Peter Smith <[email protected]> wrote:
> On Wed, Sep 27, 2023 at 11:59 PM Karl O. Pinc <[email protected]>
> wrote:
> >
> > On Wed, 27 Sep 2023 12:58:54 +0000
> > "Hayato Kuroda (Fujitsu)" <[email protected]> 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>.
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.)
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.
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.
Is this desireable?
Regards,
Karl <[email protected]>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
P.S. Hayato, it is good practice to cc everybody who has
replied to a thread. At least I think that's what I see,
it's not just people being lazy with reply-all. So I'm
adding Tom Lane back to the thread. He can tell us otherwise
if I'm wrong to add him back.
view thread (22+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
Subject: Re: [PGdocs] fix description for handling pf non-ASCII characters
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox