Re: [PATCH] doc/git-bisect: clarify `git bisect run` syntax

From: Javier Mora <cousteaulecommandant@gmail.com>
Date: Oct 23, 2023, 16:27 UTC
Message-ID: <CAH1-q0hrfROfQROXGoCfde4MFkEjxjSMneDcqLO1pqYpe+bN9g@mail.gmail.com>
In-Reply-To: <ZTYi55w_70ZlP8Ew@tanuki>

> The output of `git bisect -h` suffers the same problem. Perhaps this
> patch can fix that, as well?

Certainly possible. Probably best if I put that on a second patch though (i.e. a separate commit). Or should I just squash everything together?

There are still multiple .po files containing the old string, I guess I don't need to touch those?

Speaking of which, looking at the .po files I've found that there's also a `git bisect--helper` command; I don't know if that's relevant nor how to modify that.

> I wonder if we should eventually move these into the
> proper SYNOPSIS section.

Seems reasonable.  I was actually wondering about that.

I can make an extra patch for that if you want, while I'm at it.

> If we don't want them to drift apart I wonder whether we could instead
> generate the synopsis from the output of `-h`? This reduces duplication

That's not a bad idea. Or maybe the other way around -- generate the output of `-h` from the synopsis. Or generate both (manpage and help message) from a "synopsis stub" file; I wonder if that could be easily done.

El lun, 23 oct 2023 a las 8:38, Patrick Steinhardt (<ps@pks.im>) escribió:

Show 49 quoted lines

>
> On Sun, Oct 22, 2023 at 05:35:41PM -0700, Junio C Hamano wrote:
> > Eric Sunshine <sunshine@sunshineco.com> writes:
> >
> > > On Sun, Oct 22, 2023 at 4:03 PM cousteau via GitGitGadget
> > > <gitgitgadget@gmail.com> wrote:
> > >> The description of the `git bisect run` command syntax at the beginning
> > >> of the manpage is `git bisect run <cmd>...`, which isn't quite clear
> > >> about what `<cmd>` is or what the `...` mean; one could think that it is
> > >> the whole (quoted) command line with all arguments in a single string,
> > >> or that it supports multiple commands, or that it doesn't accept
> > >> commands with arguments at all.
> > >>
> > >> Change to `git bisect run <cmd> [<arg>...]` to clarify the syntax.
> > >
> > > Okay, makes sense.
> > >
> > >> Signed-off-by: Javier Mora <cousteaulecommandant@gmail.com>
> > >> ---
> > >> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
> > >> @@ -26,7 +26,7 @@ on the subcommand:
> > >> - git bisect run <cmd>...
> > >> + git bisect run <cmd> [<arg>...]
> > >
> > > The output of `git bisect -h` suffers the same problem. Perhaps this
> > > patch can fix that, as well?
> >
> > Good eyes.
> >
> > Not a new problem and obviously can be left outside of this simple
> > update, but I wonder if we should eventually move these into the
> > proper SYNOPSIS section.  Other multi-modal commands like "git
> > checkout", "git rebase", etc. do list different forms all in the
> > SYNOPSIS section.
> >
> > I also thought at least some commands we know the "-h" output and
> > SYNOPSIS match, we had tests to ensure they do not drift apart.  We
> > would probably want to cover more subcommands with t0450.
> >
> > Thanks.
>
> If we don't want them to drift apart I wonder whether we could instead
> generate the synopsis from the output of `-h`? This reduces duplication
> at the cost of a more complex build process for our manpages.
>
> Not saying that this is necessarily a good idea, just throwing it out
> there.
>
> Patrick