From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 07 Nov 2019 05:54:28 GMT
Subject: Re: [PATCH 4/5] doc: commit: unify <pathspec> description
Message-ID: <xmqqk18cqlij.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <6cd64094-d229-ef96-86fd-e64accd759d4@syntevo.com>

Alexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com> writes:

> I think I have implemented most suggestions in PatchV2. Thanks!
>
>> I am not sure if we want to repeat this all over the place.
>>
>> We do not say "For details about the <commit> syntax, see the
>> 'SPECIFYING REVISIONS' section of linkgit:git-rev-parse[1]" for
>> every command that takes <commit> from the command line.
>>
>> Is your urge to suggest adding this sentence coming from that you
>> are much more familiar with <commit> than <pathspec>?  In other
>> words, if you were more familiar with Git, would you still be adding
>> this (and not corresponding one for <commit>)?
>
> Commit is a well known term, dating from ancient times like CVS or
> even older.

That's more or less irrelevant.  

I am reacting to this from your change that you omitted quoting in
your reply:

> +For more details about the <pathspec> syntax, see the 'pathspec' entry
> +in linkgit:gitglossary[7].

That sentence is for those who have some notion of <pathspec> but
does not know enough about its syntax.

CVS does not let you specify <commit> like "master^{/^fix frotz}~4";
A user a user who is familiar with CVS's commits would still want to
refer to the section "For details about the <commit> syntax".

I am not advocating to add the reference to SPECIFYING REVISIONS
section; instead we should let readers know that every time they see
<defined word>, they can refer to the glossary for more details.

> Pathspec, however, is something new.

Compared to CVS, everything in Git may be new, but that was a news
in 2010, not this year.