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

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]https://www.postgresql.org/docs/devel/sql-show.html 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

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.