Re: [PATCH 1/2] glossary-content.txt: remove an obsolete paragrah

Nguyễn Thái Ngọc Duy  <pclouds@gmail.com> writes:

You need to re-read the message you took hints that led to this patch from (or, rather, the existing document around the area you are patching, which led to the wording in that message from me).

The above is a list of magic words, but until you add the magic signature ":!not_in_this_directory" for the ":(exclude)" magic word, ":/" still is the only magic signature.

Another moderately related tangent is this phrase in the existing document:

    In the short form, the leading colon `:` is followed by zero or
    more "magic signature" letters (which optionally is terminated
    by another colon `:`), and the remainder is the pattern to match
    against the path. The optional colon that terminates the "magic
    signature" can be omitted if the pattern begins with a character
    that cannot be a "magic signature" and is not a colon.

While it is technically correct, the phrase "a character that cannot be" is somewhat misleading, and I think it needs to be clarified by rephrasing.

As we can see in a later paragaph:

    The "magic signature" consists of an ASCII symbol that is not
    alphanumeric. Currently only the slash `/` is recognized as a
    "magic signature"...

the correct way to read that "a character that cannot be a magic signature" is "a character that is not 'an ASCII symbol that is not alphanumeric'", which means you can do:

	:!/foo	- with magic signatures ! and /, pattern begins at 'f'

	:/#abc  - with magic signatures # and /, pattern begins at 'a',
	          even if in a particular version of Git, '#' magic
		  signature may be invalid and produce an error

	:/:#abc - with magic signature /, pattern is "#abc".

but because the definition of "magic signature" syntax comes later than "cannot be", it is prone to be misinterpreted as "anything that is not currently defined as a magic signature (namely, '/')".