From f6b5d05ba9a4ac7c5ebec76045c6e0afcf7c9eec Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Tue, 5 Oct 2021 12:52:51 +0900
Subject: [PATCH] doc: Document pg_encoding_to_char() and
 pg_char_to_encoding().

Previously both functions were not described anywhere in the docs.
But since they have been around since 7.0 and mentioned in the description
for system catalog like pg_database, it's reasonable to add short
descriptions for them.

Author: Ian Lawrence Barwick
Reviewed-by: Laurenz Albe, Fujii Masao
Discussion: https://postgr.es/m/CAB8KJ=infievn4q1N4X7Vx8w4_RMPPG0pLvxhSDjy5WQOSHW9g@mail.gmail.com
---
 doc/src/sgml/catalogs.sgml |  8 +++++---
 doc/src/sgml/func.sgml     | 30 ++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 384e6eaa3b0..fd6910ddbea 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 78812b2dbeb..42dff83e160 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -23328,6 +23328,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>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>
-- 
2.30.2