Re: [PATCH] Documentation: remove unnecessary backslashes

From: Jeff King <peff@peff.net>
Date: Jan 20, 2016, 20:34 UTC
Message-ID: <20160120203430.GB6092@sigill.intra.peff.net>
In-Reply-To: <xmqqmvs05722.fsf@gitster.mtv.corp.google.com>

On Wed, Jan 20, 2016 at 12:28:53PM -0800, Junio C Hamano wrote:

Show 10 quoted lines

> >> -'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}'::
> >> +'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
> >
> > I see you didn't tweak the middle one here, because it _does_ look like
> > an attribute. Does asciidoctor actually remove the backslashes there?
> 
> A more important question is if it works without the backslashes.
> If not-too-stale versions of asciidoc everybody uses these days are
> all OK without braces quoted with backslashes, and if the same holds
> true for asciidoctor, then we would want consistency here.

The answer to that is implied in the original commit message; no, it does not work, because it is syntactically an asciidoc attribute.

Show 5 quoted lines

> On the other hand, if this line must be spelled like the above to
> please asciidoctor, i.e. the first and the last must not have
> backslashes and the second must have backslashes, I'd have to say
> we have a bigger problem.  Perhaps asciidoctor needs to be fixed
> until normal people like we can rely on it.

Yeah, that is the "insane" part I mentioned. It _does_ make sense syntactically ("-1" cannot possibly be an attribute name, so it does not parse as one), but I do not like the degree to which writers must know all of the arcane syntax rules (and cannot rely on something simple like "{ is special, so I must escape it, and over-escaping is not a problem").

-Peff