Re: Is the doc for SHOW somewhat stale? - Mailing list pgsql-hackers

Thank you for the comments.

At Thu, 15 Oct 2020 23:18:33 +0900, Fujii Masao <masao.fujii@oss.nttdata.com> wrote in 
> 
> 
> On 2020/10/06 16:53, Kyotaro Horiguchi wrote:
> > Hello.
> > If I read the documentation of the SHOW command, it says:
> > https://www.postgresql.org/docs/13/sql-show.html
> > 
> >> name
> >>    The name of a run-time parameter. Available parameters are documented
> >>    in Chapter 19 and on the SET reference page. In addition, there are a
> >>    few parameters that can be shown but not set:
> >>       SERVER_VERSION
> >>       SERVER_ENCODING
> >>       LC_COLLATE
> >>       LC_CTYPE
> >>       IS_SUPERUSER
> >> ALL
> >>    Show the values of all configuration parameters, with descriptions.
> > It seems to me GUC variables of PGC_INTERNAL are shown above, but
> > there are 13 other variables of that context.  On the other hand
> > is_superuser is not shown in pg_settings view nor by SHOW ALL
> > (GUC_NO_SHOW_ALL).
> > is_superuser is commented as the follows in guc.c:
> > 
> >> /* Not for general use --- used by SET SESSION AUTHORIZATION */
> > So, if I followed the current style of the page, we should:
> >   - remove IS_SUPERUSER  from the documentation.
> 
> -1
> Because "show is_superuser" has been documented and supported for a
> long time.
> As far as I just googled, there seem some cases where that command is
> used.

If it is a de-facto public varialbe, it's unnatural that that variable
is GUC_NO_SHOW_ALL. We shuold show it by SHOW ALL and in the
documentation. (Added changes to guc.c and config.sgml)

> >   - add the 13 variables.
> > However, it seems better that that item simply points to "19.15 Preset
> > Options" instead, as attached.
> 
> +1 to remove the descriptions of server_version, server_encoding,
> lc_collate
> and lc_ctype, in order to get rid of the duplicated descriptions.
> But ISTM that we don't need to add the pointer to "20.15 Preset
> Options"
> because there is already the pointer to "Chapter 20" in the docs and
> that
> chapter obviously includes "20.15 Preset Options".

(19 was moved to 20)

As the ".15" suggests, the chapter 20 is so large and the section
section name "Preset Options" doesn't naturally correspond to the
description that it's hard for readers to find that section is that
without a hint like "the section "Preset Options"".  If we wrote that
section name, it's unnatural that it is not a link. (Not changed)

regards.

-- 
Kyotaro Horiguchi
NTT Open Source Software Center
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 2768c85a96..dfac65bcce 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -9689,6 +9689,19 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </listitem>
      </varlistentry>
 
+     <varlistentry id="is-superuser" xreflabel="is_superuser">
+      <term><varname>is_superuser</varname> (<type>boolean</type>)
+      <indexterm>
+       <primary><varname>is_superuser</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Reports whether the user name of the current execution context is a superuser.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="guc-lc-collate" xreflabel="lc_collate">
       <term><varname>lc_collate</varname> (<type>string</type>)
       <indexterm>
diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml
index 945b0491b1..5bb7a2ca1b 100644
--- a/doc/src/sgml/ref/show.sgml
+++ b/doc/src/sgml/ref/show.sgml
@@ -54,62 +54,8 @@ SHOW ALL
       documented in <xref linkend="runtime-config"/> and on the <xref
       linkend="sql-set"/> reference page.  In
       addition, there are a few parameters that can be shown but not
-      set:
-
-      <variablelist>
-       <varlistentry>
-        <term><literal>SERVER_VERSION</literal></term>
-        <listitem>
-         <para>
-          Shows the server's version number.
-         </para>
-        </listitem>
-       </varlistentry>
-
-       <varlistentry>
-        <term><literal>SERVER_ENCODING</literal></term>
-        <listitem>
-         <para>
-          Shows the server-side character set encoding.  At present,
-          this parameter can be shown but not set, because the
-          encoding is determined at database creation time.
-         </para>
-        </listitem>
-       </varlistentry>
-
-       <varlistentry>
-        <term><literal>LC_COLLATE</literal></term>
-        <listitem>
-         <para>
-          Shows the database's locale setting for collation (text
-          ordering).  At present, this parameter can be shown but not
-          set, because the setting is determined at database creation
-          time.
-         </para>
-        </listitem>
-       </varlistentry>
-
-       <varlistentry>
-        <term><literal>LC_CTYPE</literal></term>
-        <listitem>
-         <para>
-          Shows the database's locale setting for character
-          classification.  At present, this parameter can be shown but
-          not set, because the setting is determined at database creation
-          time.
-         </para>
-        </listitem>
-       </varlistentry>
-
-       <varlistentry>
-        <term><literal>IS_SUPERUSER</literal></term>
-        <listitem>
-         <para>
-          True if the current role has superuser privileges.
-         </para>
-        </listitem>
-       </varlistentry>
-      </variablelist></para>
+      set. See <xref linkend="runtime-config-preset"/> for details.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -175,7 +121,7 @@ SHOW ALL;
     .
  xmloption               | content | Sets whether XML data in implicit parsing ...
  zero_damaged_pages      | off     | Continues processing past damaged page headers.
-(196 rows)
+(329 rows)
 </programlisting></para>
  </refsect1>
 
diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c
index a62d64eaa4..098fff6c6e 100644
--- a/src/backend/utils/misc/guc.c
+++ b/src/backend/utils/misc/guc.c
@@ -1120,11 +1120,10 @@ static struct config_bool ConfigureNamesBool[] =
         NULL, NULL, NULL
     },
     {
-        /* Not for general use --- used by SET SESSION AUTHORIZATION */
         {"is_superuser", PGC_INTERNAL, UNGROUPED,
             gettext_noop("Shows whether the current user is a superuser."),
             NULL,
-            GUC_REPORT | GUC_NO_SHOW_ALL | GUC_NO_RESET_ALL | GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE
+            GUC_REPORT | GUC_NO_RESET_ALL | GUC_NOT_IN_SAMPLE | GUC_DISALLOW_IN_FILE
         },
         &session_auth_is_superuser,
         false,