Suggestion for deprecated spellings
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. :-)
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.
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
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.
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
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.
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:
group.difftext/x-diff; charset=us-asciiDownload+16-21
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.