Am 28.07.23 um 11:45 schrieb Phillip Wood:
> On 28/07/2023 07:12, René Scharfe wrote:
>>>> Right. Perhaps --[[no-]no-]doubt? Looks a bit silly with its nested
>>>> brackets, but it's more correct, because it documents all three accepted
>>>> forms, including the no-less one.
>>>
>>> It may look a bit silly but looks very tempting. Also it is not
>>> much longer than "--[no-]no-doubt".
>>
>> Yes, it's quite compact. But is it they still legible?
>>
>> --no-index find in contents not managed by git
>> --[no-]no-index find in contents not managed by git
>> --[[no-]no-]index find in contents not managed by git
>> --[no-[no-]]index find in contents not managed by git
>>
>> The last two document all three variants, but is it still obvious that
>> the help text is supposed to be about the one with a single "no-"?
>> That's something that has to be learned, I suspect. No good making the
>> short help too cryptic. Hmm, how about:
>>
>> --no-index, --[no-[no-]]index
>> find in contents not managed by git
>
> I think spelling out the positive and negative options separately
> makes it much clearer, but in that case I think we'd be better just
> to show
>
> --no-index, --index
>
> adding "[no-[no]]" is just going to confuse users. If we had a
> convention of "[<short>, ]<positive long>; <negative long>" then I
> think it should be clear to users how to negate a given option
>
> -v, --invert-match; --no-invert-match
> show non-matching lines
> -I, --no-index; --index find in contents not managed by git
>
> Spelling out both versions is a bit verbose but I think it is worth
> it to avoid "--[no-]no-index"
I kinda like it, even though it is quite verbose and adds a new syntax
element.
A bit more verbose still: Document the negative form on its own line
with a generated description -- requires no new syntax:
-v, --invert-match show non-matching lines
--no-invert-match opposite of --invert-match, default
-I, --no-index find in contents not managed by git
--index opposite of --no-index, default
> One other thought is to mark options that can be negated with a
> symbol like '*' and add a footnote saying those options can be
> negated.
Sure, adding a layer of indirection would work.
All these imperfect solutions make me wish we could get rid of the
problem, e.g. by converting all "no-" options to their positive variants
and mentioning that they are the default. Won't fly, though, because
some of them have short forms, and we don't follow the convention of
uppercase short options negating lowercase ones, so we have to document
them anyway.
René
