From: Phillip Wood <phillip.wood123@gmail.com>
Date: Fri, 28 Jul 2023 09:45:12 GMT
Subject: Re: [PATCH] ls-tree: fix --no-full-name
Message-ID: <b17b4f6b-199f-973b-3aa9-ef995a61bb3d@gmail.com>
In-Reply-To: <a19879db-d45a-ee42-1ad5-497e4e9eb8df@web.de>

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"

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.

Best Wishes

Phillip