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

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

Johannes Sixt <j6t@kdbg.org> writes:

> 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.

Thanks for placing this into words a lot better than how I could
have done.  I share the same feeling.