{"thread":{"id":"28721","subject":"[PATCH] git-show-ref: fix escaping in asciidoc source","startedAt":"2011-10-19T18:52:16Z","lastAt":"2011-11-16T13:08:50Z","messageCount":7,"participants":["mhagger@alum.mit.edu","Junio C Hamano","Michael Haggerty","Thomas Rast"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"178005","messageId":"1319050336-24717-1-git-send-email-mhagger@alum.mit.edu","threadId":"28721","inReplyTo":null,"subject":"[PATCH] git-show-ref: fix escaping in asciidoc source","fromName":"","fromEmail":"mhagger@alum.mit.edu","sentAt":"2011-10-19T18:52:16Z","receivedAt":"2011-10-19T18:52:16Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"From: Michael Haggerty \n\nOne of the \"^\" characters was not coming through in the man page.\n\nSigned-off-by: Michael Haggerty \n---\n Documentation/git-show-ref.txt | 4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\nindex 3c45895..87f358d 100644\n--- a/Documentation/git-show-ref.txt\n+++ b/Documentation/git-show-ref.txt\n@@ -44,7 +44,7 @@ OPTIONS\n -d::\n --dereference::\n \n-\tDereference tags into object IDs as well. They will be shown with \"^{}\"\n+\tDereference tags into object IDs as well. They will be shown with \"{caret}\\{\\}\"\n \tappended.\n \n -s::\n@@ -75,7 +75,7 @@ OPTIONS\n \tMake 'git show-ref' act as a filter that reads refs from stdin of the\n \tform \"^(?:\\s)?(?:{backslash}{caret}\\{\\})?$\"\n \tand performs the following actions on each:\n-\t(1) strip \"^{}\" at the end of line if any;\n+\t(1) strip \"{caret}\\{\\}\" at the end of line if any;\n \t(2) ignore if pattern is provided and does not head-match refname;\n \t(3) warn if refname is not a well-formed refname and skip;\n \t(4) ignore if refname is a ref that exists in the local repository;\n-- \n1.7.7\n"},{"id":"178010","messageId":"7v1uu8dax0.fsf@alter.siamese.dyndns.org","threadId":"28721","inReplyTo":"1319050336-24717-1-git-send-email-mhagger@alum.mit.edu","subject":"Re: [PATCH] git-show-ref: fix escaping in asciidoc source","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-10-19T19:43:55Z","receivedAt":"2011-10-19T19:43:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks.\n"},{"id":"179503","messageId":"4EC27328.3070309@alum.mit.edu","threadId":"28721","inReplyTo":"1319050336-24717-1-git-send-email-mhagger@alum.mit.edu","subject":"Re: [PATCH] git-show-ref: fix escaping in asciidoc source","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2011-11-15T14:11:52Z","receivedAt":"2011-11-15T14:11:52Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"Junio,\n\nDid this one fall through the cracks? I don't see it in your tree.\n\nMichael\n\nOn 10/19/2011 08:52 PM, mhagger@alum.mit.edu wrote:\n> From: Michael Haggerty \n> \n> One of the \"^\" characters was not coming through in the man page.\n> \n> Signed-off-by: Michael Haggerty \n> ---\n> Documentation/git-show-ref.txt | 4 ++--\n> 1 files changed, 2 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\n> index 3c45895..87f358d 100644\n> --- a/Documentation/git-show-ref.txt\n> +++ b/Documentation/git-show-ref.txt\n> @@ -44,7 +44,7 @@ OPTIONS\n> -d::\n> --dereference::\n> \n> -\tDereference tags into object IDs as well. They will be shown with \"^{}\"\n> +\tDereference tags into object IDs as well. They will be shown with \"{caret}\\{\\}\"\n> \tappended.\n> \n> -s::\n> @@ -75,7 +75,7 @@ OPTIONS\n> \tMake 'git show-ref' act as a filter that reads refs from stdin of the\n> \tform \"^(?:\\s)?(?:{backslash}{caret}\\{\\})?$\"\n> \tand performs the following actions on each:\n> -\t(1) strip \"^{}\" at the end of line if any;\n> +\t(1) strip \"{caret}\\{\\}\" at the end of line if any;\n> \t(2) ignore if pattern is provided and does not head-match refname;\n> \t(3) warn if refname is not a well-formed refname and skip;\n> \t(4) ignore if refname is a ref that exists in the local repository;\n\n-- \nMichael Haggerty\nmhagger@alum.mit.edu\nhttp://softwareswirl.blogspot.com/\n"},{"id":"179524","messageId":"7vk471urfy.fsf@alter.siamese.dyndns.org","threadId":"28721","inReplyTo":"4EC27328.3070309@alum.mit.edu","subject":"Re: [PATCH] git-show-ref: fix escaping in asciidoc source","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-11-15T19:16:33Z","receivedAt":"2011-11-15T19:16:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael Haggerty writes:\n\n> Junio,\n>\n> Did this one fall through the cracks? I don't see it in your tree.\n>\n> Michael\n\nYeah, I was wondering if we can have a concise description in what context\nany \"^\" must be spelled as {caret} and what other context \"^\" can be\nspelled literally, and possibly which versions of AsciiDoc toolchain have\nthis issue [*1*]. Without a clear guideline, people may unknowingly use\nliteral \"^\" to new paragraphs, or perhaps worse yet, spell {caret} that\nend up being shown literally.\n\nSince I didn't find a clear pattern other than that \"^\" can and should be\nliterally given in a literal paragraph (i.e. an indented paragraph or\ninside a listing/literal block that shows program examples), I was meaning\nto ask you if you knew the rules better than I did, and I stopped there,\nforgetting to follow through.\n\n\n[Footnote]\n\n*1* For example, http://schacon.github.com/git/git-show-ref.html indicates\nthat the description for \"-d\" does not seem to need your patch for the box\nit was formatted on.\n\n> On 10/19/2011 08:52 PM, mhagger@alum.mit.edu wrote:\n>> From: Michael Haggerty \n>> \n>> One of the \"^\" characters was not coming through in the man page.\n>> \n>> Signed-off-by: Michael Haggerty \n>> ---\n>> Documentation/git-show-ref.txt | 4 ++--\n>> 1 files changed, 2 insertions(+), 2 deletions(-)\n>> \n>> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\n>> index 3c45895..87f358d 100644\n>> --- a/Documentation/git-show-ref.txt\n>> +++ b/Documentation/git-show-ref.txt\n>> @@ -44,7 +44,7 @@ OPTIONS\n>> -d::\n>> --dereference::\n>> \n>> -\tDereference tags into object IDs as well. They will be shown with \"^{}\"\n>> +\tDereference tags into object IDs as well. They will be shown with \"{caret}\\{\\}\"\n>> \tappended.\n>> \n>> -s::\n>> @@ -75,7 +75,7 @@ OPTIONS\n>> \tMake 'git show-ref' act as a filter that reads refs from stdin of the\n>> \tform \"^(?:\\s)?(?:{backslash}{caret}\\{\\})?$\"\n>> \tand performs the following actions on each:\n>> -\t(1) strip \"^{}\" at the end of line if any;\n>> +\t(1) strip \"{caret}\\{\\}\" at the end of line if any;\n>> \t(2) ignore if pattern is provided and does not head-match refname;\n>> \t(3) warn if refname is not a well-formed refname and skip;\n>> \t(4) ignore if refname is a ref that exists in the local repository;\n"},{"id":"179550","messageId":"4EC34FA5.2020809@alum.mit.edu","threadId":"28721","inReplyTo":"7vk471urfy.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-show-ref: fix escaping in asciidoc source","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2011-11-16T05:52:37Z","receivedAt":"2011-11-16T05:52:37Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 11/15/2011 08:16 PM, Junio C Hamano wrote:\n> Michael Haggerty writes:\n>> Did this one fall through the cracks? I don't see it in your tree.\n> \n> Yeah, I was wondering if we can have a concise description in what context\n> any \"^\" must be spelled as {caret} and what other context \"^\" can be\n> spelled literally, and possibly which versions of AsciiDoc toolchain have\n> this issue [*1*]. Without a clear guideline, people may unknowingly use\n> literal \"^\" to new paragraphs, or perhaps worse yet, spell {caret} that\n> end up being shown literally.\n> \n> Since I didn't find a clear pattern other than that \"^\" can and should be\n> literally given in a literal paragraph (i.e. an indented paragraph or\n> inside a listing/literal block that shows program examples), I was meaning\n> to ask you if you knew the rules better than I did, and I stopped there,\n> forgetting to follow through.\n\nI didn't know anything about asciidoc, and just tried to fix it using a\nbit of cargo-cult programming.\n\nNow I just did about an hour of research about asciidoc (but I still\ndon't feel very enlightened). It seems that asciidoc was interpreting\nthe caret, paired with one earlier in the paragraph, as markup asking\nfor the enclosed text to be superscripted [1]. Apparently, single\ncarets in a paragraph are not treated as markup, which would explain\nsome apparent inconsistency about when carets need to be quoted. But it\nwould seem prudent to escape all carets that don't appear in literal blocks.\n\nConstructs like \"{caret}\" are \"simple attribute references\". In this\nparticular case, the attribute that it is referencing is not built into\nasciidoc but rather defined in the file Documentation/asciidoc.conf.\nEmpirically it seems that curly braces need to be escaped if they can be\ninterpreted to be part of an attribute reference, but not otherwise.\nFor example, curly braces with nothing inside of them like \"{}\" don't\nnecessarily need to be quoted, but it doesn't hurt if they are quoted to\n\"\\{\\}\".\n\nThe backslash escape rules are a bit mysterious to me. Backslash can be\nused to escape some special characters. For example, they can be used\nto escape leading special quoting characters to avoid the special\neffect, like \"\\_not italic_\" [3]. They can also be used to suppress\nattribute references, like \"\\{caret}\" [4]. But it doesn't appear\npossible to use a backslash to escape another backslash; for example\n\"\\\\{carat}\" is rendered as \"\\{carat}\". In such cases, the backslash can\nbe spelled \"{backslash}\" (which is also defined in asciidoc.conf).\n\nHow to quote a monstrosity like the regexp in git-show-ref.txt? We want\nit to render as\n\n ^(?:\\s)?(?:\\^{})?$\n\n, probably in monospaced font and surrounded by double quotes. asciidoc\nsupports a bewildering variety of quoting mechanisms [5]. Empirically,\n\n \"`^(?:\\s)?(?:\\^{})?$`\"\n\ndoesn't work (the backticks don't suppress superscripting).\n\nA pedestrian option is\n\n \"`{caret}(?:\\s)?(?:{backslash}{caret}\\{\\})?$`\"\n\nor\n\n \"`{caret}(?:\\s)?(?:{backslash}{caret}{})?$`\"\n\nOr the whole blob can be quoted en masse using $$:\n\n \"`$$^(?:\\s)?(?:\\^{})?$$$`\"\n\nI don't know whether it treats the last dollar signs as \"$$ $\" or \"$\n$$\", but either way the result looks OK.\n\nI can't believe I spent my whole morning on this :-(\n\nMichael\n\n[1]\nhttp://www.methods.co.nz/asciidoc/userguide.html#_superscripts_and_subscripts\n[2]\nhttp://www.methods.co.nz/asciidoc/userguide.html#_simple_attributes_references\n[3] http://www.methods.co.nz/asciidoc/userguide.html#X51\n[4] http://www.methods.co.nz/asciidoc/userguide.html#_attribute_references\n[5] http://www.methods.co.nz/asciidoc/userguide.html#X77\n\n-- \nMichael Haggerty\nmhagger@alum.mit.edu\nhttp://softwareswirl.blogspot.com/\n"},{"id":"179581","messageId":"4EC3A45F.9080005@alum.mit.edu","threadId":"28721","inReplyTo":"4EC34FA5.2020809@alum.mit.edu","subject":"Re: [PATCH] git-show-ref: fix escaping in asciidoc source","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2011-11-16T11:54:07Z","receivedAt":"2011-11-16T11:54:07Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 11/16/2011 06:52 AM, Michael Haggerty wrote:\n> On 11/15/2011 08:16 PM, Junio C Hamano wrote:\n>> Michael Haggerty writes:\n>>> Did this one fall through the cracks? I don't see it in your tree.\n>>\n>> Yeah, I was wondering if we can have a concise description in what context\n>> any \"^\" must be spelled as {caret} and what other context \"^\" can be\n>> spelled literally, and possibly which versions of AsciiDoc toolchain have\n>> this issue [*1*]. Without a clear guideline, people may unknowingly use\n>> literal \"^\" to new paragraphs, or perhaps worse yet, spell {caret} that\n>> end up being shown literally.\n>>\n>> Since I didn't find a clear pattern other than that \"^\" can and should be\n>> literally given in a literal paragraph (i.e. an indented paragraph or\n>> inside a listing/literal block that shows program examples), I was meaning\n>> to ask you if you knew the rules better than I did, and I stopped there,\n>> forgetting to follow through.\n> \n> I didn't know anything about asciidoc, and just tried to fix it using a\n> bit of cargo-cult programming. [...]\n> \n> I can't believe I spent my whole morning on this :-(\n\nThere are a couple of FAQ entries on the asciidoc site that are relevant\n(excerpted; click on the links in the footnotes for the full text):\n\n====================================================================\n\n35 [1]. How can I place a backslash character in front of an attribute\nreference without escaping the reference?\n\nUse the predefined {backslash} attribute reference instead of an actual\nbackslash [...]\n\n36 [2]. How can I escape AsciiDoc markup?\n\nMost AsciiDoc inline elements can be suppressed by preceding them with a\nbackslash character. These elements include: [...] But there are\nexceptions — see the next question.\n\n37 [3]. Some elements can’t be escaped with a single backslash\n\nThere are a number of exceptions to the usual single backslash rule — \nmostly relating to URL macros that have two syntaxes or quoting\nambiguity. Here are some non-standard escape examples: [...] A\nwork-around for difficult cases is to side-step the problem using the\npass:[] passthrough inline macro.\nNote Escaping is unnecessary inside inline literal passthroughs\n(backtick quoted text).\n\n51 [4]. How can I selectively disable a quoted text substitution?\n\nOmitting the tag name will disable quoting. For example, if you don’t\nwant superscripts or subscripts then put the following in a custom\nconfiguration file or edit the global asciidoc.conf configuration file:\n\n[quotes]\n^=\n~=\n\nAlternatively you can set the configuration entries from within your\ndocument, the above examples are equivalent to:\n\n:quotes.^:\n:quotes.~:\n\n====================================================================\n\nGiven that the git documentation uses lots of \"^\" and \"~\" but probably\nno subscripting or superscripting, it seems like the suggestion in FAQ\nentry 51 would be helpful. But unfortunately it chokes version 8.5.2 of\nasciidoc, which is what I have installed. So it is probably too new to\nbe appropriate for git use.\n\nI also did a check to see whether other sub/superscripts are present in\nthe git documentation:\n\n make all doc\n find Documentation -type f -name '*.html' -print0 |\n xargs -0 grep -nE -e ''\n\nThe only hit was the one under discussion, in git-show-ref.html. (This\nis no check that \"^\" and \"~\" are always quoted, but only that they don't\nappear unquoted in pairs.)\n\nMichael\n\n[1]\nhttp://www.methods.co.nz/asciidoc/faq.html#_how_can_i_place_a_backslash_character_in_front_of_an_attribute_reference_without_escaping_the_reference\n[2]\nhttp://www.methods.co.nz/asciidoc/faq.html#_how_can_i_escape_asciidoc_markup\n[3]\nhttp://www.methods.co.nz/asciidoc/faq.html#_some_elements_can_8217_t_be_escaped_with_a_single_backslash\n[4]\nhttp://www.methods.co.nz/asciidoc/faq.html#_how_can_i_selectively_disable_a_quoted_text_substitution\n\n-- \nMichael Haggerty\nmhagger@alum.mit.edu\nhttp://softwareswirl.blogspot.com/\n"},{"id":"179585","messageId":"201111161408.50700.trast@student.ethz.ch","threadId":"28721","inReplyTo":"4EC3A45F.9080005@alum.mit.edu","subject":"Re: [PATCH] git-show-ref: fix escaping in asciidoc source","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2011-11-16T13:08:50Z","receivedAt":"2011-11-16T13:08:50Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Michael Haggerty wrote:\n> 36 [2]. How can I escape AsciiDoc markup?\n> \n> Most AsciiDoc inline elements can be suppressed by preceding them with a\n> backslash character. These elements include: [...] But there are\n> exceptions — see the next question.\n[...]\n> Note Escaping is unnecessary inside inline literal passthroughs\n> (backtick quoted text).\n\nBeware! We actively change the inline literal quoting behaviour to\nensure consistent output with different versions of asciidoc. See\nthis commit:\n\ncommit 71c020c53ec472b04678237d8fe5687f2299db2a\nAuthor: Thomas Rast \nDate: Sat Jul 25 14:06:50 2009 +0200\n\n Disable asciidoc 8.4.1+ semantics for `{plus}` and friends\n \n asciidoc 8.4.1 changed the semantics of inline backtick quoting so\n that they disable parsing of inline constructs, i.e.,\n \n Input:\t`{plus}`\n Pre 8.4.1:\t+\n Post 8.4.1:\t{plus}\n \n Fix this by defining the asciidoc attribute 'no-inline-literal'\n (which, per the 8.4.1 changelog, is the toggle to return to the old\n behaviour) when under ASCIIDOC8.\n \n Signed-off-by: Thomas Rast \n Signed-off-by: Junio C Hamano \n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"}]}