Inconsistent application of [, ...] in documentation

From: Oliver Rice <oliver(at)oliverrice(dot)com>
To: pgsql-bugs(at)lists(dot)postgresql(dot)org
Subject: Inconsistent application of [, ...] in documentation
Date: 2021-01-27 17:27:41
Message-ID: CAKYAq67vavWsuaPGwqmT7K7n1wPEGZZxSKv4LH_dDG0j08q04A@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-bugs

Hi,

In the "Synopsis" part of "SQL Commands" section of the docs the "[, ...]"
token appears to be applied inconsistently to either the preceding 1 token,
or all preceding tokens within the same group.

For example:
https://www.postgresql.org/docs/13/sql-grant.html

*Variant A*:

GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER }
[, ...] | ALL [ PRIVILEGES ] }
ON { [ TABLE ] *table_name* [, ...]
| ALL TABLES IN SCHEMA *schema_name* [, ...] }
TO *role_specification* [, ...] [ WITH GRANT OPTION ]

Relevant Extract:
"ALL TABLES IN SCHEMA *schema_name* [, ...]"

Correct Usage:

"ALL TABLES IN SCHEMA public, api_v1"

Incorrect Usage:

"ALL TABLES IN SCHEMA public, ALL TABLES IN SCHEMA api_v1"

*Variant B:*
GRANT { EXECUTE | ALL [ PRIVILEGES ] }
ON { { FUNCTION | PROCEDURE | ROUTINE } *routine_name* [ ( [ [
*argmode* ] [ *arg_name* ] *arg_type* [, ...] ] ) ] [, ...]
| ALL { FUNCTIONS | PROCEDURES | ROUTINES } IN SCHEMA
*schema_name* [, ...] }
TO *role_specification* [, ...] [ WITH GRANT OPTION ]

Relevant Extract:
"( [ [ *argmode* ] [ *arg_name* ] *arg_type* [, ...] ] )"

Correct Usage:

"( first_param TEXT, second_param TEXT )"

Incorrect Usage:

"( first_param TEXT, TEXT)"

--

So in Variant A, "[, ...]" is intended to apply to the immediately
preceding token but in variant B it is intended to apply to all
preceding tokens in the same group.

Thank you,

Oliver

Responses

Browse pgsql-bugs by date

  From Date Subject
Next Message David G. Johnston 2021-01-27 17:59:38 Re: Inconsistent application of [, ...] in documentation
Previous Message Michał Albrycht 2021-01-27 17:19:47 Re: BUG #16840: Rows not found in table partitioned by hash when not all partitions exists