| From: | "David G(dot) Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com> |
|---|---|
| To: | Oliver Rice <oliver(at)oliverrice(dot)com> |
| Cc: | PostgreSQL mailing lists <pgsql-bugs(at)lists(dot)postgresql(dot)org> |
| Subject: | Re: Inconsistent application of [, ...] in documentation |
| Date: | 2021-01-27 17:59:38 |
| Message-ID: | CAKFQuwZH_OdMKexkN5bVOiSQ_U6oGJus9WVCTQyFgLC3yPB8pQ@mail.gmail.com |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-bugs |
On Wed, Jan 27, 2021 at 10:37 AM Oliver Rice <oliver(at)oliverrice(dot)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.
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Tom Lane | 2021-01-27 18:08:34 | Re: BUG #16840: Rows not found in table partitioned by hash when not all partitions exists |
| Previous Message | Oliver Rice | 2021-01-27 17:27:41 | Inconsistent application of [, ...] in documentation |