On Mon, Oct 03 2022, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes:
>
>> On Sat, Oct 01 2022, Junio C Hamano wrote:
>>
>>> Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> 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>..."?
>> 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.
