Re: [PATCH 1/1] doc: git-bisect: convert to new doc format

From: Jean-Noël Avila <jn.avila@free.fr>
Date: Jan 13, 2026, 18:45 UTC
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 :

Show 20 quoted lines

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