From: Jean-Noël Avila <jn.avila@free.fr>
Date: Tue, 13 Jan 2026 18:45:36 GMT
Subject: Re: [PATCH 1/1] doc: git-bisect: convert to new doc format
Message-ID: <1CDABB57-6197-49A5-B679-17D56153738C@free.fr>
In-Reply-To: <xmqqqzrtllkw.fsf@gitster.g>

Le 13 janvier 2026 13:54:23 GMT+01:00, Junio C Hamano <gitster@pobox.com> a écrit :
>Jean-Noël AVILA <jn.avila@free.fr> writes:
>
>>>  ------------
>>> -$ git bisect run my_script arguments
>>> +$ git bisect run <my_script> <arguments>
>>>  ------------
>>
>> Here, if you want to use to use the synopsis formatting, you may replace the 
>> verbatim block with a [synopsis] one:
>>
>> [synopsis]
>> $ git bisect run <my_script> <arguments>
>>
>
>Can you add a bit to "if you _want_ to use" above?  What's the
>pros-and-cons of doing so or leaving it as the way it is written in
>the patch?  That would help people on the same page when they decide
>if they want to use the [synopsis], preferring over the verbatim
>block.
>

The rationale is simple: the patch is changing the mode of this section
from a verbatim instance of example to a synopsis model of command.
I'm not settled on whether this is a good move. What is sure though is that 
when writing in synopsis grammar, it is better to switch to synopsis style, in 
order to maintain a consistent output and allow clearer and more direct 
explanations.