Re: documentation synopsis grammar

> On May 11, 2018, at 8:15 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> "David G. Johnston" <david.g.johnston@gmail.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.

Perhaps a way around it is having more practical examples that highlight
the way the language can be used.  Even with an understanding of the
PostgreSQL, let alone SQL, syntax, I find that I continue to learn things
the language can do even to this day when I see an example. Sometimes
the grammar masks a lot of the power :-)

I would think changing the grammar at this point would cause even more
confusion, but more examples to capture the power should shed more
light on how to do things.

Jonathan