Re: [PGdocs] fix description for handling pf non-ASCII characters - Mailing list pgsql-hackers

Hi Kuroda-san.

Here are my review comments for your v3 patch.

TBH, I felt the new text descriptions deviated a bit too much from the
originals. IMO only quite a small tweak was needed, so my suggested
text in the comments below reflects that.

======
Commit message.

1.
missing description

======
src/sgml/config.sgml

2. application_name:

-        Only printable ASCII characters may be used in the
-        <varname>application_name</varname> value. Other characters will be
-        replaced with question marks (<literal>?</literal>).
+        Characters that are not printable ASCII, like <literal>\x03</literal>,
+        are replaced with the <productname>PostgreSQL</productname>
+        <link linkend="sql-syntax-strings-escape">C-style escaped
hexadecimal byte value</link>.

BEFORE
Other characters will be replaced with question marks (<literal>?</literal>).

SUGGESTION
Other characters will be replaced with <link
linkend="sql-syntax-strings-escape">C-style escaped hexadecimal byte
values</link>.

~~~

3. cluster_name:

-        build). Only printable ASCII characters may be used in the
-        <varname>cluster_name</varname> value. Other characters will be
-        replaced with question marks (<literal>?</literal>).  No name is shown
-        if this parameter is set to the empty string
<literal>''</literal> (which is
-        the default). This parameter can only be set at server start.
+        build).
+        Characters that are not printable ASCII, like <literal>\x03</literal>,
+        are replaced with the <productname>PostgreSQL</productname>
+        <link linkend="sql-syntax-strings-escape">C-style escaped
hexadecimal byte value</link>.
+        No name is shown if this parameter is set to the empty string
+        <literal>''</literal> (which is the default). This parameter can only
+        be set at server start.

<same as previous review comment #2>

======
src/sgml/postgres-fdw.sgml

4.
      <para>
       <varname>postgres_fdw.application_name</varname> can be any string
-      of any length and contain even non-ASCII characters.  However when
-      it's passed to and used as <varname>application_name</varname>
+      of any length and contain even characters that are not printable ASCII.
+      However when it's passed to and used as
<varname>application_name</varname>
       in a foreign server, note that it will be truncated to less than
       <symbol>NAMEDATALEN</symbol> characters and anything other than
-      printable ASCII characters will be replaced with question
-      marks (<literal>?</literal>).
+      printable ASCII characters are replaced with the
<productname>PostgreSQL</productname>
+      <link linkend="sql-syntax-strings-escape">C-style escaped
hexadecimal byte value</link>.
       See <xref linkend="guc-application-name"/> for details.
      </para>

~

AFAICT the first change wasn't necessary.

~

As for the 2nd change:

BEFORE
... and anything other than printable ASCII characters will be
replaced with question marks (<literal>?</literal>).

SUGGESTION
... and anything other than printable ASCII characters will be
replaced with <link linkend="sql-syntax-strings-escape">C-style
escaped hexadecimal byte values</link>.

======
Kind Regards,
Peter Smith.
Fujitsu Australia