From: | rir <rirans(at)comcast(dot)net> |
---|---|
To: | Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at> |
Cc: | rir <rirans(at)comcast(dot)net>, pgsql-docs(at)lists(dot)postgresql(dot)org |
Subject: | Re: small patch |
Date: | 2021-10-07 03:39:05 |
Message-ID: | 20211007033905.pmsg5qnyqceepfva@localhost |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-docs |
On Mon, Oct 04, 2021 at 08:18:22AM +0200, Laurenz Albe wrote:
> On Fri, 2021-10-01 at 21:06 -0400, rir wrote:
> > Minor changes to move.sgml and fetch.sgml.
> >
> > The text 'or empty' is inconsistent by restating what the
> > synopsis notation has expressed.
> >
> > The comments on sharing a language feature, while
> > likely helpful during review, seem verbose compared to
> > the non-commenting in other similar files.
>
> Thanks for the effort of preparing a patch.
>
> However, I don't think that is an improvement:
>
> - the comments pointing from MOVE to FETCH and vice versa are
> helpful for people who edit the documentation like you did
> - we should retain "empty or one of", otherwise the following syntax
> would be undocumented:
>
> FETCH FROM c;
> Yours,
> Laurenz Albe
Laurenz,
Your view is completely reasonable, but it suggests that
many of the synopses are leaving syntax undocumented.
The 'empty or one of:' is only used in these two synopses.
If I had found the comments helpful, I would have spared them.
My sense was that the comments were unusual by their existence
for their purpose. That was not rigorous: so okay.
Since I'm only making the same points again, I'll stop.
Thanks again,
Rob
From | Date | Subject | |
---|---|---|---|
Next Message | Laurenz Albe | 2021-10-07 05:58:47 | Re: small patch |
Previous Message | Thomas Munro | 2021-10-05 23:26:04 | Re: Correction to documentation at https://www.postgresql.org/docs/12/kernel-resources.html |