From: Martin Ågren <martin.agren@gmail.com>
Date: Sat, 06 Apr 2019 09:21:22 GMT
Subject: Re: [PATCH 1/2] Documentation/git-show-branch: drop last use of {apostrophe}
Message-ID: <CAN0heSoNNb4QLqQfkgPZRBD2TJ3h1JM3udyRyHnuoOcWbe94Zg@mail.gmail.com>
In-Reply-To: <20190405225115.3882-2-tmz@pobox.com>

On Sat, 6 Apr 2019 at 00:51, Todd Zullinger <tmz@pobox.com> wrote:
>
> The {apostrophe} was needed at the time of a521845800 ("Documentation:
> remove stray backslash in show-branch discussion", 2010-08-20).  All
> other uses of {apostrophe} were removed in 6cf378f0cb ("docs: stop using
> asciidoc no-inline-literal", 2012-04-26).
>
> Escape only the leading single-quote.  This renders properly in asciidoc
> and asciidoctor.

You could perhaps say that "{apostrophe}" renders literally with
Asciidoctor (at least with 1.5.5). Right now, you sort of undersell this
patch. I know from context that you have some Asciidoctor "issue", but
it's not clear from this patch alone.

> ---
>
> Maybe it would be easier to change the example commit messages
> and avoid having to nest single quotes within double quotes?  I
> don't know if that's much preferable to escaping only the opening
> single quote.

Yeah, those commit messages are a bit unfortunate from the point of view
of quoting. Avoiding all that nesting would probably improve the reading
experience, but I don't think that should hold up this patch.

> This is another potential parsing bug in asciidoctor.  Of course,
> distros will have versions of asciidoctor in place for some time
> which have trouble parsing this doc.  Since it's not much work
> for us to adjust the text to work around it, that seemed
> reasonable.

Agreed.


Martin