Re: [PATCH 2/2] Documentation/git-svn: improve asciidoctor compatibility
- Date: Sat, 6 Apr 2019 11:31:19 +0200
- From: Martin Ågren <martin.agren@xxxxxxxxx>
- Subject: Re: [PATCH 2/2] Documentation/git-svn: improve asciidoctor compatibility
On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@xxxxxxxxx> wrote:
> The second paragraph in the CONFIGURATION section intends to emphasize
> the word 'must' with bold type. Adjust the formatting slightly to
> provide similar results between asciidoc and asciidoctor.
I don't think this explains the problem you're solving well enough. It
also doesn't make it clear enough, IMHO, how what we're doing here
solves that problem. How about something like this?
The second paragraph in the CONFIGURATION section intends to emphasize
the word 'must' with bold type. It does so by writing it as *must*,
and this works fine with AsciiDoc. It usually works great with
Asciidoctor, too, but in this particular instance, we have another "*"
earlier in the paragraph. We do escape it, and it is rendered
literally just like we want it to, but Asciidoctor then ends up
tripping on the second (or third) of the asterisks in this paragraph.
Since that asterisk is (part of) a literal example, we can set it in
monospace, by giving it as `*`. Adjust the whole paragraph in this
way. There's lots more monospacing to be done in this document, but
since our main motivation is addressing AsciiDoc/Asciidoctor
discrepancies like this one, let's just convert this one paragraph.
I think what's happening could be related to the fix in the first patch.
There, it's ok to explicitly escape only the first '. The second one is
matched to it and gets escaped implicitly. Something like that could be
happening here, too, just that we don't want it to. (Should we escape
the implicit escaping? ...) Just speculation, though.