Re: [PATCH 1/2] Documentation/git-show-branch: drop last use of {apostrophe}

From: Martin Ågren <martin.agren@gmail.com>
Date: Apr 6, 2019, 09:21 UTC
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:

Show 8 quoted lines

>
> 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.

Show 6 quoted lines

> ---
>
> 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.

Show 5 quoted lines

> 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