From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Tue, 19 May 2026 20:57:29 GMT
Subject: Re: [PATCH 1/5] doc: convert git-bisect to synopsis style
Message-ID: <5072065.GXAFRqVoOG@piment-oiseau>
In-Reply-To: <xmqq4ik5d0le.fsf@gitster.g>

On Monday, 18 May 2026 02:26:37 CEST Junio C Hamano wrote:
> "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 ...

In fact, the synopsis style was already applied before outside the SYNOPSIS 
sections in diff-generate-patch.adoc when describing the output of the -p 
option.


This formatting reaches beyond the synopsis, but the rationale is simple. Each 
time a listing contains some <placeholder>, what is actually described is a 
model, not an actual output. The <placeholder> needs a special formatting to 
convey its special meaning.

That may mean that the naming of "synopsis style" may not be adequate.

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

Are they? the "[<rev>]" block is typical of synopsis syntax, not something you 
would actually type in.

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

The '$' is an error to me. Will fix.

> Other than that, this is quite exciting.