Re: [PATCH/docs] make slash-rules more readable

[Junio C Hamano <gitster@pobox.com>]

"Dr. Adam Nielsen" <admin@in-ici.net> writes:

> I agree with you. How about we make up the word "intermediate slash" and
> explain it in an extra paragraph?

I am not sure if that is any better than "in the following, pretend
that a slash at the end of a pattern does not exist", which is how
the current description avoids repetition and aims for clarity.  It
probably is worse than than the current one if we need to introduce
a new term that is otherwise not useful elsewhere---a new term adds
to the cognitive load of readers.

>> I also wonder if "in all directories" is clear enough that your
>> "all" is limited to below the level the ignore pattern is defined
>> for (i.e. "*.1" that appears in "Documentation/.gitignore" does not
>> ignore "foo.1" at the top-level of the tree).
>
> Its mentioned at the start of the page that the pattern is always
> relative to the location of the `.gitignore` file. However, I see that
> since its said "in all directories" its necessary to restrict it again.
> How about
>
>          If the pattern contains no intermediate slash "`/`",
>          the pattern will match in all directories at or below
>          the `.gitignore` file, with infinite depth.

It is unclear what "with infinite depth" means in this sentence.
There is no depth-limit in the exclude mechanism, and I'd prefer
not to confuse readers by making a casual mention of "depth" to
imply as if there is some depth-based logic.

Also, as you defined "intermediate" as a slash that is neither
leading nor trailing, the above paragraph says "/foo" matches any
filesystem entity whose final path component is 'foo', e.g. a file
'foo' at the current level, a directory 'foo' in subdirectory 'dir'
(i.e. 'dir/foo'), etc.  I do not think you meant to say that (and
this is why I do not like to introduce a new term---even its
inventor cannot get it right).

>> So I can tell that this patch is trying to address a problem in the
>> original that is worth fixing, but I cannot say the result is good.
>> At least not yet.
>> ...
>> Once you write consistently that a path for a directory foo/bar is
>> foo/bar, not foo/bar/, then this example would become much easier to
>> write and read, I suspect.
>>
>>         An asterisk "`*`" matches anything except a slash.  A
>>         pattern "foo/*", for example, matches "foo/test.json" (a
>>         regular file), "foo/bar" (a diretory), but it does not match
>>         "foo/bar/hello.c" (a regular file), as the asterisk in the
>>         patter does not match "bar/hello.c" which has a slash in it.
>>
>> perhaps.
>
> I agree, this is much better. Although I would leave out
>
>>  "as the asterisk in the patter does not match "bar/hello.c"
>>   which has a slash in it."

I happen to think that the part is the more important half of that
whole "example".  By explaining why it does not match, it enforces
"matches anything except a slash" we gave upfront.

Thanks.  I think we are making progress...