Re: documentation synopsis grammar

"David G. Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com> writes:
> I'm suspecting that our best bet is leave the notation page a bit vague and
> just clear up confusion when it arises. The example above, while probably
> technically incorrect, is, I'm reasonably certain, common and saying its
> wrong and fixing it is unlikely to happen given the rarity of questions
> like this.

Yeah; a quick grep suggests that there are several hundred occurrences
of this notation in our reference pages alone. Even if somebody were
initially confused, they'd soon figure it out, I should think. Certainly
we've had few if any complaints about this point before.

The bigger question though is, if we don't like this notation, what
notation would we replace it with? We could be formally correct by
rewriting all of these syntax synopses in BNF, but I think most people
are not terribly familiar with that and would be more confused, not less.
Our actual bison grammar, which is BNF-equivalent I think, is certainly
arcane enough to scare off non-experts.

There was a related discussion recently:

https://www.postgresql.org/message-id/flat/152110913499.1223.7026776990975251345%40wrigleys.postgresql.org

The problems discussed there with our description of set-operation syntax
are really a lot worse than this issue, I think. And yet we still opted
not to change the documentation, because it seemed that anything that's
more formally correct would also be a lot more incomprehensible.

I don't want to sound like I think what we've got now is the peak of
perfection, because it isn't. But we have to strike a balance between
formal correctness and readability for users who aren't familiar with
formal syntax notations. It's a difficult problem.

regards, tom lane