Thread: Inconsistent application of [, ...] in documentation
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:
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 SCHEMAschema_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 SCHEMAschema_name[, ...] } TOrole_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
On Wed, Jan 27, 2021 at 10:37 AM Oliver Rice <oliver@oliverrice.com> wrote:
"( 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.
But (TEXT, TEXT) is valid.
The reality is that there is a trade-off between explicitness and readability (human usability). Complaints strictly about inconsistency are not going to be acted upon. Specific documentation will be improved upon given sufficient demonstration of a usability problem AND the available of a more usable alternative. That the wrong choice will simply "fail fast" in cases where the capturing of the repetition is ambiguous, and there are examples to make clear which is correct, causes one to err on the side of readability for the synopsis (which is unique to each command) rather than consistency between commands.
David J.
Would contributions to synopsis documentation attempting to increase consistency and accuracy be considered provided they don't negatively impact readability?
Oliver
On Wed, Jan 27, 2021 at 11:59 AM David G. Johnston <david.g.johnston@gmail.com> wrote:
On Wed, Jan 27, 2021 at 10:37 AM Oliver Rice <oliver@oliverrice.com> wrote:"( 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.But (TEXT, TEXT) is valid.The reality is that there is a trade-off between explicitness and readability (human usability). Complaints strictly about inconsistency are not going to be acted upon. Specific documentation will be improved upon given sufficient demonstration of a usability problem AND the available of a more usable alternative. That the wrong choice will simply "fail fast" in cases where the capturing of the repetition is ambiguous, and there are examples to make clear which is correct, causes one to err on the side of readability for the synopsis (which is unique to each command) rather than consistency between commands.David J.
On Wed, Jan 27, 2021 at 3:16 PM Oliver Rice <oliver@oliverrice.com> wrote:
Would contributions to synopsis documentation attempting to increase consistency and accuracy be considered provided they don't negatively impact readability?
Do a couple and see what happens.
David J.