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

From: Junio C Hamano <gitster@pobox.com>
Date: May 18, 2021, 00:51 UTC
Message-ID: <xmqq1ra46f0h.fsf@gitster.g>
In-Reply-To: <60a2daa57d8a6_13c370208f3@natae.notmuch>

Felipe Contreras <felipe.contreras@gmail.com> writes:

Show 17 quoted lines

> Junio C Hamano wrote:
>> Jeff King <peff@peff.net> writes:
>> 
>> > 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.