Re: Re* [PATCH] doc: glossary: add entry for revision range

Felipe Contreras [off-list ref] writes:

Junio C Hamano wrote:

quoted

Jeff King [off-list ref] writes:

quoted

I agree that if the purpose is to be illustrative, using shortcuts like
"an empty endpoint means HEAD" is not helpful. And likewise for "@"; if
you need to have "revision range" defined, there is a good chance that
you don't know about shortcuts like "@" either.

So I would prefer something more explicit (whether it's "mybranch" or
"end" or "HEAD" or whatever).

Perhaps.  Being illustrative for common use case is also important,
so I do not mind teaching "missing endpoint at either side defaults
to HEAD" early.

A glossary is not a place to teach (anything other than the definition).
It's supposed to contain glosses (brief explanations).

Fair enough.  Then let's limit ourselves to the definition, but give
a correct one.  It is not "syntax" that the phrase "revision range"
refers to; it is what is specified by that syntax.

[[def_revision_range]]revision range::
        A set of connected commits to work on, usually specified by
        giving two end points, like `origin..mytopic`.  See the
        'Specifying Ranges' and 'Revision Range Summary' sections of
        linkgit:gitrevisions[7] for details.

Junio C Hamano wrote:

Felipe Contreras [off-list ref] writes:

quoted

Junio C Hamano wrote:

quoted

quoted

Perhaps.  Being illustrative for common use case is also important,
so I do not mind teaching "missing endpoint at either side defaults
to HEAD" early.

A glossary is not a place to teach (anything other than the definition).
It's supposed to contain glosses (brief explanations).

Fair enough.  Then let's limit ourselves to the definition, but give
a correct one.  It is not "syntax" that the phrase "revision range"
refers to; it is what is specified by that syntax.

That's a distinction without a difference.

Like saying "Felipe is a person" is wrong, because "Felipe" is not a
person, but the _name_ of a person. This is excessive concern with minor
details to me.

In the minds of most people object identifiers are used interchangeably
with the object themselves: "Felipe" is a person, "master" is a branch, and
"master..@" is a revision range.

[[def_revision_range]]revision range::
        A set of connected commits to work on, usually specified by
        giving two end points, like `origin..mytopic`.

endpoints.

As for the rest I already raised my concerns.

Cheers.

-- 
Felipe Contreras