Re: Bug report: Documentation error in git-bisect man description

[Manuel Ullmann <ullman.alias@posteo.de>]

> On Fri, Jan 13, 2017 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> Manuel Ullmann <ullman.alias@posteo.de> writes:
>>>
>>> Hmmm, I tend to agree, modulo a minor fix.
>>>
>>> If the description were in a context inside a paragraph like this:
>>>
>>>       When you want to tell 'git bisect' that a <rev> belongs to
>>>       the newer half of the history, you say
>>>
>>>               git bisect (bad|new) [<rev>]
>>>
>>>       On the other hand, when you want to tell 'git bisect' that a
>>>       <rev> belongs to the older half of the history, you can say
>>>
>>>               git bisect (good|old) [<rev>]
>>>
>>> then the pairing we see in the current text makes quite a lot of
>>> sense.
>>
>> Actually, the above is _exactly_ what was intended.  I misread the
>> current documentation when I made the comment, and I think that the
>> current one _IS_ correct.  The latter half of the above is not about
>> a single rev.  You can paint multiple commits with the "older half"
>> color, i.e.
>>
>>         On the other hand, when you want to tell 'git bisect' that
>>         one or more <rev>s  belong to the older half of the history,
>>         you can say
>>
>>                 git bisect (good|old) [<rev>...]
>>
>> In contrast, you can mark only one <rev> as newer (or "already
>> bad").  So pairing (bad|good) and (new|old) like you suggested
>> breaks the correctness of the command line description.
>
> Yeah, I agree.
>
>> If (bad|new) and (good|old) bothers you because they may mislead the
>> readers to think bad is an opposite of new (and good is an opposite
>> of old), the only solution I can think of to that problem is to
>> expand these two lines into four and list them like this:
>>
>>         git bisect bad [<rev>]
>>         git bisect good [<rev>...]
>>         git bisect new [<rev>]
>>         git bisect old [<rev>...]
>
> Maybe it would be more complete and a bit clearer if it was:
>
>            git bisect (bad|new|<term-new>) [<rev>]
>            git bisect (good|old|<term-old>) [<rev>...]

That would clarify the intention quite a bit (at least for me).

Best regards,
Manuel