Re: [PATCH] git-show-ref: fix escaping in asciidoc source
On 11/15/2011 08:16 PM, Junio C Hamano wrote:
Show 15 quoted lines
> Michael Haggerty <mhagger@alum.mit.edu> writes:
>> Did this one fall through the cracks? I don't see it in your tree.
>
> Yeah, I was wondering if we can have a concise description in what context
> any "^" must be spelled as {caret} and what other context "^" can be
> spelled literally, and possibly which versions of AsciiDoc toolchain have
> this issue [*1*]. Without a clear guideline, people may unknowingly use
> literal "^" to new paragraphs, or perhaps worse yet, spell {caret} that
> end up being shown literally.
>
> Since I didn't find a clear pattern other than that "^" can and should be
> literally given in a literal paragraph (i.e. an indented paragraph or
> inside a listing/literal block that shows program examples), I was meaning
> to ask you if you knew the rules better than I did, and I stopped there,
> forgetting to follow through.I didn't know anything about asciidoc, and just tried to fix it using a bit of cargo-cult programming.
Now I just did about an hour of research about asciidoc (but I still don't feel very enlightened). It seems that asciidoc was interpreting the caret, paired with one earlier in the paragraph, as markup asking for the enclosed text to be superscripted [1]. Apparently, single carets in a paragraph are not treated as markup, which would explain some apparent inconsistency about when carets need to be quoted. But it would seem prudent to escape all carets that don't appear in literal blocks.
Constructs like "{caret}" are "simple attribute references". In this particular case, the attribute that it is referencing is not built into asciidoc but rather defined in the file Documentation/asciidoc.conf. Empirically it seems that curly braces need to be escaped if they can be interpreted to be part of an attribute reference, but not otherwise. For example, curly braces with nothing inside of them like "{}" don't necessarily need to be quoted, but it doesn't hurt if they are quoted to "\{\}".
The backslash escape rules are a bit mysterious to me. Backslash can be used to escape some special characters. For example, they can be used to escape leading special quoting characters to avoid the special effect, like "\_not italic_" [3]. They can also be used to suppress attribute references, like "\{caret}" [4]. But it doesn't appear possible to use a backslash to escape another backslash; for example "\\{carat}" is rendered as "\{carat}". In such cases, the backslash can be spelled "{backslash}" (which is also defined in asciidoc.conf).
How to quote a monstrosity like the regexp in git-show-ref.txt? We want it to render as
^(?:<anything>\s)?<refname>(?:\^{})?$, probably in monospaced font and surrounded by double quotes. asciidoc supports a bewildering variety of quoting mechanisms [5]. Empirically,
"`^(?:<anything>\s)?<refname>(?:\^{})?$`"doesn't work (the backticks don't suppress superscripting).
A pedestrian option is
"`{caret}(?:<anything>\s)?<refname>(?:{backslash}{caret}\{\})?$`"or
"`{caret}(?:<anything>\s)?<refname>(?:{backslash}{caret}{})?$`"Or the whole blob can be quoted en masse using $$:
"`$$^(?:<anything>\s)?<refname>(?:\^{})?$$$`"I don't know whether it treats the last dollar signs as "$$ $" or "$ $$", but either way the result looks OK.
I can't believe I spent my whole morning on this :-(
Michael
[1] http://www.methods.co.nz/asciidoc/userguide.html#_superscripts_and_subscripts [2] http://www.methods.co.nz/asciidoc/userguide.html#_simple_attributes_references [3] http://www.methods.co.nz/asciidoc/userguide.html#X51 [4] http://www.methods.co.nz/asciidoc/userguide.html#_attribute_references [5] http://www.methods.co.nz/asciidoc/userguide.html#X77
--
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/
mhagger@alum.mit.edu
