Re: [PATCH] git-show-ref: fix escaping in asciidoc source

[Michael Haggerty <mhagger@alum.mit.edu>]

On 11/16/2011 06:52 AM, Michael Haggerty wrote:
> On 11/15/2011 08:16 PM, Junio C Hamano wrote:
>> 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. [...]
> 
> I can't believe I spent my whole morning on this :-(

There are a couple of FAQ entries on the asciidoc site that are relevant
(excerpted; click on the links in the footnotes for the full text):

====================================================================

35 [1]. How can I place a backslash character in front of an attribute
reference without escaping the reference?

Use the predefined {backslash} attribute reference instead of an actual
backslash [...]

36 [2]. How can I escape AsciiDoc markup?

Most AsciiDoc inline elements can be suppressed by preceding them with a
backslash character.  These elements include: [...] But there are
exceptions — see the next question.

37 [3]. Some elements can’t be escaped with a single backslash

There are a number of exceptions to the usual single backslash rule — 
mostly relating to URL macros that have two syntaxes or quoting
ambiguity.  Here are some non-standard escape examples: [...]  A
work-around for difficult cases is to side-step the problem using the
pass:[] passthrough inline macro.
Note Escaping is unnecessary inside inline literal passthroughs
(backtick quoted text).

51 [4]. How can I selectively disable a quoted text substitution?

Omitting the tag name will disable quoting. For example, if you don’t
want superscripts or subscripts then put the following in a custom
configuration file or edit the global asciidoc.conf configuration file:

[quotes]
^=
~=

Alternatively you can set the configuration entries from within your
document, the above examples are equivalent to:

:quotes.^:
:quotes.~:

====================================================================

Given that the git documentation uses lots of "^" and "~" but probably
no subscripting or superscripting, it seems like the suggestion in FAQ
entry 51 would be helpful.  But unfortunately it chokes version 8.5.2 of
asciidoc, which is what I have installed.  So it is probably too new to
be appropriate for git use.

I also did a check to see whether other sub/superscripts are present in
the git documentation:

    make all doc
    find Documentation -type f -name '*.html' -print0 |
        xargs -0 grep -nE -e '<su[bp]>'

The only hit was the one under discussion, in git-show-ref.html.  (This
is no check that "^" and "~" are always quoted, but only that they don't
appear unquoted in pairs.)

Michael

[1]
http://www.methods.co.nz/asciidoc/faq.html#_how_can_i_place_a_backslash_character_in_front_of_an_attribute_reference_without_escaping_the_reference
[2]
http://www.methods.co.nz/asciidoc/faq.html#_how_can_i_escape_asciidoc_markup
[3]
http://www.methods.co.nz/asciidoc/faq.html#_some_elements_can_8217_t_be_escaped_with_a_single_backslash
[4]
http://www.methods.co.nz/asciidoc/faq.html#_how_can_i_selectively_disable_a_quoted_text_substitution

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/