Re: Suggestion for deprecated spellings
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 writes: > > > > On Thu, Jan 26, 2023 at 12:19:29PM +, 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.kityn...@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 https://momjian.us EDB https://enterprisedb.com Only you can decide what is important to you.
Re: Suggestion for deprecated spellings
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 writes: > > > On Thu, Jan 26, 2023 at 12:19:29PM +, 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.kityn...@gmail.com, please us that > as a guide. Thanks. I developed the attached patch to move the deprecated clauses to the bottom. -- Bruce Momjian https://momjian.us EDB https://enterprisedb.com Only you can decide what is important to you. 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 name [ [ WITH ] password' | PASSWORD NULL | VALID UNTIL 'timestamp' | IN ROLE role_name [, ...] -| IN GROUP role_name [, ...] | ROLE role_name [, ...] | ADMIN role_name [, ...] -| USER role_name [, ...] | SYSID uid @@ -294,15 +292,6 @@ in sync when changing the above synopsis! - - IN GROUP role_name - - IN GROUP is an obsolete spelling of -IN ROLE. - - - - ROLE role_name @@ -326,16 +315,6 @@ in sync when changing the above synopsis! - - USER role_name - - -The USER clause is an obsolete spelling of -the ROLE clause. - - - - SYSID uid @@ -484,6 +463,22 @@ CREATE ROLE name [ WITH ADMIN NOINHERIT attribute, while roles are given the INHERIT attribute. + + + The USER clause has the same behavior as + ROLE but has been deprecated: + +USER role_name [, ...] + + + + + The IN GROUP clause has the same behavior as IN + ROLE but has been deprecated: + +IN GROUP role_name [, ...] + +
Re: Suggestion for deprecated spellings
W dniu 30.01.2023 o 21:39, Bruce Momjian pisze: On Thu, Jan 26, 2023 at 12:19:29PM +, 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
Re: Suggestion for deprecated spellings
On Mon, Jan 30, 2023 at 04:07:46PM -0500, Tom Lane wrote: > Bruce Momjian writes: > > On Thu, Jan 26, 2023 at 12:19:29PM +, 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.kityn...@gmail.com, please us that as a guide. Thanks. -- Bruce Momjian https://momjian.us EDB https://enterprisedb.com Embrace your flaws. They make you human, rather than perfect, which you will never be.
Re: Suggestion for deprecated spellings
Bruce Momjian writes: > On Thu, Jan 26, 2023 at 12:19:29PM +, 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
Re: Suggestion for deprecated spellings
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 +, 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 https://momjian.us EDB https://enterprisedb.com Embrace your flaws. They make you human, rather than perfect, which you will never be.
Re: Suggestion for deprecated spellings
On Thu, Jan 26, 2023 at 12:19:29PM +, 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 https://momjian.us EDB https://enterprisedb.com Embrace your flaws. They make you human, rather than perfect, which you will never be.
