Dear Karl, Thank you for reviewing!
> A related thing that's nice to have is to limit the line > length of the documentation source to 80 characters or less. > 79 is probably best. Since the source text around your patch > conforms to this convention you should also. IIUC it is not hard limit, but I followed this. > 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? > Also, based on the comments in the > patch which changed the system's behavior, I believe that > your patch updates all the relevant places in the documentation. Thanks. Actually, I think it should be backpatched to PG16 because the commit was done last year. I will make the patch for it after deciding the explanation. > > I now think that you should consider another change to your wording. > Instead of starting with "Characters that are not printable ASCII ..." > consider writing "The bytes of the string which are not printable ASCII > ...". Notice above that characters (e.g. あ) generate output for > each non-ASCII byte (e.g. \xe3\x81\x82). So my thought is that > the docs should be talking about bytes. > > For the last hunk you'd change around "anything". Write: > "... it will be truncated to less than NAMEDATALEN characters and > the bytes of the string which are not printable ASCII characters ...". > 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". [1]: https://www.postgresql.org/message-id/CAHut%2BPvEbKC8ABA_daX-XPNOTFzuAmHGhjPj%3DtPZYQskRHECOg%40mail.gmail.com Best Regards, Hayato Kuroda FUJITSU LIMITED
From c3a2c68fd74bce14af6df7c773317d496cf75209 Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hay...@fujitsu.com>
Date: Wed, 27 Sep 2023 07:31:07 +0000
Subject: [PATCH v32] Fix description for handling of non-printable ASCII
characters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
45b1a67a changed the behavior when characters that are not printable ASCII were
used for three configuration parameters (application_name, cluster_name, and
postgres_fdw.application_name), but it was not documented. This commit fixes
that.
PG15 and prior:
```
postgres=# SET application_name TO 'ããã';
SET
postgres=# SHOW application_name ;
application_name
------------------
?????????
(1 row)
```
PG16 and later:
```
postgres=# SET application_name TO 'ããã';
SET
postgres=# SHOW application_name ;
application_name
--------------------------------------
\xe3\x81\x82\xe3\x81\x82\xe3\x81\x82
(1 row)
```
---
doc/src/sgml/config.sgml | 17 +++++++++++------
doc/src/sgml/postgres-fdw.sgml | 7 ++++---
2 files changed, 15 insertions(+), 9 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 38684af5b1..587bdf3d72 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -6893,8 +6893,10 @@ local0.* /var/log/postgresql
and included in CSV log entries. It can also be included in regular
log entries via the <xref linkend="guc-log-line-prefix"/> parameter.
Only printable ASCII characters may be used in the
- <varname>application_name</varname> value. Other characters will be
- replaced with question marks (<literal>?</literal>).
+ <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>.
</para>
</listitem>
</varlistentry>
@@ -7890,10 +7892,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH
csv;
The name can be any string of less
than <symbol>NAMEDATALEN</symbol> characters (64 characters in a
standard
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.
+ <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>.
+ 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.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 5062d712e7..9894d61a98 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -1067,9 +1067,10 @@ postgres=# SELECT postgres_fdw_disconnect_all();
of any length and contain even non-ASCII characters. 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>).
+ <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>.
See <xref linkend="guc-application-name"/> for details.
</para>
--
2.27.0
v3-0001-Fix-description-for-handling-of-non-printable-AS.patch
Description: v3-0001-Fix-description-for-handling-of-non-printable-AS.patch
From 5f4dc139a3a401d22793e49d9a51caa00ba2ecad Mon Sep 17 00:00:00 2001
From: Hayato Kuroda <kuroda.hay...@fujitsu.com>
Date: Wed, 27 Sep 2023 07:31:07 +0000
Subject: [PATCH v3] Fix description for handling of non-printable ASCII
characters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
45b1a67a changed the behavior when characters that are not printable ASCII were
used for three configuration parameters (application_name, cluster_name, and
postgres_fdw.application_name), but it was not documented. This commit fixes
that.
PG15 and prior:
```
postgres=# SET application_name TO 'ããã';
SET
postgres=# SHOW application_name ;
application_name
------------------
?????????
(1 row)
```
PG16 and later:
```
postgres=# SET application_name TO 'ããã';
SET
postgres=# SHOW application_name ;
application_name
--------------------------------------
\xe3\x81\x82\xe3\x81\x82\xe3\x81\x82
(1 row)
```
---
doc/src/sgml/config.sgml | 17 +++++++++++------
doc/src/sgml/postgres-fdw.sgml | 7 ++++---
2 files changed, 15 insertions(+), 9 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 38684af5b1..fdd93002bc 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -6893,8 +6893,10 @@ local0.* /var/log/postgresql
and included in CSV log entries. It can also be included in regular
log entries via the <xref linkend="guc-log-line-prefix"/> parameter.
Only printable ASCII characters may be used in the
- <varname>application_name</varname> value. Other characters will be
- replaced with question marks (<literal>?</literal>).
+ <varname>application_name</varname> value.
+ Other characters will be replaced with
+ <link linkend="sql-syntax-strings-escape">C-style escaped hexadecimal
+ byte values</link>.
</para>
</listitem>
</varlistentry>
@@ -7890,10 +7892,13 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH
csv;
The name can be any string of less
than <symbol>NAMEDATALEN</symbol> characters (64 characters in a
standard
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.
+ <varname>cluster_name</varname> value.
+ Other characters will be replaced with
+ <link linkend="sql-syntax-strings-escape">C-style escaped hexadecimal
+ byte values</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.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 5062d712e7..522f736144 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -1067,9 +1067,10 @@ postgres=# SELECT postgres_fdw_disconnect_all();
of any length and contain even non-ASCII characters. 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>).
+ <symbol>NAMEDATALEN</symbol> characters and anything other than printable
+ ASCII characters will be replaced with <link
+ linkend="sql-syntax-strings-escape">C-style escaped hexadecimal byte
+ values</link>.
See <xref linkend="guc-application-name"/> for details.
</para>
--
2.27.0
