Is the doc for SHOW somewhat stale?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Is the doc for SHOW somewhat stale?

Kyotaro Horiguchi-4
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.
 - add the 13 variables.

However, it seems better that that item simply points to "19.15 Preset
Options" instead, as attached.

By the way, SHOW ALL shows 329 rows as of PG13 whereas documentation
says 196 rows. (14 devel shows 331 rows.)

Thoughts?

regards.

--
Kyotaro Horiguchi
NTT Open Source Software Center

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>
 
Reply | Threaded
Open this post in threaded view
|

Re: Is the doc for SHOW somewhat stale?

Fujii Masao-4


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.


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

Regards,

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


Reply | Threaded
Open this post in threaded view
|

Re: Is the doc for SHOW somewhat stale?

Kyotaro Horiguchi-4
Thank you for the comments.

At Thu, 15 Oct 2020 23:18:33 +0900, Fujii Masao <[hidden email]> 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,