pg.ddx.io pgsql-bugs@postgresql.org mailing list archive
help / color / mirror / Atom feedBUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command
7+ messages / 6 participants
[nested] [flat]
* BUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command
@ 2024-02-07 02:25 PG Bug reporting form <noreply@postgresql.org>
0 siblings, 1 reply; 7+ messages in thread
From: PG Bug reporting form @ 2024-02-07 02:25 UTC (permalink / raw)
To: pgsql-bugs@lists.postgresql.org; +Cc: masano@sraoss.co.jp
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.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command
@ 2024-02-07 04:01 Laurenz Albe <laurenz.albe@cybertec.at>
parent: PG Bug reporting form <noreply@postgresql.org>
0 siblings, 1 reply; 7+ messages in thread
From: Laurenz Albe @ 2024-02-07 04:01 UTC (permalink / raw)
To: masano@sraoss.co.jp; pgsql-bugs@lists.postgresql.org
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
Attachments:
v1-0001-Remove-documentation-for-SHOW-LC_COLLATE-LC_CTYPE.patch (text/x-patch, 1.6K) download
From 4205e98a9885e12fb15cf02ea619deeb31bc802a Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Wed, 7 Feb 2024 04:55:51 +0100
Subject: [PATCH v1] Remove documentation for SHOW LC_COLLATE/LC_CTYPE
These have been removed in b0f6c43716, but the documentation was
not updated.
Reported-by: Yuta Masano
Backpatch-to: 16
Discussion: https://postgr.es/m/18336-d3652b898b550423@postgresql.org
---
doc/src/sgml/ref/show.sgml | 24 ------------------------
1 file changed, 24 deletions(-)
diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml
index b3747b119f..5fbb5bbe01 100644
--- a/doc/src/sgml/ref/show.sgml
+++ b/doc/src/sgml/ref/show.sgml
@@ -77,30 +77,6 @@ SHOW ALL
</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>
--
2.43.0
* Re: BUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command
@ 2024-02-07 07:49 Peter Eisentraut <peter@eisentraut.org>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 7+ messages in thread
From: Peter Eisentraut @ 2024-02-07 07:49 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; masano@sraoss.co.jp; pgsql-bugs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command
@ 2024-02-07 19:53 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Peter Eisentraut <peter@eisentraut.org>
0 siblings, 1 reply; 7+ messages in thread
From: Laurenz Albe @ 2024-02-07 19:53 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; masano@sraoss.co.jp; pgsql-bugs@lists.postgresql.org
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
Attachments:
v2-0001-Doc-Remove-preset-parameters-from-SHOW-reference-.patch (text/x-patch, 2.8K) download
From f75d42e5df075c9e5b5bf6a8bfebaba4e66fca84 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Wed, 7 Feb 2024 20:51:52 +0100
Subject: [PATCH v2] Doc: Remove preset parameters from SHOW reference page
The list of parameters is redundant and incomplete and constitutes
a backpatching hazard (it was missed by b0f6c43716), so let's get
rid of it.
Reported-by: Yuta Masano
Backpatch-to: 16
Discussion: https://postgr.es/m/18336-d3652b898b550423@postgresql.org
---
doc/src/sgml/ref/show.sgml | 60 ++------------------------------------
1 file changed, 2 insertions(+), 58 deletions(-)
diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml
index b3747b119f..3db13ad4cd 100644
--- a/doc/src/sgml/ref/show.sgml
+++ b/doc/src/sgml/ref/show.sgml
@@ -52,64 +52,8 @@ SHOW ALL
<para>
The name of a run-time parameter. Available parameters are
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>
+ linkend="sql-set"/> reference page.
+ </para>
</listitem>
</varlistentry>
--
2.43.0
* Re: BUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command
@ 2024-08-17 05:21 Imran Zaheer <imran.zhir@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 7+ messages in thread
From: Imran Zaheer @ 2024-08-17 05:21 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Peter Eisentraut <peter@eisentraut.org>; masano@sraoss.co.jp; pgsql-bugs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command
@ 2024-08-17 18:12 Tom Lane <tgl@sss.pgh.pa.us>
parent: Imran Zaheer <imran.zhir@gmail.com>
0 siblings, 1 reply; 7+ messages in thread
From: Tom Lane @ 2024-08-17 18:12 UTC (permalink / raw)
To: Imran Zaheer <imran.zhir@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Peter Eisentraut <peter@eisentraut.org>; masano@sraoss.co.jp; pgsql-bugs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: BUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command
@ 2024-08-17 19:36 Bruce Momjian <bruce@momjian.us>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 7+ messages in thread
From: Bruce Momjian @ 2024-08-17 19:36 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Imran Zaheer <imran.zhir@gmail.com>; Laurenz Albe <laurenz.albe@cybertec.at>; Peter Eisentraut <peter@eisentraut.org>; masano@sraoss.co.jp; pgsql-bugs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2024-08-17 19:36 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-02-07 02:25 BUG #18336: Inconsistency in PostgreSQL 16 Documentation for SHOW Command PG Bug reporting form <noreply@postgresql.org>
2024-02-07 04:01 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-02-07 07:49 ` Peter Eisentraut <peter@eisentraut.org>
2024-02-07 19:53 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-08-17 05:21 ` Imran Zaheer <imran.zhir@gmail.com>
2024-08-17 18:12 ` Tom Lane <tgl@sss.pgh.pa.us>
2024-08-17 19:36 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox