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

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

[mhagger]

From: Michael Haggerty <mhagger@alum.mit.edu>

One of the "^" characters was not coming through in the man page.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
 Documentation/git-show-ref.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index 3c45895..87f358d 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -44,7 +44,7 @@ OPTIONS
 -d::
 --dereference::
 
-	Dereference tags into object IDs as well. They will be shown with "^{}"
+	Dereference tags into object IDs as well. They will be shown with "{caret}\{\}"
 	appended.
 
 -s::
@@ -75,7 +75,7 @@ OPTIONS
 	Make 'git show-ref' act as a filter that reads refs from stdin of the
 	form "^(?:<anything>\s)?<refname>(?:{backslash}{caret}\{\})?$"
 	and performs the following actions on each:
-	(1) strip "^{}" at the end of line if any;
+	(1) strip "{caret}\{\}" at the end of line if any;
 	(2) ignore if pattern is provided and does not head-match refname;
 	(3) warn if refname is not a well-formed refname and skip;
 	(4) ignore if refname is a ref that exists in the local repository;
-- 
1.7.7

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

[Junio C Hamano]

Thanks.

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

[Michael Haggerty]

Junio,

Did this one fall through the cracks?  I don't see it in your tree.

Michael

On 10/19/2011 08:52 PM, mhagger@alum.mit.edu wrote:
> From: Michael Haggerty <mhagger@alum.mit.edu>
> 
> One of the "^" characters was not coming through in the man page.
> 
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> ---
>  Documentation/git-show-ref.txt |    4 ++--
>  1 files changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
> index 3c45895..87f358d 100644
> --- a/Documentation/git-show-ref.txt
> +++ b/Documentation/git-show-ref.txt
> @@ -44,7 +44,7 @@ OPTIONS
>  -d::
>  --dereference::
>  
> -	Dereference tags into object IDs as well. They will be shown with "^{}"
> +	Dereference tags into object IDs as well. They will be shown with "{caret}\{\}"
>  	appended.
>  
>  -s::
> @@ -75,7 +75,7 @@ OPTIONS
>  	Make 'git show-ref' act as a filter that reads refs from stdin of the
>  	form "^(?:<anything>\s)?<refname>(?:{backslash}{caret}\{\})?$"
>  	and performs the following actions on each:
> -	(1) strip "^{}" at the end of line if any;
> +	(1) strip "{caret}\{\}" at the end of line if any;
>  	(2) ignore if pattern is provided and does not head-match refname;
>  	(3) warn if refname is not a well-formed refname and skip;
>  	(4) ignore if refname is a ref that exists in the local repository;

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

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

[Junio C Hamano]

Michael Haggerty <mhagger@alum.mit.edu> writes:

> Junio,
>
> Did this one fall through the cracks?  I don't see it in your tree.
>
> Michael

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.


[Footnote]

*1* For example, http://schacon.github.com/git/git-show-ref.html indicates
that the description for "-d" does not seem to need your patch for the box
it was formatted on.

> On 10/19/2011 08:52 PM, mhagger@alum.mit.edu wrote:
>> From: Michael Haggerty <mhagger@alum.mit.edu>
>> 
>> One of the "^" characters was not coming through in the man page.
>> 
>> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
>> ---
>>  Documentation/git-show-ref.txt |    4 ++--
>>  1 files changed, 2 insertions(+), 2 deletions(-)
>> 
>> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
>> index 3c45895..87f358d 100644
>> --- a/Documentation/git-show-ref.txt
>> +++ b/Documentation/git-show-ref.txt
>> @@ -44,7 +44,7 @@ OPTIONS
>>  -d::
>>  --dereference::
>>  
>> -	Dereference tags into object IDs as well. They will be shown with "^{}"
>> +	Dereference tags into object IDs as well. They will be shown with "{caret}\{\}"
>>  	appended.
>>  
>>  -s::
>> @@ -75,7 +75,7 @@ OPTIONS
>>  	Make 'git show-ref' act as a filter that reads refs from stdin of the
>>  	form "^(?:<anything>\s)?<refname>(?:{backslash}{caret}\{\})?$"
>>  	and performs the following actions on each:
>> -	(1) strip "^{}" at the end of line if any;
>> +	(1) strip "{caret}\{\}" at the end of line if any;
>>  	(2) ignore if pattern is provided and does not head-match refname;
>>  	(3) warn if refname is not a well-formed refname and skip;
>>  	(4) ignore if refname is a ref that exists in the local repository;

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

[Michael Haggerty]

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.

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/

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

[Michael Haggerty]

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/

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

[Thomas Rast]

Michael Haggerty wrote:
> 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.
[...]
> Note Escaping is unnecessary inside inline literal passthroughs
> (backtick quoted text).

Beware!  We actively change the inline literal quoting behaviour to
ensure consistent output with different versions of asciidoc.  See
this commit:

commit 71c020c53ec472b04678237d8fe5687f2299db2a
Author: Thomas Rast <trast@student.ethz.ch>
Date:   Sat Jul 25 14:06:50 2009 +0200

    Disable asciidoc 8.4.1+ semantics for `{plus}` and friends
    
    asciidoc 8.4.1 changed the semantics of inline backtick quoting so
    that they disable parsing of inline constructs, i.e.,
    
      Input:	`{plus}`
      Pre 8.4.1:	+
      Post 8.4.1:	{plus}
    
    Fix this by defining the asciidoc attribute 'no-inline-literal'
    (which, per the 8.4.1 changelog, is the toggle to return to the old
    behaviour) when under ASCIIDOC8.
    
    Signed-off-by: Thomas Rast <trast@student.ethz.ch>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

-- 
Thomas Rast
trast@{inf,student}.ethz.ch