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

+1

Yours,
Laurenz Albe

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

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

+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

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

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 <!-- function() --> comments before and/or after each.

--
Justin

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

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