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.
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
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 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.
