Re: [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Oct 4, 2022, 07:50 UTC
Message-ID: <221004.86fsg4t3x2.gmgdl@evledraar.gmail.com>
In-Reply-To: <xmqqczb8yk8h.fsf@gitster.g>

On Mon, Oct 03 2022, Junio C Hamano wrote:

Show 20 quoted lines

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> On Sat, Oct 01 2022, Junio C Hamano wrote:
>>
>>> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>>>
>>>> For "rerere" say "pathspec" consistently, and list the subcommands in
>>>> the order that they're discussed in the "COMMANDS" section of the
>>>> documentation.
>>>
>>> pathspec refers to the entire set of patterns, which consists of one
>>> or more "pathspec element"s, so there is no need for "..." there.
>>
>> Maybe I'm misreading this, but are you suggesting that whenever
>> "<pathspec>" appears in the text the user should understand it as
>> "<pathspec>...", i.e. as is the case with the special-case that is
>> "<options>".
>
> Not really.  A <pathspec> is a set of <pathspec element>s, so
> writing "<pathspec-element>..." and "<pathspec>" are equivalent.

So, "yes"? I.e. leaving aside "pathspec" or "pathspec-element" "<pathspecs>" is redundant to "<pathspecs>..." in this intpreretation? But for any given "<x>" the "<x>" is not the same as "<x>..."?

Show 20 quoted lines

>> I'm not opposet do that, but I really wish we could avoid further
>> special-cases, there's no current user of "<pathspecs>" (with an "s" for
>> plural.
>
> Presumably just like range-diff compares two ranges (which in the
> normal command line syntax we would not have), some future commands
> may need to take two pathspecs (that is two sets of patterns to
> match paths) to do something interesting, but I do not think of
> anything that does so in the current command set, so it is very good
> that nobody claims to take <pathspecs> with an "s"for plural.
>
>> 	Documentation/git-clone.txt:--recurse-submodules[=<pathspec>]::
>>
>> Should be read as supporting:
>>
>> 	--recurse-submodules some/path some-other-path
>
> Yup, the option should support it, alternatively it could take
> <path>.  Or it could take multiple of these options in which case
> each of them is taking a pathspec element.

In bourne shell syntax we're talking about the distinction between:

	$ echo --opt {a,b}
	--opt a b

And:

	$ echo --opt={a,b}
	--opt=a --opt=b

Which in the SYNOPSIS syntax are (asuming "a", and "b" are <byte>), respectively:

	--opt <byte>...

And:

	[--opt <byte>]...

If we maintain that for a given "<label>" that it has an implicit "..." after it I don't see how you can distingish these two by way of explaining how the command works via the syntax. I.e. it's possible (and we even have some obscure code in-tree that does this) to support e.g.:

	--opt a b c --opt d e f g h --opt i --opt j

Which, if (in my wordview) would be explained with this syntax:

	[--opt <byte>...]...

But that's really not what we mean most of the time, we *don't* want that "..." on the argument to "--opt", because it only takes one argument.