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

On Wed, 17 Feb 2021 at 23:47, Chris Torek [off-list ref] wrote:

On Wed, Feb 17, 2021 at 1:21 PM Martin Ågren [off-list ref] wrote:

quoted

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):

quoted

 +           contain an equals sign to avoid ambiguity with <name> containing

quoted

+       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 [off-list ref] 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:

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