On Wed, 17 Feb 2021 at 23:47, Chris Torek <chris.torek@xxxxxxxxx> wrote: > > On Wed, Feb 17, 2021 at 1:21 PM Martin Ågren <martin.agren@xxxxxxxxx> 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@xxxxxxxxx> 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
