"David G. Johnston" <david.g.johnston@gmail.com> writes: > On Thu, Feb 13, 2020 at 4:13 AM Alexey Bashtanov <bashtanov@imap.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.
