[PATCH] document

Started by Ian Lawrence Barwickover 4 years ago8 messages

barwick@gmail.com

over 4 years ago

1 attachment(s)

The description for "pg_database" [1]https://www.postgresql.org/docs/current/catalog-pg-database.html mentions the function
"pg_encoding_to_char()", but this is not described anywhere in the docs. Given
that that it (and the corresponding "pg_char_to_encoding()") have been around
since 7.0 [2]https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=5eb1d0deb15f2b7cd0051bef12f3e091516c723b, it's probably not a burning issue, but it seems not entirely
unreasonable to add short descriptions for both (and link from "pg_conversion"
while we're at it); see attached patch. "System Catalog Information Functions"
seems the most logical place to put these.

[1]: https://www.postgresql.org/docs/current/catalog-pg-database.html
[2]: https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=5eb1d0deb15f2b7cd0051bef12f3e091516c723b

Will add to the next commitfest.

Regards

Ian Barwick

--
EnterpriseDB: https://www.enterprisedb.com

Attachments:

doc-pg-char-encoding-funcs.v1.patchtext/x-patch; charset=US-ASCII; name=doc-pg-char-encoding-funcs.v1.patchDownload

commit b8617bc6e6ca551ce51d661de10e6d3830e80694
Author: Ian Barwick <barwick@gmail.com>
Date:   Wed Jul 14 12:44:58 2021 +0900

    document pg_encoding_to_char() and pg_char_to_encoding()

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 0f5d25b948..1ee07854ed 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -2819,7 +2819,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        <structfield>conforencoding</structfield> <type>int4</type>
       </para>
       <para>
-       Source encoding ID
+       Source encoding ID (<link linkend="pg-encoding-to-char"><function>pg_encoding_to_char()</function></link>
+       can translate this number to the encoding name)
       </para></entry>
      </row>
 
@@ -2828,7 +2829,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        <structfield>contoencoding</structfield> <type>int4</type>
       </para>
       <para>
-       Destination encoding ID
+       Destination encoding ID (<link linkend="pg-encoding-to-char"><function>pg_encoding_to_char()</function></link>
+       can translate this number to the encoding name)
       </para></entry>
      </row>
 
@@ -2927,7 +2929,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       </para>
       <para>
        Character encoding for this database
-       (<function>pg_encoding_to_char()</function> can translate
+       (<link linkend="pg-encoding-to-char"><function>pg_encoding_to_char()</function></link> can translate
        this number to the encoding name)
       </para></entry>
      </row>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6388385edc..af0488fed7 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -22987,6 +22987,36 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
        </para></entry>
       </row>
 
+      <row>
+       <entry id="pg-char-to-encoding" role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>pg_char_to_encoding</primary>
+        </indexterm>
+        <function>pg_char_to_encoding</function> ( <parameter>encoding</parameter> <type>name</type> )
+        <returnvalue>int</returnvalue>
+       </para>
+       <para>
+        Converts the supplied encoding name into an integer representing the
+        internal identifier used in some system catalog tables.
+        Returns <literal>-1</literal> if an unknown encoding name is provided.
+       </para></entry>
+      </row>
+
+      <row>
+       <entry id="pg-encoding-to-char" role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>pg_encoding_to_char</primary>
+        </indexterm>
+        <function>pg_encoding_to_char</function> ( <parameter>encoding</parameter> <type>int</type> )
+        <returnvalue>name</returnvalue>
+       </para>
+       <para>
+        Converts the integer used as the internal identifier of an encoding in some
+        system catalog tables into a human-readable string.
+        Returns an empty string if an invalid encoding number is provided.
+       </para></entry>
+      </row>
+
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>

Laurenz Albe

laurenz.albe@cybertec.at

over 4 years ago

In reply to: Ian Lawrence Barwick (#1)

Re: [PATCH] document

On Wed, 2021-07-14 at 14:43 +0900, Ian Lawrence Barwick wrote:

Hi

The description for "pg_database" [1] mentions the function
"pg_encoding_to_char()", but this is not described anywhere in the docs. Given
that that it (and the corresponding "pg_char_to_encoding()") have been around
since 7.0 [2], it's probably not a burning issue, but it seems not entirely
unreasonable to add short descriptions for both (and link from "pg_conversion"
while we're at it); see attached patch. "System Catalog Information Functions"
seems the most logical place to put these.

[1] https://www.postgresql.org/docs/current/catalog-pg-database.html
[2] https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=5eb1d0deb15f2b7cd0051bef12f3e091516c723b

Will add to the next commitfest.

Yours,
Laurenz Albe

Ian Lawrence Barwick

barwick@gmail.com

over 4 years ago

In reply to: Ian Lawrence Barwick (#1)

Re: [PATCH] document pg_encoding_to_char() and pg_char_to_encoding()

2021年7月14日(水) 14:43 Ian Lawrence Barwick <barwick@gmail.com>:

Hi

The description for "pg_database" [1] mentions the function
"pg_encoding_to_char()", but this is not described anywhere in the docs. Given
that that it (and the corresponding "pg_char_to_encoding()") have been around
since 7.0 [2], it's probably not a burning issue, but it seems not entirely
unreasonable to add short descriptions for both (and link from "pg_conversion"
while we're at it); see attached patch. "System Catalog Information Functions"
seems the most logical place to put these.

[1] https://www.postgresql.org/docs/current/catalog-pg-database.html
[2] https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=5eb1d0deb15f2b7cd0051bef12f3e091516c723b

Will add to the next commitfest.

Added; apologies, the subject line of the original mail was
unintentionally truncated.

Regards

Ian Barwick

--
EnterpriseDB: https://www.enterprisedb.com

Fujii Masao

masao.fujii@oss.nttdata.com

over 4 years ago

In reply to: Laurenz Albe (#2)

Re: [PATCH] document

On 2021/07/14 14:45, Laurenz Albe wrote:

On Wed, 2021-07-14 at 14:43 +0900, Ian Lawrence Barwick wrote:

Hi

The description for "pg_database" [1] mentions the function
"pg_encoding_to_char()", but this is not described anywhere in the docs. Given
that that it (and the corresponding "pg_char_to_encoding()") have been around
since 7.0 [2], it's probably not a burning issue, but it seems not entirely
unreasonable to add short descriptions for both (and link from "pg_conversion"
while we're at it); see attached patch. "System Catalog Information Functions"
seems the most logical place to put these.

[1] https://www.postgresql.org/docs/current/catalog-pg-database.html
[2] https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=5eb1d0deb15f2b7cd0051bef12f3e091516c723b

Will add to the next commitfest.

+1

When I applied the patch to the master, I found that the table entries for
those function were added into the table for aclitem functions in the docs.
I think this is not valid position and needs to be moved to the proper one
(maybe the table for system catalog information functions?).

+        <returnvalue>int</returnvalue>
+        <function>pg_encoding_to_char</function> ( <parameter>encoding</parameter> <type>int</type> )

It's better to s/int/integer because the entries for other functions
in func.sgml use "integer".

Regards,

--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

Tom Lane

tgl@sss.pgh.pa.us

over 4 years ago

In reply to: Fujii Masao (#4)

Re: [PATCH] document

Fujii Masao <masao.fujii@oss.nttdata.com> writes:

When I applied the patch to the master, I found that the table entries for
those function were added into the table for aclitem functions in the docs.
I think this is not valid position and needs to be moved to the proper one
(maybe the table for system catalog information functions?).

You have to be very careful these days when applying stale patches to
func.sgml --- there's enough duplicate boilerplate that "patch' can easily
be fooled into dumping an addition into the wrong place. I doubt that
the submitter meant the doc addition to go there.

regards, tom lane

Justin Pryzby

pryzby@telsasoft.com

over 4 years ago

In reply to: Tom Lane (#5)

Re: [PATCH] document

On Wed, Aug 25, 2021 at 09:50:13AM -0400, Tom Lane wrote:

Fujii Masao <masao.fujii@oss.nttdata.com> writes:

When I applied the patch to the master, I found that the table entries for
those function were added into the table for aclitem functions in the docs.
I think this is not valid position and needs to be moved to the proper one
(maybe the table for system catalog information functions?).

You have to be very careful these days when applying stale patches to
func.sgml --- there's enough duplicate boilerplate that "patch' can easily
be fooled into dumping an addition into the wrong place. I doubt that
the submitter meant the doc addition to go there.

I suppose one solution to this is to use git format-patch -U11 or similar, at
least for doc/

Or write the "duplicate boilerplate" across fewer lines.

And another is to add  comments before and/or after each.

--
Justin

Fujii Masao

masao.fujii@oss.nttdata.com

over 4 years ago

In reply to: Justin Pryzby (#6)

1 attachment(s)

Re: [PATCH] document

On 2021/08/26 1:39, Justin Pryzby wrote:

On Wed, Aug 25, 2021 at 09:50:13AM -0400, Tom Lane wrote:

Fujii Masao <masao.fujii@oss.nttdata.com> writes:

When I applied the patch to the master, I found that the table entries for
those function were added into the table for aclitem functions in the docs.
I think this is not valid position and needs to be moved to the proper one
(maybe the table for system catalog information functions?).

You have to be very careful these days when applying stale patches to
func.sgml --- there's enough duplicate boilerplate that "patch' can easily
be fooled into dumping an addition into the wrong place. I doubt that
the submitter meant the doc addition to go there.

I suppose one solution to this is to use git format-patch -U11 or similar, at
least for doc/

Yes. I moved the desriptions of the function into the table for
system catalog information functions, and made the patch by using
git diff -U6. Patch attached. Barring any objection, I'm thinking
to commit it.

Regards,

--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

Attachments:

doc-pg-char-encoding-funcs_v2.patchtext/plain; charset=UTF-8; name=doc-pg-char-encoding-funcs_v2.patch; x-mac-creator=0; x-mac-type=0Download

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 384e6eaa3b..fd6910ddbe 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -2816,22 +2816,24 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
 
      <row>
       <entry role="catalog_table_entry"><para role="column_definition">
        <structfield>conforencoding</structfield> <type>int4</type>
       </para>
       <para>
-       Source encoding ID
+       Source encoding ID (<link linkend="pg-encoding-to-char"><function>pg_encoding_to_char()</function></link>
+       can translate this number to the encoding name)
       </para></entry>
      </row>
 
      <row>
       <entry role="catalog_table_entry"><para role="column_definition">
        <structfield>contoencoding</structfield> <type>int4</type>
       </para>
       <para>
-       Destination encoding ID
+       Destination encoding ID (<link linkend="pg-encoding-to-char"><function>pg_encoding_to_char()</function></link>
+       can translate this number to the encoding name)
       </para></entry>
      </row>
 
      <row>
       <entry role="catalog_table_entry"><para role="column_definition">
        <structfield>conproc</structfield> <type>regproc</type>
@@ -2924,13 +2926,13 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
      <row>
       <entry role="catalog_table_entry"><para role="column_definition">
        <structfield>encoding</structfield> <type>int4</type>
       </para>
       <para>
        Character encoding for this database
-       (<function>pg_encoding_to_char()</function> can translate
+       (<link linkend="pg-encoding-to-char"><function>pg_encoding_to_char()</function></link> can translate
        this number to the encoding name)
       </para></entry>
      </row>
 
      <row>
       <entry role="catalog_table_entry"><para role="column_definition">
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 78812b2dbe..42dff83e16 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -23325,12 +23325,42 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
         Returns the SQL name for a data type that is identified by its type
         OID and possibly a type modifier.  Pass NULL for the type modifier if
         no specific modifier is known.
        </para></entry>
       </row>
 
+      <row>
+       <entry id="pg-char-to-encoding" role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>pg_char_to_encoding</primary>
+        </indexterm>
+        <function>pg_char_to_encoding</function> ( <parameter>encoding</parameter> <type>name</type> )
+        <returnvalue>integer</returnvalue>
+       </para>
+       <para>
+        Converts the supplied encoding name into an integer representing the
+        internal identifier used in some system catalog tables.
+        Returns <literal>-1</literal> if an unknown encoding name is provided.
+       </para></entry>
+      </row>
+
+      <row>
+       <entry id="pg-encoding-to-char" role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>pg_encoding_to_char</primary>
+        </indexterm>
+        <function>pg_encoding_to_char</function> ( <parameter>encoding</parameter> <type>integer</type> )
+        <returnvalue>name</returnvalue>
+       </para>
+       <para>
+        Converts the integer used as the internal identifier of an encoding in some
+        system catalog tables into a human-readable string.
+        Returns an empty string if an invalid encoding number is provided.
+       </para></entry>
+      </row>
+
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
          <primary>pg_get_catalog_foreign_keys</primary>
         </indexterm>
         <function>pg_get_catalog_foreign_keys</function> ()

Fujii Masao

masao.fujii@oss.nttdata.com

over 4 years ago

In reply to: Fujii Masao (#7)

Re: [PATCH] document

On 2021/10/04 15:18, Fujii Masao wrote:

On 2021/08/26 1:39, Justin Pryzby wrote:

On Wed, Aug 25, 2021 at 09:50:13AM -0400, Tom Lane wrote:

Fujii Masao <masao.fujii@oss.nttdata.com> writes:

When I applied the patch to the master, I found that the table entries for
those function were added into the table for aclitem functions in the docs.
I think this is not valid position and needs to be moved to the proper one
(maybe the table for system catalog information functions?).

You have to be very careful these days when applying stale patches to
func.sgml --- there's enough duplicate boilerplate that "patch' can easily
be fooled into dumping an addition into the wrong place. I doubt that
the submitter meant the doc addition to go there.

I suppose one solution to this is to use git format-patch -U11 or similar, at
least for doc/

Yes. I moved the desriptions of the function into the table for
system catalog information functions, and made the patch by using
git diff -U6. Patch attached. Barring any objection, I'm thinking
to commit it.

Pushed. Thanks!

Regards,

--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION