{"thread":{"id":"41224","subject":"[PATCH] Documentation: remove unnecessary backslashes","startedAt":"2016-01-20T17:21:37Z","lastAt":"2016-01-22T02:46:12Z","messageCount":6,"participants":["Matt Kraai","Jeff King","Junio C Hamano","brian m. carlson"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"276441","messageId":"1453310497-7971-1-git-send-email-kraai@ftbfs.org","threadId":"41224","inReplyTo":null,"subject":"[PATCH] Documentation: remove unnecessary backslashes","fromName":"Matt Kraai","fromEmail":"kraai@ftbfs.org","sentAt":"2016-01-20T17:21:37Z","receivedAt":"2016-01-20T17:21:37Z","isPatch":true,"sender":{"key":"kraai@ftbfs.org","avatar":null},"body":"From: Matthew Kraai <matt.kraai@abbott.com>\n\nasciidoctor does not remove backslashes used to escape curly brackets from\nthe HTML output if the contents of the curly brackets are empty or contain\nat least a <, -, or space.  asciidoc does not require the backslashes in\nthese cases, so just remove them.\n\nSigned-off-by: Matthew Kraai <matt.kraai@abbott.com>\nReported-by: Philip Oakley <philipoakley@iee.org>\n---\n Documentation/revisions.txt | 20 ++++++++++----------\n 1 file changed, 10 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex d85e303..fa4bdb2 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -61,11 +61,11 @@ some output processing may assume ref names in UTF-8.\n '@'::\n   '@' alone is a shortcut for 'HEAD'.\n \n-'<refname>@\\{<date>\\}', e.g. 'master@\\{yesterday\\}', 'HEAD@\\{5 minutes ago\\}'::\n+'<refname>@{<date>}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n   A ref followed by the suffix '@' with a date specification\n   enclosed in a brace\n-  pair (e.g. '\\{yesterday\\}', '\\{1 month 2 weeks 3 days 1 hour 1\n-  second ago\\}' or '\\{1979-02-26 18:30:00\\}') specifies the value\n+  pair (e.g. '\\{yesterday\\}', '{1 month 2 weeks 3 days 1 hour 1\n+  second ago}' or '{1979-02-26 18:30:00}') specifies the value\n   of the ref at a prior point in time.  This suffix may only be\n   used immediately following a ref name and the ref must have an\n   existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state\n@@ -73,7 +73,7 @@ some output processing may assume ref names in UTF-8.\n   'master' branch last week. If you want to look at commits made during\n   certain times, see '--since' and '--until'.\n \n-'<refname>@\\{<n>\\}', e.g. 'master@\\{1\\}'::\n+'<refname>@{<n>}', e.g. 'master@\\{1\\}'::\n   A ref followed by the suffix '@' with an ordinal specification\n   enclosed in a brace pair (e.g. '\\{1\\}', '\\{15\\}') specifies\n   the n-th prior value of that ref.  For example 'master@\\{1\\}'\n@@ -82,13 +82,13 @@ some output processing may assume ref names in UTF-8.\n   immediately following a ref name and the ref must have an existing\n   log ('$GIT_DIR/logs/<refname>').\n \n-'@\\{<n>\\}', e.g. '@\\{1\\}'::\n+'@{<n>}', e.g. '@\\{1\\}'::\n   You can use the '@' construct with an empty ref part to get at a\n   reflog entry of the current branch. For example, if you are on\n   branch 'blabla' then '@\\{1\\}' means the same as 'blabla@\\{1\\}'.\n \n-'@\\{-<n>\\}', e.g. '@\\{-1\\}'::\n-  The construct '@\\{-<n>\\}' means the <n>th branch/commit checked out\n+'@{-<n>}', e.g. '@{-1}'::\n+  The construct '@{-<n>}' means the <n>th branch/commit checked out\n   before the current one.\n \n '<branchname>@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n@@ -139,7 +139,7 @@ from one location and push to another. In a non-triangular workflow,\n   '<rev>{caret}1{caret}1{caret}1'.  See below for an illustration of\n   the usage of this form.\n \n-'<rev>{caret}\\{<type>\\}', e.g. 'v0.99.8{caret}\\{commit\\}'::\n+'<rev>{caret}{<type>}', e.g. 'v0.99.8{caret}\\{commit\\}'::\n   A suffix '{caret}' followed by an object type name enclosed in\n   brace pair means dereference the object at '<rev>' recursively until\n   an object of type '<type>' is found or the object cannot be\n@@ -159,13 +159,13 @@ it does not have to be dereferenced even once to get to an object.\n 'rev{caret}\\{tag\\}' can be used to ensure that 'rev' identifies an\n existing tag object.\n \n-'<rev>{caret}\\{\\}', e.g. 'v0.99.8{caret}\\{\\}'::\n+'<rev>{caret}{}', e.g. 'v0.99.8{caret}{}'::\n   A suffix '{caret}' followed by an empty brace pair\n   means the object could be a tag,\n   and dereference the tag recursively until a non-tag object is\n   found.\n \n-'<rev>{caret}\\{/<text>\\}', e.g. 'HEAD^{/fix nasty bug}'::\n+'<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}'::\n   A suffix '{caret}' to a revision parameter, followed by a brace\n   pair that contains a text led by a slash,\n   is the same as the ':/fix nasty bug' syntax below except that\n-- \n2.7.0.windows.1\n"},{"id":"276443","messageId":"20160120182421.GA27562@sigill.intra.peff.net","threadId":"41224","inReplyTo":"1453310497-7971-1-git-send-email-kraai@ftbfs.org","subject":"Re: [PATCH] Documentation: remove unnecessary backslashes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-01-20T18:24:21Z","receivedAt":"2016-01-20T18:24:21Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jan 20, 2016 at 09:21:37AM -0800, Matt Kraai wrote:\n\n> From: Matthew Kraai <matt.kraai@abbott.com>\n> \n> asciidoctor does not remove backslashes used to escape curly brackets from\n> the HTML output if the contents of the curly brackets are empty or contain\n> at least a <, -, or space.  asciidoc does not require the backslashes in\n> these cases, so just remove them.\n\nI think these backslashes may have been necessary in older versions of\nasciidoc, but I don't recall the details. Looks like we did a similar\nround of cleanups already in 4538a88256, so this is probably safe (and I\nverified with asciidoc 8.6.9 that the generated output is the same).\n\n> -'<refname>@\\{<date>\\}', e.g. 'master@\\{yesterday\\}', 'HEAD@\\{5 minutes ago\\}'::\n> +'<refname>@{<date>}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n\nI see you didn't tweak the middle one here, because it _does_ look like\nan attribute. Does asciidoctor actually remove the backslashes there?\n\n> -'<refname>@\\{<n>\\}', e.g. 'master@\\{1\\}'::\n> +'<refname>@{<n>}', e.g. 'master@\\{1\\}'::\n\nDitto here for \"1\". IMHO asciidoctor's behavior is somewhat crazy, as it\nmeans you have to know arcane quoting rules to get correct output (you\ncannot just err on the side of quoting). But it's probably still worth\nworking around.\n\n-Peff\n"},{"id":"276446","messageId":"xmqqmvs05722.fsf@gitster.mtv.corp.google.com","threadId":"41224","inReplyTo":"20160120182421.GA27562@sigill.intra.peff.net","subject":"Re: [PATCH] Documentation: remove unnecessary backslashes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-01-20T20:28:53Z","receivedAt":"2016-01-20T20:28:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> On Wed, Jan 20, 2016 at 09:21:37AM -0800, Matt Kraai wrote:\n>\n>> From: Matthew Kraai <matt.kraai@abbott.com>\n>> \n>> asciidoctor does not remove backslashes used to escape curly brackets from\n>> the HTML output if the contents of the curly brackets are empty or contain\n>> at least a <, -, or space.  asciidoc does not require the backslashes in\n>> these cases, so just remove them.\n>\n> I think these backslashes may have been necessary in older versions of\n> asciidoc, but I don't recall the details. Looks like we did a similar\n> round of cleanups already in 4538a88256, so this is probably safe (and I\n> verified with asciidoc 8.6.9 that the generated output is the same).\n>\n>> -'<refname>@\\{<date>\\}', e.g. 'master@\\{yesterday\\}', 'HEAD@\\{5 minutes ago\\}'::\n>> +'<refname>@{<date>}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n>\n> I see you didn't tweak the middle one here, because it _does_ look like\n> an attribute. Does asciidoctor actually remove the backslashes there?\n\nA more important question is if it works without the backslashes.\nIf not-too-stale versions of asciidoc everybody uses these days are\nall OK without braces quoted with backslashes, and if the same holds\ntrue for asciidoctor, then we would want consistency here.\n\nOn the other hand, if this line must be spelled like the above to\nplease asciidoctor, i.e. the first and the last must not have\nbackslashes and the second must have backslashes, I'd have to say\nwe have a bigger problem.  Perhaps asciidoctor needs to be fixed\nuntil normal people like we can rely on it.\n"},{"id":"276448","messageId":"20160120203430.GB6092@sigill.intra.peff.net","threadId":"41224","inReplyTo":"xmqqmvs05722.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation: remove unnecessary backslashes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-01-20T20:34:30Z","receivedAt":"2016-01-20T20:34:30Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jan 20, 2016 at 12:28:53PM -0800, Junio C Hamano wrote:\n\n> >> -'<refname>@\\{<date>\\}', e.g. 'master@\\{yesterday\\}', 'HEAD@\\{5 minutes ago\\}'::\n> >> +'<refname>@{<date>}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n> >\n> > I see you didn't tweak the middle one here, because it _does_ look like\n> > an attribute. Does asciidoctor actually remove the backslashes there?\n> \n> A more important question is if it works without the backslashes.\n> If not-too-stale versions of asciidoc everybody uses these days are\n> all OK without braces quoted with backslashes, and if the same holds\n> true for asciidoctor, then we would want consistency here.\n\nThe answer to that is implied in the original commit message; no, it\ndoes not work, because it is syntactically an asciidoc attribute.\n\n> On the other hand, if this line must be spelled like the above to\n> please asciidoctor, i.e. the first and the last must not have\n> backslashes and the second must have backslashes, I'd have to say\n> we have a bigger problem.  Perhaps asciidoctor needs to be fixed\n> until normal people like we can rely on it.\n\nYeah, that is the \"insane\" part I mentioned. It _does_ make sense\nsyntactically (\"-1\" cannot possibly be an attribute name, so it does not\nparse as one), but I do not like the degree to which writers must know\nall of the arcane syntax rules (and cannot rely on something simple like\n\"{ is special, so I must escape it, and over-escaping is not a\nproblem\").\n\n-Peff\n"},{"id":"276456","messageId":"20160120213512.GA10192@ftbfs.org","threadId":"41224","inReplyTo":"20160120182421.GA27562@sigill.intra.peff.net","subject":"Re: [PATCH] Documentation: remove unnecessary backslashes","fromName":"Matt Kraai","fromEmail":"kraai@ftbfs.org","sentAt":"2016-01-20T21:35:12Z","receivedAt":"2016-01-20T21:35:12Z","isPatch":true,"sender":{"key":"kraai@ftbfs.org","avatar":null},"body":"Hi,\n\nOn Wed, Jan 20, 2016 at 01:24:21PM -0500, Jeff King wrote:\n> On Wed, Jan 20, 2016 at 09:21:37AM -0800, Matt Kraai wrote:\n> > -'<refname>@\\{<date>\\}', e.g. 'master@\\{yesterday\\}', 'HEAD@\\{5 minutes ago\\}'::\n> > +'<refname>@{<date>}', e.g. 'master@\\{yesterday\\}', 'HEAD@{5 minutes ago}'::\n> \n> I see you didn't tweak the middle one here, because it _does_ look like\n> an attribute. Does asciidoctor actually remove the backslashes there?\n\nYes, asciidoctor appears to remove the backslashes in some cases but\nnot others.  I removed the backslashes from the source if it did not\nremove them.  I verified that the asciidoc output isn't affected.\n\n> > -'<refname>@\\{<n>\\}', e.g. 'master@\\{1\\}'::\n> > +'<refname>@{<n>}', e.g. 'master@\\{1\\}'::\n> \n> Ditto here for \"1\". IMHO asciidoctor's behavior is somewhat crazy, as it\n> means you have to know arcane quoting rules to get correct output (you\n> cannot just err on the side of quoting). But it's probably still worth\n> working around.\n\nI couldn't find any documentation of asciidoctor's behavior.  I didn't\ntry figuring the behavior out from asciidoctor's source code.\n\n-- \nMatt                                           https://ftbfs.org/~kraai/\n"},{"id":"276528","messageId":"20160122024612.GB686558@vauxhall.crustytoothpaste.net","threadId":"41224","inReplyTo":"20160120203430.GB6092@sigill.intra.peff.net","subject":"Re: [PATCH] Documentation: remove unnecessary backslashes","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2016-01-22T02:46:12Z","receivedAt":"2016-01-22T02:46:12Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Wed, Jan 20, 2016 at 03:34:30PM -0500, Jeff King wrote:\n> On Wed, Jan 20, 2016 at 12:28:53PM -0800, Junio C Hamano wrote:\n> > On the other hand, if this line must be spelled like the above to\n> > please asciidoctor, i.e. the first and the last must not have\n> > backslashes and the second must have backslashes, I'd have to say\n> > we have a bigger problem.  Perhaps asciidoctor needs to be fixed\n> > until normal people like we can rely on it.\n> \n> Yeah, that is the \"insane\" part I mentioned. It _does_ make sense\n> syntactically (\"-1\" cannot possibly be an attribute name, so it does not\n> parse as one), but I do not like the degree to which writers must know\n> all of the arcane syntax rules (and cannot rely on something simple like\n> \"{ is special, so I must escape it, and over-escaping is not a\n> problem\").\n\nThe underlying issue is that both AsciiDoc and Asciidoctor use regexps\nto parse their data, which we all know is a bad idea.  Asciidoctor does\nless forward looking because it's much faster, so it's a bit less\nflexible with overescaping.\n\nThere are plans for Asciidoctor to move to a defined grammar at some\npoint, which should hopefully make things a bit less insane.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187\n"}]}