Re: [PATCH 4/5] doc: commit: unify <pathspec> description

From: Alexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com>
Date: Nov 7, 2019, 11:39 UTC
Message-ID: <ffcc5857-a6c8-1cf5-f5b6-334e778c576c@syntevo.com>
In-Reply-To: <xmqqk18cqlij.fsf@gitster-ct.c.googlers.com>

On 07.11.2019 6:54, Junio C Hamano wrote:

Show 8 quoted lines

> 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.

In the perfect world, I would expect _every_ 'pathspec' word in text to be an HTML-style link to a dedicated article, not just a paragraph in glossary.

MSDN is in general a good example [1]: there, it's easy to read only a small portion of article, ignoring anything you're not interested in, and still have all links at hand.

Regarding dedicated page: the content of 'pathspec' in glossary is already long enough for a page, and it could benefit from additional examples. Also, having a dedicated page makes linking easier, so that user doesn't have to scroll glossary.

Regarding links: I don't really understand what git's doc format allows. Is it just pure text in worst (or even average) case?

If it's usually something with clickable links, it could be worth to just insert links everywhere.

If it's usually plaintext, then "see the 'pathspec' entry in linkgit:gitglossary[7]" is a bit too verbose to repeat on every occasion. Still, I'd like to see links everywhere. One big reason is to let reader know that the explanation actually exists!

A compromise solution is to give every article header like this:

     This article uses the following terms which are explained
     in linkgit:gitglossary[7]:
     * pathspec
     * tree-ish
     * refspec

If it's close to top of article, then chances are that everyone will notice it. Also, it will not require extra verbosity in plaintext.

Show 7 quoted lines

> 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.

I now think that my arguments apply to <pathspec> AND <commit> in the same way. Indeed a user can't know complex <commit> variants until he/she reads it in git docs.

----

[1] https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea