Re: [PATCH 2/3] git.txt: fix monospace rendering

["Martin Ågren" <martin.agren@gmail.com>]

On Wed, 17 Feb 2021 at 23:47, Chris Torek <chris.torek@gmail.com> wrote:
>
> On Wed, Feb 17, 2021 at 1:21 PM Martin Ågren <martin.agren@gmail.com> wrote:
> >
> > When we write `<name>`s with the "s" tucked on to the closing backtick,
> > we end up rendering the backticks literally. Rephrase this sentence
> > slightly to render this as monospace.
>
> That seems fine, but one question (diff trimmed way down to
> make it clearer I hope):
>
> >  +           contain an equals sign to avoid ambiguity with <name> containing
>
> > +       to avoid ambiguity with `<name>` containing one.
>
> One replacement drops the backquotes entirely.  The other keeps
> them.  Surely these two shouldn't be *different*...?

I included the output of our "doc-diff" script below the double-dash
line. The patch applies just as fine anyway, but I did wonder if it
would trip up human readers. :-/

Quoting my original, slightly less trimmed:

On Wed, 17 Feb 2021 at 20:56, Martin Ågren <martin.agren@gmail.com> wrote:
>  doc-diff:
>  --- a/.../man/man1/git.1
>  +++ b/.../man/man1/git.1
>  -           contain an equals sign to avoid ambiguity with `<name>`s which
>  -           contain one.
>  +           contain an equals sign to avoid ambiguity with <name> containing
>  +           one.

So that's how the rendering is changed. From "oops, we rendered the
backticks literally" to "we no longer do". (It's not clear from the
doc-diff that they're rendered monospace/bold, but at least this is no
longer obviously broken.)

(Note the extra indentation of all of that. This is where one might
place some commentary that one don't want to burden the commit message
with, but which also isn't part of the actual diff. Now that this looks
very much like a diff, I can see how it's confusing.)

And that's because of this change to the actual sources:

> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index d36e6fd482..3a9c44987f 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> -       to avoid ambiguity with `<name>`s which contain one.
> +       to avoid ambiguity with `<name>` containing one.

I hope that clarifies it? It's a bit unfortunate that the misrendering
is so similar to the source in the txt file. But I guess that's still
better than some of those misrenderings where some cogwheel slips and
everything spins out of control through the rest of the paragraph.

Martin