Date: Wed, 7 Jul 2021 12:30:09 -0400
From: rir <rirans@comcast.net>
To: Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: conventions
Message-ID: <20210707163009.44wpfn7uc72zwyp7@localhost>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: NeoMutt/20180716
Archived-At: 
 <https://www.postgresql.org/message-id/20210707163009.44wpfn7uc72zwyp7%40localhost>
Precedence: bulk


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