Subject: Re: [PATCH 4/5] doc: git-diff: apply format changes to diff-generate-patch

From: Johannes Sixt <[email-masked]>
Date: Mon, 5 Aug 2024 07:53:19 +0200

Am 04.08.24 um 22:05 schrieb Jean-Noël Avila via GitGitGadget:
> @@ -134,17 +135,18 @@ or like this (when the `--cc` option is used):
>  
>  2.   It is followed by one or more extended header lines
>       (this example shows a merge with two parents):
> -
> -       index <hash>,<hash>..<hash>
> -       mode <mode>,<mode>..<mode>
> -       new file mode <mode>
> -       deleted file mode <mode>,<mode>
>  +
> -The `mode <mode>,<mode>..<mode>` line appears only if at least one of
> -the <mode> is different from the rest. Extended headers with
> +[synopsis]
> +index <hash>,<hash>`..`<hash>
> +mode <mode>,<mode>`..`<mode>
> +new file mode <mode>
> +deleted file mode <mode>,<mode>
> ++
> +The `mode` __<mode>__++,++__<mode>__++..++__<mode>__ line appears only if at least one of
> +the _<mode>_ is different from the rest. Extended headers with

I've a strong aversion to the formatting that this series applies,
because it introduces many (IMHO) unnecessary punctuation that
vandalizes the perfectly readable plain text. And this hunk now shows
where it goes too far. These lines under the new [synopsis] header just
aren't syopsis; they are comamnd output. The updated version abuses a
semantic token to achieve syntactic highlighting.

To me this series looks too much like "we must adapt to the tool" when
the correct stance should be "the tool must adapt to us". If the tool
(one of asciidoc and asciidoctor, I presume) does not cooperate well
with out documents, then it is the tool that must be changed, not our
documents.

I understand that some compromises are needed, but with this extent of
changes we give in to a sub-par tool too far.

Just my 2c.

-- Hannes