Re: Is the doc for SHOW somewhat stale?

Thank you for the comments.

At Thu, 15 Oct 2020 23:18:33 +0900, Fujii Masao <masao(dot)fujii(at)oss(dot)nttdata(dot)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