Date: Wed, 6 Oct 2021 23:39:05 -0400
From: rir <rirans@comcast.net>
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: rir <rirans@comcast.net>, pgsql-docs@lists.postgresql.org
Subject: Re: small patch
Message-ID: <20211007033905.pmsg5qnyqceepfva@localhost>
References: <20211001163938.ifg4ayrsjwd7r6zr@localhost>
 <1c0eefa304434f67fd6a5a9d3f420d59ac74623a.camel@cybertec.at>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <1c0eefa304434f67fd6a5a9d3f420d59ac74623a.camel@cybertec.at>
User-Agent: NeoMutt/20180716
Archived-At: 
 <https://www.postgresql.org/message-id/20211007033905.pmsg5qnyqceepfva%40localhost>
Precedence: bulk

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