Re: Inconsistent application of [, ...] in documentation

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(dot)g(dot)johnston(at)gmail(dot)com> wrote:

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