Re: Small docs bugfix: make it clear what can be used in UPDATE FROM and DELETE USING

On Thu, Feb 13, 2020 at 9:26 AM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> "David G. Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com> writes:
> > On Thu, Feb 13, 2020 at 4:13 AM Alexey Bashtanov <bashtanov(at)imap(dot)cc>
> wrote:
> >> Please could someone have a look at the patch attached?
> >> It's not just pedantry but rather based on a real-life example of
> >> someone reading and being not sure
> >> whether e.g. joins can be used in there.
>
> > Drive-by comment - I'm on board with the idea but I do not believe this
> > patch accomplishes the goal.
> > IMO there is too much indirection happening and trying to get terms
> exactly
> > right, so the user can find or remember them from elsewhere in the
> > documentation, doesn't seem like the best solution. The material isn't
> > that extensive and since it is covered elsewhere a little bit more
> > explicitness in the DELETE and FROM documentation seems like a better
> path
> > forward.
>
> I see where you're coming from, but I do not think that repeating the
> whole from_item syntax in UPDATE and DELETE is the best way forward.
> In the first place, we'd inevitably forget to update those copies,
> and in the second, I'm not sure that the syntax is all that helpful
> without all the supporting text in the SELECT ref page --- which
> surely we aren't going to duplicate.
>
> I think the real problem with the places Alexey is on about is that
> they're too waffle-y. They use wording like "similar to", leaving
> one wondering what discrepancies exist but are being papered over.
> In point of fact, as a look into gram.y will show, what you can
> write after UPDATE ... FROM or DELETE ... USING is *exactly* the
> same thing as what you can write after SELECT ... FROM. So what
> I'm in favor of here is:
>
> * Change the synopsis entries to look like "FROM from_item [, ...]"
> and "USING from_item [, ...]", so that they match the SELECT
> synopsis exactly.
>
> * In the text, describe from_item as being exactly the same as
> it is in SELECT.
>
>
+1

I didn't want a wholesale repetition but the whole "similar to" piece is
indeed my issue and this addresses it sufficiently.

David J.