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

Dear Peter,

Thank you for reviewing!

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

Good point, my patch may be too much.

> Commit message.
> 
> 1.
> missing description

Added.
If we should use only printable ascii as a commit message, I can use '\x03'
instead of 'あああ'.

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

They seem good, but they conflict with Karl's comments.
I made three patches based on comments [1], could you check?

[1]:
https://www.postgresql.org/message-id/TYAPR01MB58663EB061888B2715A39217F5C2A%40TYAPR01MB5866.jpnprd01.prod.outlook.com

Best Regards,
Hayato Kuroda
FUJITSU LIMITED