Fwd: documentation synopsis grammar - Mailing list pgsql-docs

"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.

I understand the motivation .
   This notation considerably shorten the synopsis.
In many cases  it is shiny clear what is the correct grammar.
everybody should know what is repeating in argument list like here:
                 ( [ [ argmode ] [ argname ] argtype [ { DEFAULT | = }
default_expr ] [, ...] ] )
otherwise it is not possible to write any function

the same is with return clause (I hope ):
                  ( column_name column_type [, ...] )
though it is less ofently use .

the problem may arise with with rarely use and/or new features like e.g.:

create table exclude clause (does anybody ude it ? :)  no use of construct
= no complaints)
          EXCLUDE [ USING index_method ] ( exclude_element WITH operator [,
... ] ) index_parameters [ WHERE ( predicate ) ]
if I do not consult bison grammar  I bet  the repeating item comma
separated group is
         exclude_element WITH operator

so the description would be everything at the level of parents (either
round, curly or square) same as "[,... ]" repeats.
      NOTE THAT: some braces are tokens, other are metasymbols.
On the other hand  there is no such thing as "obligatory repetition". So
either the whole list is obligatory or optional.
This can be expressed in adding braces around the list.

so there is no need to use ambiguous symbols [,...]  [...] ... ,...

Last but not least:
When you say the synopsis is for humans (excuse to not to be exact?) .
  ok no problem.
Question is where in documentation is formal syntax definition of language?
gram.y?

What is my actual motivation is to create ANTLR4 grammar . The synopsis is
better starting point than bison .  You simply replace parents by tokens.
next curly braces by parents next you determine what is to be repeated in
[,...] constructs and put it into the  XYZ(,XYZ )? rule  and finally
replace square barces  by ()? construct.

with best wishes Peter







> 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

Hallo Tom

so at first the new explanation is (and should be written  in definition of
notation):