pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedSuggestion for deprecated spellings
8+ messages / 4 participants
[nested] [flat]
* Suggestion for deprecated spellings
@ 2023-01-26 12:19 PG Doc comments form <noreply@postgresql.org>
2023-01-30 20:39 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 8+ messages in thread
From: PG Doc comments form @ 2023-01-26 12:19 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: t.kitynski@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/sql-createrole.html
Description:
From time to time some spelling for given command gets obsolete, yet it is
shown in the syntax on "equal rights" as other valid clauses. For instance
see `CREATE ROLE` with deprecated spellings like `IN GROUP` or `USER`. I
guess it would be useful to see those spellings visually marked as
deprecated in Synopsis section (with e.g. strike-through or whatever suits
better). Otherwise, when consulting documentation, it often requires jumping
from the synopsis to detailed description and back to check if given
spelling is still applicable. Just a thought. :-)
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Suggestion for deprecated spellings
2023-01-26 12:19 Suggestion for deprecated spellings PG Doc comments form <noreply@postgresql.org>
@ 2023-01-30 20:39 ` Bruce Momjian <bruce@momjian.us>
2023-01-30 20:52 ` Re: Suggestion for deprecated spellings Tomisław Kityński <t.kitynski@gmail.com>
2023-01-30 21:07 ` Re: Suggestion for deprecated spellings Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 2 replies; 8+ messages in thread
From: Bruce Momjian @ 2023-01-30 20:39 UTC (permalink / raw)
To: t.kitynski@gmail.com; pgsql-docs@lists.postgresql.org
On Thu, Jan 26, 2023 at 12:19:29PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/sql-createrole.html
> Description:
>
> From time to time some spelling for given command gets obsolete, yet it is
> shown in the syntax on "equal rights" as other valid clauses. For instance
> see `CREATE ROLE` with deprecated spellings like `IN GROUP` or `USER`. I
> guess it would be useful to see those spellings visually marked as
> deprecated in Synopsis section (with e.g. strike-through or whatever suits
> better). Otherwise, when consulting documentation, it often requires jumping
> from the synopsis to detailed description and back to check if given
> spelling is still applicable. Just a thought. :-)
We don't need to show all _supported_ syntaxes in the "Synopsis"
section, so we could just remove them.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Embrace your flaws. They make you human, rather than perfect,
which you will never be.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Suggestion for deprecated spellings
2023-01-26 12:19 Suggestion for deprecated spellings PG Doc comments form <noreply@postgresql.org>
2023-01-30 20:39 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
@ 2023-01-30 20:52 ` Tomisław Kityński <t.kitynski@gmail.com>
2023-01-30 20:52 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
1 sibling, 1 reply; 8+ messages in thread
From: Tomisław Kityński @ 2023-01-30 20:52 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; pgsql-docs@lists.postgresql.org
W dniu 30.01.2023 o 21:39, Bruce Momjian pisze:
> On Thu, Jan 26, 2023 at 12:19:29PM +0000, PG Doc comments form wrote:
>> The following documentation comment has been logged on the website:
>>
>> Page:https://www.postgresql.org/docs/12/sql-createrole.html
>> Description:
>>
>> From time to time some spelling for given command gets obsolete, yet it is
>> shown in the syntax on "equal rights" as other valid clauses. For instance
>> see `CREATE ROLE` with deprecated spellings like `IN GROUP` or `USER`. I
>> guess it would be useful to see those spellings visually marked as
>> deprecated in Synopsis section (with e.g. strike-through or whatever suits
>> better). Otherwise, when consulting documentation, it often requires jumping
>> from the synopsis to detailed description and back to check if given
>> spelling is still applicable. Just a thought. :-)
> We don't need to show all _supported_ syntaxes in the "Synopsis"
> section, so we could just remove them.
>
I like this idea even more! :-) Much cleaner approach . And then those
obsolete aliases could be simply mentioned in the text for backward
compatibility. Big yes! :-)
--
Greetings, TK
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Suggestion for deprecated spellings
2023-01-26 12:19 Suggestion for deprecated spellings PG Doc comments form <noreply@postgresql.org>
2023-01-30 20:39 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
2023-01-30 20:52 ` Re: Suggestion for deprecated spellings Tomisław Kityński <t.kitynski@gmail.com>
@ 2023-01-30 20:52 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 8+ messages in thread
From: Bruce Momjian @ 2023-01-30 20:52 UTC (permalink / raw)
To: Tomisław Kityński <t.kitynski@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Mon, Jan 30, 2023 at 09:52:15PM +0100, Tomisław Kityński wrote:
> W dniu 30.01.2023 o 21:39, Bruce Momjian pisze:
>
> On Thu, Jan 26, 2023 at 12:19:29PM +0000, PG Doc comments form wrote:
>
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/sql-createrole.html
> Description:
>
> >From time to time some spelling for given command gets obsolete, yet it is
> shown in the syntax on "equal rights" as other valid clauses. For instance
> see `CREATE ROLE` with deprecated spellings like `IN GROUP` or `USER`. I
> guess it would be useful to see those spellings visually marked as
> deprecated in Synopsis section (with e.g. strike-through or whatever suits
> better). Otherwise, when consulting documentation, it often requires jumping
> from the synopsis to detailed description and back to check if given
> spelling is still applicable. Just a thought. :-)
>
> We don't need to show all _supported_ syntaxes in the "Synopsis"
> section, so we could just remove them.
>
>
> I like this idea even more! :-) Much cleaner approach . And then those obsolete
> aliases could be simply mentioned in the text for backward compatibility. Big
> yes! :-)
Right. What examples of these do we have in our docs? Just these?
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Embrace your flaws. They make you human, rather than perfect,
which you will never be.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Suggestion for deprecated spellings
2023-01-26 12:19 Suggestion for deprecated spellings PG Doc comments form <noreply@postgresql.org>
2023-01-30 20:39 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
@ 2023-01-30 21:07 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-01-30 21:17 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
1 sibling, 1 reply; 8+ messages in thread
From: Tom Lane @ 2023-01-30 21:07 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: t.kitynski@gmail.com; pgsql-docs@lists.postgresql.org
Bruce Momjian <bruce@momjian.us> writes:
> On Thu, Jan 26, 2023 at 12:19:29PM +0000, PG Doc comments form wrote:
>> From time to time some spelling for given command gets obsolete, yet it is
>> shown in the syntax on "equal rights" as other valid clauses.
> We don't need to show all _supported_ syntaxes in the "Synopsis"
> section, so we could just remove them.
IIRC, there is precedent in COPY for moving obsolete alternatives
to a separate part of the man page. I'd prefer that to just
removing them, because then there is no documentation to help
someone understand what an old SQL script is doing.
regards, tom lane
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Suggestion for deprecated spellings
2023-01-26 12:19 Suggestion for deprecated spellings PG Doc comments form <noreply@postgresql.org>
2023-01-30 20:39 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
2023-01-30 21:07 ` Re: Suggestion for deprecated spellings Tom Lane <tgl@sss.pgh.pa.us>
@ 2023-01-30 21:17 ` Bruce Momjian <bruce@momjian.us>
2023-09-28 00:17 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 8+ messages in thread
From: Bruce Momjian @ 2023-01-30 21:17 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: t.kitynski@gmail.com; pgsql-docs@lists.postgresql.org
On Mon, Jan 30, 2023 at 04:07:46PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Thu, Jan 26, 2023 at 12:19:29PM +0000, PG Doc comments form wrote:
> >> From time to time some spelling for given command gets obsolete, yet it is
> >> shown in the syntax on "equal rights" as other valid clauses.
>
> > We don't need to show all _supported_ syntaxes in the "Synopsis"
> > section, so we could just remove them.
>
> IIRC, there is precedent in COPY for moving obsolete alternatives
> to a separate part of the man page. I'd prefer that to just
> removing them, because then there is no documentation to help
> someone understand what an old SQL script is doing.
Yeah, I remember that with COPY. t.kitynski@gmail.com, please us that
as a guide. Thanks.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Embrace your flaws. They make you human, rather than perfect,
which you will never be.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Suggestion for deprecated spellings
2023-01-26 12:19 Suggestion for deprecated spellings PG Doc comments form <noreply@postgresql.org>
2023-01-30 20:39 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
2023-01-30 21:07 ` Re: Suggestion for deprecated spellings Tom Lane <tgl@sss.pgh.pa.us>
2023-01-30 21:17 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
@ 2023-09-28 00:17 ` Bruce Momjian <bruce@momjian.us>
2023-10-10 20:44 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 8+ messages in thread
From: Bruce Momjian @ 2023-09-28 00:17 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: t.kitynski@gmail.com; pgsql-docs@lists.postgresql.org
On Mon, Jan 30, 2023 at 04:17:14PM -0500, Bruce Momjian wrote:
> On Mon, Jan 30, 2023 at 04:07:46PM -0500, Tom Lane wrote:
> > Bruce Momjian <bruce@momjian.us> writes:
> > > On Thu, Jan 26, 2023 at 12:19:29PM +0000, PG Doc comments form wrote:
> > >> From time to time some spelling for given command gets obsolete, yet it is
> > >> shown in the syntax on "equal rights" as other valid clauses.
> >
> > > We don't need to show all _supported_ syntaxes in the "Synopsis"
> > > section, so we could just remove them.
> >
> > IIRC, there is precedent in COPY for moving obsolete alternatives
> > to a separate part of the man page. I'd prefer that to just
> > removing them, because then there is no documentation to help
> > someone understand what an old SQL script is doing.
>
> Yeah, I remember that with COPY. t.kitynski@gmail.com, please us that
> as a guide. Thanks.
I developed the attached patch to move the deprecated clauses to the
bottom.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
Attachments:
[text/x-diff] group.diff (2.8K, ../../ZRTGMpPpFCFbdSsM@momjian.us/2-group.diff)
download | inline diff:
diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 7249fc7432..6a3cd6d808 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -36,10 +36,8 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac
| [ ENCRYPTED ] PASSWORD '<replaceable class="parameter">password</replaceable>' | PASSWORD NULL
| VALID UNTIL '<replaceable class="parameter">timestamp</replaceable>'
| IN ROLE <replaceable class="parameter">role_name</replaceable> [, ...]
- | IN GROUP <replaceable class="parameter">role_name</replaceable> [, ...]
| ROLE <replaceable class="parameter">role_name</replaceable> [, ...]
| ADMIN <replaceable class="parameter">role_name</replaceable> [, ...]
- | USER <replaceable class="parameter">role_name</replaceable> [, ...]
| SYSID <replaceable class="parameter">uid</replaceable>
</synopsis>
</refsynopsisdiv>
@@ -294,15 +292,6 @@ in sync when changing the above synopsis!
</listitem>
</varlistentry>
- <varlistentry>
- <term><literal>IN GROUP</literal> <replaceable class="parameter">role_name</replaceable></term>
- <listitem>
- <para><literal>IN GROUP</literal> is an obsolete spelling of
- <literal>IN ROLE</literal>.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><literal>ROLE</literal> <replaceable class="parameter">role_name</replaceable></term>
<listitem>
@@ -326,16 +315,6 @@ in sync when changing the above synopsis!
</listitem>
</varlistentry>
- <varlistentry>
- <term><literal>USER</literal> <replaceable class="parameter">role_name</replaceable></term>
- <listitem>
- <para>
- The <literal>USER</literal> clause is an obsolete spelling of
- the <literal>ROLE</literal> clause.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><literal>SYSID</literal> <replaceable class="parameter">uid</replaceable></term>
<listitem>
@@ -484,6 +463,22 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ WITH ADMIN <repl
by giving users the <literal>NOINHERIT</literal> attribute, while roles are
given the <literal>INHERIT</literal> attribute.
</para>
+
+ <para>
+ The <literal>USER</literal> clause has the same behavior as
+ <literal>ROLE</literal> but has been deprecated:
+<synopsis>
+ USER <replaceable class="parameter">role_name</replaceable> [, ...]
+</synopsis>
+ </para>
+
+ <para>
+ The <literal>IN GROUP</literal> clause has the same behavior as <literal>IN
+ ROLE</literal> but has been deprecated:
+<synopsis>
+ IN GROUP <replaceable class="parameter">role_name</replaceable> [, ...]
+</synopsis>
+ </para>
</refsect1>
<refsect1>
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Suggestion for deprecated spellings
2023-01-26 12:19 Suggestion for deprecated spellings PG Doc comments form <noreply@postgresql.org>
2023-01-30 20:39 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
2023-01-30 21:07 ` Re: Suggestion for deprecated spellings Tom Lane <tgl@sss.pgh.pa.us>
2023-01-30 21:17 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
2023-09-28 00:17 ` Re: Suggestion for deprecated spellings Bruce Momjian <bruce@momjian.us>
@ 2023-10-10 20:44 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 8+ messages in thread
From: Bruce Momjian @ 2023-10-10 20:44 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: t.kitynski@gmail.com; pgsql-docs@lists.postgresql.org
On Wed, Sep 27, 2023 at 08:17:54PM -0400, Bruce Momjian wrote:
> On Mon, Jan 30, 2023 at 04:17:14PM -0500, Bruce Momjian wrote:
> > On Mon, Jan 30, 2023 at 04:07:46PM -0500, Tom Lane wrote:
> > > Bruce Momjian <bruce@momjian.us> writes:
> > > > On Thu, Jan 26, 2023 at 12:19:29PM +0000, PG Doc comments form wrote:
> > > >> From time to time some spelling for given command gets obsolete, yet it is
> > > >> shown in the syntax on "equal rights" as other valid clauses.
> > >
> > > > We don't need to show all _supported_ syntaxes in the "Synopsis"
> > > > section, so we could just remove them.
> > >
> > > IIRC, there is precedent in COPY for moving obsolete alternatives
> > > to a separate part of the man page. I'd prefer that to just
> > > removing them, because then there is no documentation to help
> > > someone understand what an old SQL script is doing.
> >
> > Yeah, I remember that with COPY. t.kitynski@gmail.com, please us that
> > as a guide. Thanks.
>
> I developed the attached patch to move the deprecated clauses to the
> bottom.
Applied to master. I didn't want to backpatch a command syntax
adjustment like this.
--
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] 8+ messages in thread
end of thread, other threads:[~2023-10-10 20:44 UTC | newest]
Thread overview: 8+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-01-26 12:19 Suggestion for deprecated spellings PG Doc comments form <noreply@postgresql.org>
2023-01-30 20:39 ` Bruce Momjian <bruce@momjian.us>
2023-01-30 20:52 ` Tomisław Kityński <t.kitynski@gmail.com>
2023-01-30 20:52 ` Bruce Momjian <bruce@momjian.us>
2023-01-30 21:07 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-01-30 21:17 ` Bruce Momjian <bruce@momjian.us>
2023-09-28 00:17 ` Bruce Momjian <bruce@momjian.us>
2023-10-10 20:44 ` 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