Thread: BUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command

The following bug has been logged on the website:

Bug reference:      18336
Logged by:          Yuta MASANO
Email address:      masano@sraoss.co.jp
PostgreSQL version: 16.1
Operating system:   Not Applicable - Documentation Issue
Description:

In the PostgreSQL 16 release notes, there is an entry stating that the
read-only server variables lc_collate and lc_ctype have been removed.
However, the documentation for the SHOW command on the PostgreSQL official
website (https://www.postgresql.org/docs/current/sql-show.html) still lists
lc_collate and lc_ctype as valid variables. This discrepancy suggests that
the documentation has not been updated to reflect the removal of these
variables. This report is to request clarification and, if necessary, an
update to the documentation to accurately represent the current state of
these server variables in PostgreSQL 16.

On Wed, 2024-02-07 at 02:25 +0000, PG Bug reporting form wrote:
> In the PostgreSQL 16 release notes, there is an entry stating that the
> read-only server variables lc_collate and lc_ctype have been removed.
> However, the documentation for the SHOW command on the PostgreSQL official
> website (https://www.postgresql.org/docs/current/sql-show.html) still lists
> lc_collate and lc_ctype as valid variables.

Right; here is a patch for that.

Yours,
Laurenz Albe

On 07.02.24 05:01, Laurenz Albe wrote:
> On Wed, 2024-02-07 at 02:25 +0000, PG Bug reporting form wrote:
>> In the PostgreSQL 16 release notes, there is an entry stating that the
>> read-only server variables lc_collate and lc_ctype have been removed.
>> However, the documentation for the SHOW command on the PostgreSQL official
>> website (https://www.postgresql.org/docs/current/sql-show.html) still lists
>> lc_collate and lc_ctype as valid variables.
> 
> Right; here is a patch for that.

I think the whole list of read-only options on the SHOW reference page 
is redundant and incomplete.  A more complete list is at <sect1 
id="runtime-config-preset"> in config.sgml.  This includes 
server_version and server_encoding, but not is_superuser.  Maybe that's 
an omission?  I think we should get rid of the list on the SHOW 
reference page.

On Wed, 2024-02-07 at 08:49 +0100, Peter Eisentraut wrote:
> On 07.02.24 05:01, Laurenz Albe wrote:
> > On Wed, 2024-02-07 at 02:25 +0000, PG Bug reporting form wrote:
> > > In the PostgreSQL 16 release notes, there is an entry stating that the
> > > read-only server variables lc_collate and lc_ctype have been removed.
> > > However, the documentation for the SHOW command on the PostgreSQL official
> > > website (https://www.postgresql.org/docs/current/sql-show.html) still lists
> > > lc_collate and lc_ctype as valid variables.
> >
> > Right; here is a patch for that.
>
> I think the whole list of read-only options on the SHOW reference page
> is redundant and incomplete.  A more complete list is at <sect1
> id="runtime-config-preset"> in config.sgml.  This includes
> server_version and server_encoding, but not is_superuser.  Maybe that's
> an omission?  I think we should get rid of the list on the SHOW
> reference page.

That is much better; here is a patch.

Yours,
Laurenz Albe

Hi,

The website[1] still shows the redundant LC_COLLATE & LC_CTYPE params.
Are we planning to update them?

Thanks
Imran

[1]: https://www.postgresql.org/docs/devel/sql-show.html

On Sat, Aug 17, 2024 at 2:09 PM Laurenz Albe <laurenz.albe@cybertec.at> wrote:
>
> On Wed, 2024-02-07 at 08:49 +0100, Peter Eisentraut wrote:
> > On 07.02.24 05:01, Laurenz Albe wrote:
> > > On Wed, 2024-02-07 at 02:25 +0000, PG Bug reporting form wrote:
> > > > In the PostgreSQL 16 release notes, there is an entry stating that the
> > > > read-only server variables lc_collate and lc_ctype have been removed.
> > > > However, the documentation for the SHOW command on the PostgreSQL official
> > > > website (https://www.postgresql.org/docs/current/sql-show.html) still lists
> > > > lc_collate and lc_ctype as valid variables.
> > >
> > > Right; here is a patch for that.
> >
> > I think the whole list of read-only options on the SHOW reference page
> > is redundant and incomplete.  A more complete list is at <sect1
> > id="runtime-config-preset"> in config.sgml.  This includes
> > server_version and server_encoding, but not is_superuser.  Maybe that's
> > an omission?  I think we should get rid of the list on the SHOW
> > reference page.
>
> That is much better; here is a patch.
>
> Yours,
> Laurenz Albe

Imran Zaheer <imran.zhir@gmail.com> writes:
> The website[1] still shows the redundant LC_COLLATE & LC_CTYPE params.
> Are we planning to update them?

This patch seems to have fallen through the cracks.  I thought
I'd go apply it, but on closer inspection the cross-reference
to SET seems to indicate we have some more work to do.
That's because set.sgml has its own list of "special" names.
It'd be fine if SHOW recognized exactly the same list of special
names, but it seems to recognize only some of them:

regression=# set time zone 'America/New_York';
SET
regression=# show time zone;
     TimeZone     
------------------
 America/New_York
(1 row)
regression=# set names 'LATIN1';
SET
regression=# show names;
ERROR:  unrecognized configuration parameter "names"

Digging in gram.y, I see that VariableShowStmt actually has these options:

            SHOW var_name
            | SHOW TIME ZONE
            | SHOW TRANSACTION ISOLATION LEVEL
            | SHOW SESSION AUTHORIZATION
            | SHOW ALL

which is a subset of the special cases in VariableSetStmt (many
of which don't seem to be documented anywhere, although I suppose
most or all are derived from the SQL spec).  I wonder if we ought
to try to make that more systematic.  I don't see a really good
reason why SHOW shouldn't have exactly the same list of special
target-name syntaxes as SET.

In short: we might end up applying exactly this patch to show.sgml,
but we'd have to do some work elsewhere to make the cross-ref to
set.sgml not still be a lie.  Maybe we should go ahead and commit
it as-is anyway, since it's better than what we have.

            regards, tom lane

On Sat, Aug 17, 2024 at 02:12:40PM -0400, Tom Lane wrote:
> Imran Zaheer <imran.zhir@gmail.com> writes:
> > The website[1] still shows the redundant LC_COLLATE & LC_CTYPE params.
> > Are we planning to update them?
> 
> This patch seems to have fallen through the cracks.  I thought

I had kept this thread in my mailbox from February.

> I'd go apply it, but on closer inspection the cross-reference

I was trying to apply Peter Eisentraut's patch when gitmaster stopped
working.

> to SET seems to indicate we have some more work to do.
> That's because set.sgml has its own list of "special" names.
> It'd be fine if SHOW recognized exactly the same list of special
> names, but it seems to recognize only some of them:
> 
> regression=# set time zone 'America/New_York';
> SET
> regression=# show time zone;
>      TimeZone     
> ------------------
>  America/New_York
> (1 row)
> regression=# set names 'LATIN1';
> SET
> regression=# show names;
> ERROR:  unrecognized configuration parameter "names"
> 
> Digging in gram.y, I see that VariableShowStmt actually has these options:
> 
>             SHOW var_name
>             | SHOW TIME ZONE
>             | SHOW TRANSACTION ISOLATION LEVEL
>             | SHOW SESSION AUTHORIZATION
>             | SHOW ALL
> 
> which is a subset of the special cases in VariableSetStmt (many
> of which don't seem to be documented anywhere, although I suppose
> most or all are derived from the SQL spec).  I wonder if we ought
> to try to make that more systematic.  I don't see a really good
> reason why SHOW shouldn't have exactly the same list of special
> target-name syntaxes as SET.

Agredd.

> In short: we might end up applying exactly this patch to show.sgml,
> but we'd have to do some work elsewhere to make the cross-ref to
> set.sgml not still be a lie.  Maybe we should go ahead and commit
> it as-is anyway, since it's better than what we have.

I think we should apply what Peter supplied, and then we can do a
follow-up patch to synchronize.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.