From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 18 May 2026 00:26:37 GMT
Subject: Re: [PATCH 1/5] doc: convert git-bisect to synopsis style
Message-ID: <xmqq4ik5d0le.fsf@gitster.g>
In-Reply-To: <dca7f192f1e5cdfb57682feace0a4b3a10204376.1779049615.git.gitgitgadget@gmail.com>

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> Convert Documentation/git-bisect.adoc to the modern synopsis style.
>
> - Replace [verse] with [synopsis] in the SYNOPSIS block

This was expected.

> - Remove single quotes around command names in the synopsis
> - Use backticks for inline commands, options, refs, and special values
> - Apply [synopsis] attribute to in-body command-form code blocks

This is very much unexpected.  I think everybody thought [synopsis]
was invented to be used for the SYNOPSIS section at the beginning of
each manual page, and ...

>  SYNOPSIS
>  --------
> -[verse]
> -'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
> -		   [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
> ...
> -'git bisect' help
> +[synopsis]
> +git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
> +		 [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
> ...
> +git bisect help

... a change like this is very much expected and understandable, but
new appearances of [synonsis] in places like:

> +[synopsis]
>  ------------------------------------------------
>  $ git bisect reset <commit>
>  ------------------------------------------------

and

> +[synopsis]
>  ------------------------------------------------
>  git bisect old [<rev>]
>  ------------------------------------------------

were a bit surprising and confusing.  They are not exactly command
syntax definitions (which is the SYNOPSIS section is about), but
examples of usage.  The one with '$' command line prompt feels
particularly confusing, as the prompt is not something that the
end-user gives, unlike what we write in the synopsis section.

Other than that, this is quite exciting.