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
