Re: [PATCH v2 3/3] doc: git-config: escape erroneous highlight markup

From: Jeff King <peff@peff.net>
Date: Jun 11, 2026, 08:31 UTC
Message-ID: <20260611083139.GA2237523@coredump.intra.peff.net>
In-Reply-To: <20260611080242.lqXwi%taahol@utu.fi>

On Thu, Jun 11, 2026 at 11:02:42AM +0300, Tuomas Ahola wrote:

Show 24 quoted lines

> > >  If _<message>_ begins with one or more whitespaces followed
> > > -by "#", it is used as-is.  If it begins with "#", a space is
> > > +by "\#", it is used as-is.  If it begins with "\#", a space is
> > >  prepended before it is used.  Otherwise, a string " # " (a
> > >  space followed by a hash followed by a space) is prepended
> > 
> > I saw the comment on round 1 about this second "#" on the line. But
> > while we are here, should we be doing the one in the context, too?
> > 
> > -Peff
> 
> It seems adding that second backslash was already too much, as doc-diff (which
> I neglected to run before submitting V2) shows:
> 
> ```
> $ ./doc-diff V1 V2
>  
>             If <message> begins with one or more whitespaces followed by "#",
> -           it is used as-is. If it begins with "#", a space is prepended
> +           it is used as-is. If it begins with "\#", a space is prepended
>             before it is used. Otherwise, a string " # " (a space followed by a
>             hash followed by a space) is prepended to it. The resulting string
>             is placed immediately after the value defined for the variable. The
> ```

Heh, it would not be the first time I am baffled by asciidoc's parsing. :)

Adding a backslash to the third instance "fixes" the second one to me, but I wouldn't want to rely on that (plus it breaks the third instance).

Using backticks does work, though it always opens a typographical question. When reading the source, you see `#`, so you get a punctuation delimiter but no typographical one. In the rendered output, you'll see it in a typewriter font (assuming we fix the config issue), but we'd lose the visible punctuation. I could live with that.

But for " # ", it gets weirder. We need punctuation to call out the spaces, but what should happen to the quotes? They are not really part of the literal string, so should they go inside or outside the backticks? I think it may be a moot point as "` # `" is not parsed as you might hope by asciidoc. Doing `" # "` does work, and is probably OK enough here.

-Peff