Re: [PATCH 1/5] doc: convert git-bisect to synopsis style
- From
Junio C Hamano <gitster@pobox.com>
- Date
- May 18, 2026, 00:26 UTC
- 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:
Show 5 quoted lines
> 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 ...
Show 12 quoted lines
> 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.