Re: [PATCH 14/20] gitattributes doc: reword discussion of built-in userdiff patterns

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Feb 15, 2021, 03:26 UTC
Message-ID: <CAPig+cThGFFzNFxVo-Vdoq2HzonndrvHPjbCUznuBbMGvvLuAQ@mail.gmail.com>
In-Reply-To: <20210215005236.11313-15-avarab@gmail.com>

On Sun, Feb 14, 2021 at 7:56 PM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:

Show 21 quoted lines

> Reword the discussion of the built-in userdiff patterns to make it
> more natural to precede it with a discussion about the semantics of
> pattern matching, instead of assuming that it follows right after the
> "diff.tex.xfuncname" example which now immediately precedes it. This
> will make a follow-up commit smaller.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
> @@ -794,11 +794,17 @@ backslashes; the pattern above picks a line that begins with a
> -There are a few built-in patterns to make this easier, and `tex`
> -is one of them, so you do not have to write the above in your
> -configuration file (you still need to enable this with the
> -attribute mechanism, via `.gitattributes`).  The following built in
> -patterns are available:
> +There are built-in patterns shipped as part of git itself. A more
> +advanced version of the `tex` pattern discussed above is one of them.
> +
> +For built-in patterns you do not need the "diff.tex.xfuncname"
> +discussed above in your configuration file, but if present it'll
> +override the built-in pattern.

The literal "diff.tex.xfuncname" now feels disconnected from what is being said, especially as it is preceded by a reference to generic "built-in patterns". Perhaps it would make sense to generalize it a bit to `diff.<lang>.xfuncname`. For instance:

    For built-in patterns, you do not need `diff.<lang>.xfuncname`
    in your configuration file as discussed above, but if present,
    it will override a built-in pattern.

> +You still need to enable built-in patterns with the the attribute
> +mechanism, via `.gitattributes`).

s/the the/the/

Although you're simply re-using the existing text, it also now feels disconnected. Perhaps:

    Nevertheless, you need to enable built-in patterns via
    `.gitattributes` for the pattern to take effect.