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

The description "in the following, pretend that a slash at the end of a pattern does not exist" is much better understandable then "it is removed for the purpose of the following description" to me. However, I still think its better not to use it:

  1. The following paragraphs may not be valid if you do not keep this
rule in mind.
      This could happen, because one may not read the paragraphs in order,
      or its unclear if "in the following" is meant for all following
paragraphs or just this
      paragraph, or one simply forgets it if one happens to check up a
specific paragraph
      after some months or when returning from a break.
  2. Forcing the user to be aware that "in the following pretend that
a slash at the end does not exist"
      is at least for me a harder cognitive load then introducing a new term.
      Because for every new paragraph that I read, I have to check if
this rule applies.
  3. If you jump between paragraphs, you always need to locate the rule
      and then check if the current paragraph is below or after that rule.
  4. There are 7 paragraphs following this "specific rule" but only
the next paragraph
      is using it. I think its also not needed for the paragraph where
it appears.
      For the other 6 paragraphs one needs to unnecessary check
      if the rule is implicitly used anywhere.
  5. For every paragraph that one may add in the future below that
rule, one needs to double check
      if its compatible with this rule. So in terms of maintenance I
think its rather a downside.

If something is cumbersome to explain and appears often, I think its best to explain it once in detail and refer to that instead of a bloated description. However, since this scenario only appears in two paragraphs, a new term is maybe not justifiable. Thus, a cumbersome but complete description might be preferable.

The description "infinite depth" is used in the current documentation in the paragraph for `/**`. I thought its good to reuse something that has already been approved by the community. I think it points out very well that we are not only looking at folders at the level of the `.gitignore` file but all the folders below.

We could fix it by defining an intermediate slash as any slash that is not a trailing one. But then one may just call it a "non-trailing" slash which is maybe self-explanatory enough.

Especially if someone invents a new thing, I would not expect that its perfect right from scratch.

However, I have to admit, the introduced term "intermediate" has its flaws. Maybe using "non-trailing" or a description is better.

Alright.

To summarize: I would suggest to drop "it is removed for the purpose of the following description" because of the points I made at the top and instead mention the necessary exceptions in the two relevant paragraphs. Here my new updated proposals:

          If the pattern contains no slash "`/`"
          (except an optional trailing slash),
          the pattern will match in all directories relative to
          the `.gitignore` file, with infinite depth.
          For example, `frotz/` matches `frotz` and `a/frotz` that
          is a directory, but does not match if these are files.
          A pattern `frotz` on the other hand matches these paths
          whether they are files or directories.

I think this is better then my first proposal:

The phrase "except an optional" and the example both point out that this rule works with and without trailing slash. I kept "infinite depth" for the reasons explained above.

For the next paragraph I would suggest this:

        If the pattern contains a non-trailing slash "`/`",
        it matches the beginning of the pathname.
        For example, the pattern `doc/frotz/` matches
        `doc/frotz` that is a directory
        but does not match `a/doc/frotz`.

Where I have taken `it matches the beginning of the pathname` from the paragraph of a leading slash. The example uses a trailing slash, to emphasize that this rule works also with trailing slash, for the case that the reader confuses the line with "If the pattern contains no trailing slash". Alternatively I would suggest:

        If the pattern contains a slash "`/`"
        that is not a trailing slash,
        it matches the beginning of the pathname.
        For example, the pattern `doc/frotz/` matches
        `doc/frotz` that is a directory
        but does not match `a/doc/frotz`.

This might be addressing the problem of my first proposal:

All the best, Adam