From: Alexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com>
Date: Thu, 07 Nov 2019 11:39:55 GMT
Subject: Re: [PATCH 4/5] doc: commit: unify <pathspec> description
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:
> 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.

> 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