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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 15, 2011, 19:16 UTC
Message-ID: <7vk471urfy.fsf@alter.siamese.dyndns.org>
In-Reply-To: <4EC27328.3070309@alum.mit.edu>

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

Show 5 quoted lines

> 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.

Show 32 quoted lines

> 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;