On 11/16/2011 06:52 AM, Michael Haggerty wrote:
> On 11/15/2011 08:16 PM, Junio C Hamano wrote:
>> Michael Haggerty <mhagger@xxxxxxxxxxxx> 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@xxxxxxxxxxxx
http://softwareswirl.blogspot.com/
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html