Thread: 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.
Attachment
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.