Synopsis notation
Is the notation used in the sql command pages covered in the Pg docs or elsewhere? With my limited experience, I don't recognize the notation. rir
conventions
The conventions page is weak. Here is a proposed start for
change. Seeing SQL as an early language, I have tried to use something
like plain English. Here "early" could describe a mail merge user
wandering into programming SQL after seeing some simple examples.
I like the idea of accessibility but I may have been overly influenced
by the tone of the existing page. I tried to express the idea of
operators and that "repeaters" could/should be viewed as tokens.
I am not sure if parenthetical groups are degenerate in their
behavior pertaining to their contents. It seems they take the op's
on the outside.
Thanks,
rob
Conventions
The conventions used in the synopses of commands vary with the language
being presented.
SQL
The conventions for SQL synopses consist of placeholders, groups,
repeaters and the alternator.
Placeholders are bold, italicized names for SQL code. Often the
placeholder's definition or syntax is is introduced and presented
later in the synopsis. When not defined, there are three possible
reasons:
1. The placeholder is self-evident, i.e. "name" being more helpful
in giving the intent of the code than "sql_identifier".
2. The placeholder is a common SQL construct explained elsewhere,
i.e. "expression".
3. The placeholder is arcane or requires knowledge beyond SQL;
the commonest cases involve creating or altering C language
code.
In the above cases, the page's explanatory text should help.
Square brackets ([ and ]) create optional groups.
Pointy braces ({ and }) create required groups. To date, only alternative
lists exist inside braces.
Parentheses (( and )) are to be taken literally as part of the SQL code,
but also group parts.
The bar or pipe (|) is the alternator, it separates lists of alternatives
which require one choice.
The ellipsis (...) is the basic repeater, all repeaters indicate some
repetition of the prior group, symbol or word. The basic repeater
requires at least one repetition.
The ellipsis in square brackets ([ ... ]) indicates an optional
repetition.
The other repeaters are special usages of square brackets to create
repeaters that contain a separator that goes between the repetitions.
These are ([, ...]), ([ OR ...]) and ([ AND ...]).
PL/pgSQL
XXX See SQL above.
PL/Tcl
...
PL/Perl
...
PL/Python
...
Pg notation
Hello all, If there is no interest in a more formalized Postgres notation then reading this is a waste of your time. But accept the compliment that all the doc/src/sgml/ref/.sgml synopses are well and nicely done. I turned to your documentation pages' synopses to create a _very_ partial grammar for Pg SQL in Raku; just addressing pertinent commands in a small codebase. Simple stuff. I went down a rabbit hole. So now there is a grammar that could start formalizing and linting Pg's notation language in its SGML form. It uses added tags to identify and isolate commands, subrules, etc. and relies on the existing tags in and around the "Where" phrases. The added tags unambiguously define part of the notation while not restraining the visual layout to pre-existing models. The tags greatly simplify the parsing because the grammar doesn't need to identify the specific command being parsed. Rewriting the doc/src/sgml/notation.sgml file is within my ability with a monkey-see-monkey-do approach to SGML. The variations of the "Where X is:" phrases might be halved by using standard phrasing. I think that would be noticed by few readers. Mostly, this is at the "X may be:" versus "X is:" level. My purpose was to learn about parsing, more Raku, and a little more SQL. That was a success. I did not consider that I would be steeping myself in the notation language. I am temporarially a quasi-expert of trivia like there are 19 "[ , ... ]" usages--the least common form of the repeat-with-comma rule. Thanks for being Postgresql, Rob
create event trigger docs
The CREATE EVENT TRIGGER synopsis uses the bare word 'filter_value' when it seems filter_variable was intended. Thanks again.
small patch
Minor changes to move.sgml and fetch.sgml. The text 'or empty' is inconsistent by restating what the synopsis notation has expressed. The comments on sharing a language feature, while likely helpful during review, seem verbose compared to the non-commenting in other similar files. Thanks again, Rob :From a297377ad3b760f10e951cf67ad0cea704214f34 Mon Sep 17 00:00:00 2001 From: rir Date: Wed, 29 Sep 2021 19:06:01 -0400 Subject: [PATCH] "empty or" is unusual and redundant --- doc/src/sgml/ref/fetch.sgml | 4 ++-- doc/src/sgml/ref/move.sgml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml index ec843f5684..e76b6fc69d 100644 --- a/doc/src/sgml/ref/fetch.sgml +++ b/doc/src/sgml/ref/fetch.sgml @@ -25,11 +25,11 @@ PostgreSQL documentation - + FETCH [ direction [ FROM | IN ] ] cursor_name -where direction can be empty or one of: +where direction can one of: NEXT PRIOR diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml index 4c7d1dca39..1ed06e4c9a 100644 --- a/doc/src/sgml/ref/move.sgml +++ b/doc/src/sgml/ref/move.sgml @@ -25,11 +25,11 @@ PostgreSQL documentation - + MOVE [ direction [ FROM | IN ] ] cursor_name -where direction can be empty or one of: +where direction can one of: NEXT PRIOR -- 2.20.1
Re: small patch
On Mon, Oct 04, 2021 at 08:18:22AM +0200, Laurenz Albe wrote: > On Fri, 2021-10-01 at 21:06 -0400, rir wrote: > > Minor changes to move.sgml and fetch.sgml. > > > > The text 'or empty' is inconsistent by restating what the > > synopsis notation has expressed. > > > > The comments on sharing a language feature, while > > likely helpful during review, seem verbose compared to > > the non-commenting in other similar files. > > Thanks for the effort of preparing a patch. > > However, I don't think that is an improvement: > > - the comments pointing from MOVE to FETCH and vice versa are > helpful for people who edit the documentation like you did > - we should retain "empty or one of", otherwise the following syntax > would be undocumented: > > FETCH FROM c; > Yours, > Laurenz Albe Laurenz, Your view is completely reasonable, but it suggests that many of the synopses are leaving syntax undocumented. The 'empty or one of:' is only used in these two synopses. If I had found the comments helpful, I would have spared them. My sense was that the comments were unusual by their existence for their purpose. That was not rigorous: so okay. Since I'm only making the same points again, I'll stop. Thanks again, Rob
Re: small patch
On Thu, Oct 07, 2021 at 07:58:47AM +0200, Laurenz Albe wrote: > On Wed, 2021-10-06 at 23:39 -0400, rir wrote: > > On Mon, Oct 04, 2021 at 08:18:22AM +0200, Laurenz Albe wrote: > > > On Fri, 2021-10-01 at 21:06 -0400, rir wrote: > > > > Minor changes to move.sgml and fetch.sgml. > > > However, I don't think that is an improvement: > > > > > > - the comments pointing from MOVE to FETCH and vice versa are > > > helpful for people who edit the documentation like you did > > > - we should retain "empty or one of", otherwise the following syntax > > > would be undocumented: > > > > > > FETCH FROM c; > > > > Your view is completely reasonable, but it suggests that > > many of the synopses are leaving syntax undocumented. > > The 'empty or one of:' is only used in these two synopses. > Can you think of a way to modify the syntax diagram so that it > expresses that and still remains comprehensible? For myself, 'FETCH [ [ FROM | IN ] ] ' clearly indicates that 'direction' is optional. Rob
Re: small patch
On Thu, Oct 07, 2021 at 04:24:16PM -0400, Tom Lane wrote: > rir writes: > > On Thu, Oct 07, 2021 at 07:58:47AM +0200, Laurenz Albe wrote: > >> Can you think of a way to modify the syntax diagram so that it > >> expresses that and still remains comprehensible? > > > For myself, > >'FETCH [ [ FROM | IN ] ] ' > > clearly indicates that 'direction' is optional. > > FETCH FROM cursor_name > > which in fact is legal. I think however that we could make it read > > FETCH [ ] [ FROM | IN ] ' > > and have a correct description without requiring > to be allowed to be empty. > BTW, as it stands, the diagram is ambiguous > because there are two ways to parse > > FETCH cursor_name > > ... is present but empty, or omitted altogether? I am confident you know what you mean, but I don't. At the _parsing_ stage how is any distinction between emptiness and omission? I can correct the patch to reflect the rightness of FETCH [ ] [ FROM | IN ] in the sgml file and at least one misquote I have found. Not being here that often, I will wait to see this conversation resolve. Rob
Re: small patch
On Fri, Oct 08, 2021 at 02:47:43PM +0200, Laurenz Albe wrote: > On Thu, 2021-10-07 at 16:06 -0400, rir wrote: > So I suggest that you change the syntax diagram to > > FETCH [ direction ] [ FROM | IN ] cursor_name > Then I agree that the "empty or" can be removed. > I remain of the opinion that the comments should be > retained, but we can leave that for somebody else to > decide. I accept your three points above. The MOVE synopsis shows the same parsing as I presented, should it be changed in the same way (move a square bracket left to be after )? My guess is yes, but I've never used an SQL cursor. When this convo settles, I send a new patch. Probably here in the group. If I have a few more, or a complex one, I'll check out the other submission method. Rob
Re: small patch
On Sun, Oct 10, 2021 at 04:15:01PM -0400, rir wrote: > On Fri, Oct 08, 2021 at 02:47:43PM +0200, Laurenz Albe wrote: > > On Thu, 2021-10-07 at 16:06 -0400, rir wrote: > > FETCH [ direction ] [ FROM | IN ] cursor_name Should the pgplsql docs be similiarly changed per the above in 43.7.3.1 and 2? Rob
Re: small patch
On Tue, Oct 12, 2021 at 08:43:34AM +0200, Laurenz Albe wrote: > On Mon, 2021-10-11 at 23:14 -0400, rir wrote: > > On Sun, Oct 10, 2021 at 04:15:01PM -0400, rir wrote: > > > On Fri, Oct 08, 2021 at 02:47:43PM +0200, Laurenz Albe wrote: > > > > On Thu, 2021-10-07 at 16:06 -0400, rir wrote: > > > > > > FETCH [ direction ] [ FROM | IN ] cursor_name > > > > Should the pgplsql docs be similiarly changed per the above > > in 43.7.3.1 and 2? > > Absolutely! > > It may even make sense to extend the existing comments to > alert people who modify the syntax diagram in the future > that they should also consider reviewing the PL/pgSQL syntax. I will make the syntax change. Since my understanding is that, absent contrary documentation, plpgSQL follows SQL, I resist the idea of yet another comment. Better would be establishing a SPoT, tagging it, and tagging various forms of derived info as quotes, code samples, etc. or, at worst, logically dependent. This more form of commenting could allow linting processes to support its use and check its accuracy. Absent that ... Rob
