Re: [PATCH] git-show-ref: fix escaping in asciidoc source
- From
Michael Haggerty <mhagger@alum.mit.edu>
- Date
- Nov 16, 2011, 11:54 UTC
- Message-ID
- <4EC3A45F.9080005@alum.mit.edu>
- In-Reply-To
- <4EC34FA5.2020809@alum.mit.edu>
On 11/16/2011 06:52 AM, Michael Haggerty wrote:
Show 21 quoted lines
> 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/