list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: "Martin Ågren" <>
To: Chris Torek <>
Cc: "Git List" <>,
	"Sergey Organov" <>,
	"Patrick Steinhardt" <>,
	"Ævar Arnfjörð Bjarmason" <>
Subject: Re: [PATCH 2/3] git.txt: fix monospace rendering
Date: Thu, 18 Feb 2021 07:28:29 +0100	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

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


  reply	other threads:[~2021-02-18  6:41 UTC|newest]

Thread overview: 12+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-02-17 19:56 [PATCH 0/3] fix some doc rendering issues since v2.30.0 Martin Ågren
2021-02-17 19:56 ` [PATCH 1/3] rev-list-options.txt: fix rendering of bonus paragraph Martin Ågren
2021-02-17 19:56 ` [PATCH 2/3] git.txt: fix monospace rendering Martin Ågren
2021-02-17 22:47   ` Chris Torek
2021-02-18  6:28     ` Martin Ågren [this message]
2021-02-18  6:27   ` Patrick Steinhardt
2021-02-18  6:32     ` Martin Ågren
2021-02-18 18:51   ` Junio C Hamano
2021-02-19  6:33     ` Martin Ågren
2021-02-17 19:56 ` [PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses Martin Ågren
2021-02-18 10:48   ` Ævar Arnfjörð Bjarmason
2021-02-17 21:22 ` [PATCH 0/3] fix some doc rendering issues since v2.30.0 Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).