Re: [PATCH] Documentation: render special characters correctly

From: Jeff King <peff@peff.net>
Date: Jul 29, 2021, 13:04 UTC
Message-ID: <YQKnaCcfJaagTF/h@coredump.intra.peff.net>
In-Reply-To: <20210729110252.116214-1-rybak.a.v@gmail.com>

On Thu, Jul 29, 2021 at 01:02:52PM +0200, Andrei Rybak wrote:

Show 7 quoted lines

> Three hyphens are rendered verbatim, so "--" has to be used to produce a
> dash.  There is no double arrow ("<->" is rendered as "<→"), so a left
> and right arrow "<-->" have to be combined for that.
> 
> So fix asciidoc output for special characters.  This is similar to fixes
> in commit de82095a95 (doc hash-function-transition: fix asciidoc output,
> 2021-02-05).

Thanks. I looked at the doc-diff output before and after this patch, and they both seem like strict improvements.

The double-arrow thing is kind of weird to me in the first place, though. I suspect it might be more clear if it just spelled out what it is trying to say with words. Something like:

  The pruning feature doesn't actually care about branches. Instead, it
  will prune local refs tracking remote ones as a function of...

But I'm OK to leave that to do on top; the current code simply renders incorrectly, and your patch is fixing that.

-Peff