Thread: documentation synopsis grammar
Hallo
I search for it and did notsucceeded.
Where is exact definition of the grammar used here?
I thing the text "[,...]" is unclear concerning what is to be repeted.
here:
you state
" Dots (...) mean that the preceding element can be repeated. "
from that definition the fragment "[,...]" means zero or more commas.
It is often so that not one element but several elements are repeated .
Sometimes from the context, one may find out how it is meant.
In other cases it not so clear .
Well do you have a definition or third party standard?
Thank you very much,Peter Korim.
On Friday, May 11, 2018, Peter Korim <pkorim@gmail.com> wrote:
HalloI search for it and did notsucceeded.Where is exact definition of the grammar used here?I thing the text "[,...]" is unclear concerning what is to be repeted.
Not that I've found, do you have an example?
here:you state" Dots (...) mean that the preceding element can be repeated. "from that definition the fragment "[,...]" means zero or more commas.It is often so that not one element but several elements are repeated .
In which case each one requires a comma separating it from the previous one.
Sometimes from the context, one may find out how it is meant.
In other cases it not so clear.
Again, You will need to point out an example. But not all options that allow multiples require commas to separate them.
Well do you have a definition or third party standard?
You linked to it above...
David J.
On Friday, May 11, 2018, David G. Johnston <david.g.johnston@gmail.com> wrote:
On Friday, May 11, 2018, Peter Korim <pkorim@gmail.com> wrote:HalloI search for it and did notsucceeded.Where is exact definition of the grammar used here?I thing the text "[,...]" is unclear concerning what is to be repeted.Not that I've found, do you have an example?
Ok, I think I get your confusion now...
ANALYZE [ VERBOSE ] [ table_name [ ( column_name [, ...] ) ] ]
column_name can be repeated. If it is each name is separated from the previous one by a comma. The brackets indicate optional repetition of the immediately preceding element. The presence or absence of a comma in the bracket indicates whether each option repeat needs a comma separator. It's not the comma that is being repeated.
David J.
Please keep communications on-list.
On Fri, May 11, 2018 at 3:05 PM, Peter Korim <pkorim@gmail.com> wrote:
Ok Davidby your definition and following synopsis:CREATE [ OR REPLACE ] FUNCTIONname ([ [ argmode ] [ argname ] argtype [ { DEFAULT | = } default_expr ] [, ...] ] )should be valid this:CREATE [ OR REPLACE ] FUNCTIONname ( argtype = default_expr , = default_expr , = default_expr )
But it obviously isn't...
I suppose the [, ...] could be placed after the "]" to its right...but the only mandatory element in that [] block is "argtype" so the [, ...] refers to it (or rather, everything in between the [ ] of which it is a part.
(argtype, argtype, argtype)
Each one of those argtype values can be surrounded by any of the optional elements surrounding it in the syntax. The whole part between the ( ) being optional, hence the idiomatic ( [ ] ) syntax.
These are written by humans for humans - and in some cases do take a bit of thinking (and, sometimes, reading the descriptions about the items in question) about what ultimately makes sense to understanding exactly what might or might not be valid.
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. Trying to describe exactly how that [, ...] works in the presence of mandatory and optional parts is likely to add, not reduce, confusion. As its stands "..." means repetition is possible and you, the, reader, are assumed to figure out what exactly is repeatable. You'll likely get a syntax error quickly if you guess wrong and these lists are very responsive if you get stumped.
You are welcome to suggest corrections to the documentation, and even better, submit patches, if you find the existing conventions/notations page unconscionably lacking.
David J.
"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. regards, tom lane
"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):
> 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