{"thread":{"id":"32347","subject":"[PATCH] Documentation: don't link to example mail addresses","startedAt":"2012-12-15T15:03:15Z","lastAt":"2012-12-17T19:57:33Z","messageCount":12,"participants":["John Keeping","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"204909","messageId":"20121215150314.GC2725@river.lan","threadId":"32347","inReplyTo":null,"subject":"[PATCH] Documentation: don't link to example mail addresses","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2012-12-15T15:03:15Z","receivedAt":"2012-12-15T15:03:15Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"Mail addresses in documentation are converted into mailto: hyperlinks in\nthe HTML output and footnotes in man pages. This isn't desirable for\ncases where the address is used as an example and is not valid.\n\nParticularly annoying is the example \"jane@laptop.(none)\" which appears\nin git-shortlog(1) as \"jane@laptop[1].(none)\", with note 1 saying:\n\n\t1. jane@laptop\n\t mailto:jane@laptop\n\nFix this by quoting example mail addresses with \"$$\", preventing\nAsciidoc from processing them.\n\nIn the case of mailmap.txt, render the address monospaced so that it\nmatches the block examples surrounding that paragraph.\n\nSigned-off-by: John Keeping \n---\n\nI can't see any other uses of the \"$$\" quote in the documentation, so\nit's probably worth noting that I've tested this with Asciidoc 8.6.8,\nalthough I can't see anything in the changelog to indicate that\nAsciidoc's treatment of it has changed recently.\n\n Documentation/git-fast-import.txt | 2 +-\n Documentation/git-tag.txt | 2 +-\n Documentation/mailmap.txt | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex d1844ea..05913cc 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -427,7 +427,7 @@ they made it.\n \n Here `` is the person's display name (for example\n ``Com M Itter'') and `` is the person's email address\n-(``cm@example.com''). `LT` and `GT` are the literal less-than (\\x3c)\n+(``$$cm@example.com$$''). `LT` and `GT` are the literal less-than (\\x3c)\n and greater-than (\\x3e) symbols. These are required to delimit\n the email address from the other fields in the line. Note that\n `` and `` are free-form and may contain any sequence\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 247534e..ed63edb 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -129,7 +129,7 @@ This option is only applicable when listing tags without annotation lines.\n CONFIGURATION\n -------------\n By default, 'git tag' in sign-with-default mode (-s) will use your\n-committer identity (of the form \"Your Name \") to\n+committer identity (of the form \"Your Name $$$$\") to\n find a key. If you want to use a different default key, you can specify\n it in the repository configuration as follows:\n \ndiff --git a/Documentation/mailmap.txt b/Documentation/mailmap.txt\nindex 288f04e..dd89fca 100644\n--- a/Documentation/mailmap.txt\n+++ b/Documentation/mailmap.txt\n@@ -46,7 +46,7 @@ Jane Doe \n Joe R. Developer \n ------------\n \n-Note how there is no need for an entry for , because the\n+Note how there is no need for an entry for ``, because the\n real name of that author is already correct.\n \n Example 2: Your repository contains commits from the following\n-- \n1.8.0\n"},{"id":"204910","messageId":"20121215172018.GA18696@sigill.intra.peff.net","threadId":"32347","inReplyTo":"20121215150314.GC2725@river.lan","subject":"Re: [PATCH] Documentation: don't link to example mail addresses","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-12-15T17:20:18Z","receivedAt":"2012-12-15T17:20:18Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Dec 15, 2012 at 03:03:15PM +0000, John Keeping wrote:\n\n> Mail addresses in documentation are converted into mailto: hyperlinks in\n> the HTML output and footnotes in man pages. This isn't desirable for\n> cases where the address is used as an example and is not valid.\n> \n> Particularly annoying is the example \"jane@laptop.(none)\" which appears\n> in git-shortlog(1) as \"jane@laptop[1].(none)\", with note 1 saying:\n> \n> \t1. jane@laptop\n> \t mailto:jane@laptop\n\nThanks, this is definitely worth fixing.\n\n> Fix this by quoting example mail addresses with \"$$\", preventing\n> Asciidoc from processing them.\n> \n> In the case of mailmap.txt, render the address monospaced so that it\n> matches the block examples surrounding that paragraph.\n\nI think I'd just render them monospace everywhere. We are very\ninconsistent about which form of quotes we use in the documentation (I\nthink because most of the developers read the source directly and not\nthe rendered asciidoc). And then we don't have to worry about the \"$$\"\nconstruct (and IMHO it makes the source much more readable, and marking\nthe address as a literal looks good in the output, too).\n\n-Peff\n"},{"id":"204918","messageId":"7vy5gztcu1.fsf@alter.siamese.dyndns.org","threadId":"32347","inReplyTo":"20121215172018.GA18696@sigill.intra.peff.net","subject":"Re: [PATCH] Documentation: don't link to example mail addresses","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-15T18:00:38Z","receivedAt":"2012-12-15T18:00:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I think I'd just render them monospace everywhere. We are very\n> inconsistent about which form of quotes we use in the documentation (I\n> think because most of the developers read the source directly and not\n> the rendered asciidoc). And then we don't have to worry about the \"$$\"\n> construct (and IMHO it makes the source much more readable, and marking\n> the address as a literal looks good in the output, too).\n\nAgreed---thanks for spotting, John, and thanks for showing the\noverall direction, Peff.\n"},{"id":"204929","messageId":"20121215182408.GD2725@river.lan","threadId":"32347","inReplyTo":"20121215172018.GA18696@sigill.intra.peff.net","subject":"Re: [PATCH] Documentation: don't link to example mail addresses","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2012-12-15T18:24:09Z","receivedAt":"2012-12-15T18:24:09Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Sat, Dec 15, 2012 at 12:20:18PM -0500, Jeff King wrote:\n> On Sat, Dec 15, 2012 at 03:03:15PM +0000, John Keeping wrote:\n>> Mail addresses in documentation are converted into mailto: hyperlinks in\n>> the HTML output and footnotes in man pages. This isn't desirable for\n>> cases where the address is used as an example and is not valid.\n>> \n>> Particularly annoying is the example \"jane@laptop.(none)\" which appears\n>> in git-shortlog(1) as \"jane@laptop[1].(none)\", with note 1 saying:\n>> \n>> \t1. jane@laptop\n>> \t mailto:jane@laptop\n> \n> Thanks, this is definitely worth fixing.\n> \n>> Fix this by quoting example mail addresses with \"$$\", preventing\n>> Asciidoc from processing them.\n>> \n>> In the case of mailmap.txt, render the address monospaced so that it\n>> matches the block examples surrounding that paragraph.\n> \n> I think I'd just render them monospace everywhere. We are very\n> inconsistent about which form of quotes we use in the documentation (I\n> think because most of the developers read the source directly and not\n> the rendered asciidoc). And then we don't have to worry about the \"$$\"\n> construct (and IMHO it makes the source much more readable, and marking\n> the address as a literal looks good in the output, too).\n\nI agree that the source is more readable as monospaced, but I think we\nneed to keep the quotes around the text in git-tag(1) and probably\ngit-fast-import(1) so that it is differentiated from the surrounding\ntext in the man page output.\n\nI just tried this and got strange results. Taking the example in\ngit-tag(1):\n\n ...of the form ``Your Name ''\n\nI tried this to preserve the quotes and make the entire quoted text\nmonospaced (I don't think we want to have just the email address\nmonospaced):\n\n ...of the form ```Your Name `''\n\nwhich had the desired effect - smart quotes and everything inside\nrendered monospaced - BUT the email address is hyperlinked!\n\nSwitching the smart Asciidoc double quotes (``...'') for \"normal\" double\nquotes (\"...\") produces the desired result, but IMHO doesn't look quite\nas good (on the other hand it looks like there are many more use of\n\"...\" than ``...'' in the Git documentation).\n\n[While searching, the only other example I could find is in\ngit-commit(1) where `A U Thor ` is rendered\nmonospaced without quotes, but I think this hurts readability in the man\npage output - expect a follow-up patch if we resolve this in the\ndirection of having quotes and monospaced text.]\n\nAt this point I've exhausted my Asciidoc knowledge and I'm not entirely\nhappy with any of these options. Suggestions?\n\nJohn\n"},{"id":"204965","messageId":"20121216120405.GA14320@sigill.intra.peff.net","threadId":"32347","inReplyTo":"20121215182408.GD2725@river.lan","subject":"Re: [PATCH] Documentation: don't link to example mail addresses","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-12-16T12:04:05Z","receivedAt":"2012-12-16T12:04:05Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Dec 15, 2012 at 06:24:09PM +0000, John Keeping wrote:\n\n> > I think I'd just render them monospace everywhere. We are very\n> > inconsistent about which form of quotes we use in the documentation (I\n> > think because most of the developers read the source directly and not\n> > the rendered asciidoc). And then we don't have to worry about the \"$$\"\n> > construct (and IMHO it makes the source much more readable, and marking\n> > the address as a literal looks good in the output, too).\n> \n> I agree that the source is more readable as monospaced, but I think we\n> need to keep the quotes around the text in git-tag(1) and probably\n> git-fast-import(1) so that it is differentiated from the surrounding\n> text in the man page output.\n\nHmm, good point. I use MAN_BOLD_LITERAL, which serves that purpose, but\nI guess not everyone does (and it is not the default; I wonder if it\nshould be). But if MAN_BOLD_LITERAL is not in use, then `` literals\nhave zero typographical impact in the manpages.\n\nSo maybe we do need to do something else. I was just hoping we could get\naway with something more readable in the source.\n\nBy my reading of the asciidoc user guide, the mechanism that is hurting\nus is that mailto is an inline macro, and that foo@bar automatically\ntriggers that inline macro. Furthermore, the right way to suppress\nexpansion of macros is with a backslash escape. Doing this:\n\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex d1844ea..68bca1a 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -427,7 +427,7 @@ Here `` is the person's display name (for example\n \n Here `` is the person's display name (for example\n ``Com M Itter'') and `` is the person's email address\n-(``cm@example.com''). `LT` and `GT` are the literal less-than (\\x3c)\n+(``\\cm@example.com''). `LT` and `GT` are the literal less-than (\\x3c)\n and greater-than (\\x3e) symbols. These are required to delimit\n the email address from the other fields in the line. Note that\n `` and `` are free-form and may contain any sequence\n\nseems to produce the output we want. I think it's a little less ugly\nthan the \"$$\" quoting, but not by much. No clue if one is accepted by\nmore asciidoc versions or not.\n\n-Peff\n"},{"id":"204967","messageId":"20121216140029.GE2725@river.lan","threadId":"32347","inReplyTo":"20121216120405.GA14320@sigill.intra.peff.net","subject":"[PATCH v2] Documentation: don't link to example mail addresses","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2012-12-16T14:00:29Z","receivedAt":"2012-12-16T14:00:29Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"Email addresses in documentation are converted into mailto: hyperlinks\nin the HTML output and footnotes in man pages. This isn't desirable for\ncases where the address is used as an example and is not valid.\n\nParticularly annoying is the example \"jane@laptop.(none)\" which appears\nin git-shortlog(1) as \"jane@laptop[1].(none)\", with note 1 saying:\n\n\t1. jane@laptop\n\t mailto:jane@laptop\n\nFix this by escaping these email addresses with a leading backslash, to\nprevent Asciidoc expanding them as inline macros.\n\nIn the case of mailmap.txt, render the address monospaced so that it\nmatches the block examples surrounding that paragraph.\n\nHelped-by: Jeff King \nSigned-off-by: John Keeping \n---\n\nOn Sun, Dec 16, 2012 at 07:04:05AM -0500, Jeff King wrote:\n> Furthermore, the right way to suppress\n> expansion of macros is with a backslash escape.\n[snipped an example]\n> I think it's a little less ugly\n> than the \"$$\" quoting, but not by much. No clue if one is accepted by\n> more asciidoc versions or not.\n\n>From a quick reading of the Asciidoc changelog, I think backslash\nescaping should be supported just as well as \"$$\" quoting, which leaves\nthe minimal patch looking like this.\n\n Documentation/git-fast-import.txt | 2 +-\n Documentation/git-tag.txt | 2 +-\n Documentation/mailmap.txt | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex d1844ea..68bca1a 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -427,7 +427,7 @@ they made it.\n \n Here `` is the person's display name (for example\n ``Com M Itter'') and `` is the person's email address\n-(``cm@example.com''). `LT` and `GT` are the literal less-than (\\x3c)\n+(``\\cm@example.com''). `LT` and `GT` are the literal less-than (\\x3c)\n and greater-than (\\x3e) symbols. These are required to delimit\n the email address from the other fields in the line. Note that\n `` and `` are free-form and may contain any sequence\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 247534e..2f1c0c3 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -129,7 +129,7 @@ This option is only applicable when listing tags without annotation lines.\n CONFIGURATION\n -------------\n By default, 'git tag' in sign-with-default mode (-s) will use your\n-committer identity (of the form \"Your Name \") to\n+committer identity (of the form \"Your Name <\\your@email.address>\") to\n find a key. If you want to use a different default key, you can specify\n it in the repository configuration as follows:\n \ndiff --git a/Documentation/mailmap.txt b/Documentation/mailmap.txt\nindex 288f04e..dd89fca 100644\n--- a/Documentation/mailmap.txt\n+++ b/Documentation/mailmap.txt\n@@ -46,7 +46,7 @@ Jane Doe \n Joe R. Developer \n ------------\n \n-Note how there is no need for an entry for , because the\n+Note how there is no need for an entry for ``, because the\n real name of that author is already correct.\n \n Example 2: Your repository contains commits from the following\n-- \n1.8.0.2\n"},{"id":"204977","messageId":"7vd2y9rfxu.fsf@alter.siamese.dyndns.org","threadId":"32347","inReplyTo":"20121216140029.GE2725@river.lan","subject":"Re: [PATCH v2] Documentation: don't link to example mail addresses","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-16T18:48:45Z","receivedAt":"2012-12-16T18:48:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"John Keeping writes:\n\n> Email addresses in documentation are converted into mailto: hyperlinks\n> in the HTML output and footnotes in man pages. This isn't desirable for\n> cases where the address is used as an example and is not valid.\n>\n> Particularly annoying is the example \"jane@laptop.(none)\" which appears\n> in git-shortlog(1) as \"jane@laptop[1].(none)\", with note 1 saying:\n>\n> \t1. jane@laptop\n> \t mailto:jane@laptop\n>\n> Fix this by escaping these email addresses with a leading backslash, to\n> prevent Asciidoc expanding them as inline macros.\n>\n> In the case of mailmap.txt, render the address monospaced so that it\n> matches the block examples surrounding that paragraph.\n>\n> Helped-by: Jeff King \n> Signed-off-by: John Keeping \n> ---\n>\n> On Sun, Dec 16, 2012 at 07:04:05AM -0500, Jeff King wrote:\n>> Furthermore, the right way to suppress\n>> expansion of macros is with a backslash escape.\n> [snipped an example]\n>> I think it's a little less ugly\n>> than the \"$$\" quoting, but not by much. No clue if one is accepted by\n>> more asciidoc versions or not.\n>\n> From a quick reading of the Asciidoc changelog, I think backslash\n> escaping should be supported just as well as \"$$\" quoting, which leaves\n> the minimal patch looking like this.\n\nThe patch looks reasonable to me, too. We were bitten by relying on\nthe description in AsciiDoc documentation (which shows the state of\ntheir latest software) before; between the constructs that work, it\nis safer to use the older, more vanilla and more common one.\n\nThanks.\n"},{"id":"204998","messageId":"7vehippg91.fsf@alter.siamese.dyndns.org","threadId":"32347","inReplyTo":"20121216140029.GE2725@river.lan","subject":"Re: [PATCH v2] Documentation: don't link to example mail addresses","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T02:24:58Z","receivedAt":"2012-12-17T02:24:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"John Keeping writes:\n\n> diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\n> index d1844ea..68bca1a 100644\n> --- a/Documentation/git-fast-import.txt\n> +++ b/Documentation/git-fast-import.txt\n> @@ -427,7 +427,7 @@ they made it.\n> \n> Here `` is the person's display name (for example\n> ``Com M Itter'') and `` is the person's email address\n> -(``cm@example.com''). `LT` and `GT` are the literal less-than (\\x3c)\n> +(``\\cm@example.com''). `LT` and `GT` are the literal less-than (\\x3c)\n\nI seem to be getting\n\n(`\\cm@example.com''). `LT and GT are the literal less-than (\\x3c)\n\nout of this part in the resulting HTML output, which is probably not\nwhat you wanted to see.\n\nI have a feeling that it might be a better solution to stop using\nthese pretty quotes. It's not like we use them a lot and a quick\nscanning of \"git grep '``'\" output seems to tell me that many of\nthem should be `monospace output`, and the rest (mostly references\nto section headers) can be \"Section\".\n"},{"id":"205007","messageId":"7vobhtnt57.fsf@alter.siamese.dyndns.org","threadId":"32347","inReplyTo":"20121215150314.GC2725@river.lan","subject":"Re: [PATCH] Documentation: don't link to example mail addresses","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T05:29:24Z","receivedAt":"2012-12-17T05:29:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"John Keeping writes:\n\n> I can't see any other uses of the \"$$\" quote in the documentation, so\n> it's probably worth noting that I've tested this with Asciidoc 8.6.8,\n> although I can't see anything in the changelog to indicate that\n> Asciidoc's treatment of it has changed recently.\n\nThanks.\n\n> Documentation/git-fast-import.txt | 2 +-\n> Documentation/git-tag.txt | 2 +-\n> Documentation/mailmap.txt | 2 +-\n> 3 files changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\n> index d1844ea..05913cc 100644\n> --- a/Documentation/git-fast-import.txt\n> +++ b/Documentation/git-fast-import.txt\n> @@ -427,7 +427,7 @@ they made it.\n> \n> Here `` is the person's display name (for example\n> ``Com M Itter'') and `` is the person's email address\n> -(``cm@example.com''). `LT` and `GT` are the literal less-than (\\x3c)\n> +(``$$cm@example.com$$''). `LT` and `GT` are the literal less-than (\\x3c)\n> and greater-than (\\x3e) symbols. These are required to delimit\n> the email address from the other fields in the line. Note that\n> `` and `` are free-form and may contain any sequence\n\nAsciiDoc 8.5.2 gives this: \n\n asciidoc: WARNING: git-fast-import.txt: line 434: nested inline passthrough\n\nAlso in git-fast-import.1, there is this line:\n\n ... person\\(cqs display name (for example `Com M Itter\\(aq\\(aq) and ` John Keeping writes:\n>> Here `` is the person's display name (for example\n>> ``Com M Itter'') and `` is the person's email address\n>> -(``cm@example.com''). `LT` and `GT` are the literal less-than (\\x3c)\n>> +(``$$cm@example.com$$''). `LT` and `GT` are the literal less-than (\\x3c)\n>> and greater-than (\\x3e) symbols. These are required to delimit\n>> the email address from the other fields in the line. Note that\n>> `` and `` are free-form and may contain any sequence\n> \n> AsciiDoc 8.5.2 gives this: \n> \n> asciidoc: WARNING: git-fast-import.txt: line 434: nested inline passthrough\n> \n> Also in git-fast-import.1, there is this line:\n> \n> ... person\\(cqs display name (for example `Com M Itter\\(aq\\(aq) and ` \n> (notice two leftover `s); not that this is a new issue with this patch.\n> \n> Which is puzzling, because the next input line formats better:\n> \n> ... email address (\\(lqcm@example\\&.com\\(rq)\\&. ...\n\nI wonder if you're hitting this bug, which is listed as fixed in\nAsciiDoc 8.6.0 [1]:\n\n FIXED: Sometimes multiple double quoted text elements in the same\n paragraph were mistakenly seen as starting with an inline literal.\n\nAs you said in your other message, it may be better to avoid using the\npretty quotes, although I don't think just changing them to `monospace\noutput` is sufficient as monospace output is not distinguished in the\ndefault man page output. IMHO that's necessary for any examples that\ncontain whitespace. Perhaps a patch series turning MAN_BOLD_LITERAL on\nby default and then changing these examples to `monospace output`?\n\n\nJohn\n\n[1] http://www.methods.co.nz/asciidoc/CHANGELOG.html#_version_8_6_0_2010_08_16\n"},{"id":"205052","messageId":"20121217120253.GA21858@sigill.intra.peff.net","threadId":"32347","inReplyTo":"7vehippg91.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2] Documentation: don't link to example mail addresses","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-12-17T12:02:54Z","receivedAt":"2012-12-17T12:02:54Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Dec 16, 2012 at 06:24:58PM -0800, Junio C Hamano wrote:\n\n> I seem to be getting\n> \n> (`\\cm@example.com''). `LT and GT are the literal less-than (\\x3c)\n> \n> out of this part in the resulting HTML output, which is probably not\n> what you wanted to see.\n> \n> I have a feeling that it might be a better solution to stop using\n> these pretty quotes. It's not like we use them a lot and a quick\n> scanning of \"git grep '``'\" output seems to tell me that many of\n> them should be `monospace output`, and the rest (mostly references\n> to section headers) can be \"Section\".\n\nTypographically speaking, I would also be just as happy to use regular\ndouble-quotes throughout. But here's an example where they also caused\na problem (which was fixed by moving to smart-quotes in f34e9ed):\n\n http://thread.gmane.org/gmane.comp.version-control.git/163067\n\n-Peff\n"},{"id":"205068","messageId":"7vr4moladu.fsf@alter.siamese.dyndns.org","threadId":"32347","inReplyTo":"20121217120253.GA21858@sigill.intra.peff.net","subject":"Re: [PATCH v2] Documentation: don't link to example mail addresses","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-17T19:57:33Z","receivedAt":"2012-12-17T19:57:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Sun, Dec 16, 2012 at 06:24:58PM -0800, Junio C Hamano wrote:\n>\n>> I seem to be getting\n>> \n>> (`\\cm@example.com''). `LT and GT are the literal less-than (\\x3c)\n>> \n>> out of this part in the resulting HTML output, which is probably not\n>> what you wanted to see.\n>> \n>> I have a feeling that it might be a better solution to stop using\n>> these pretty quotes. It's not like we use them a lot and a quick\n>> scanning of \"git grep '``'\" output seems to tell me that many of\n>> them should be `monospace output`, and the rest (mostly references\n>> to section headers) can be \"Section\".\n>\n> Typographically speaking, I would also be just as happy to use regular\n> double-quotes throughout. But here's an example where they also caused\n> a problem (which was fixed by moving to smart-quotes in f34e9ed):\n>\n> http://thread.gmane.org/gmane.comp.version-control.git/163067\n\nI agree with the typography argument.\n\nMany monospaced fonts used in the windows where the programmers view\nthe source of the docmentation, a 'normal' single quote does not\nslant by the same amount to the `opposite` quote, so ``a pair does\nnot balance'' visually in the source. And the whole point of\nwriting documentation in AsciiDoc is to keep the source readable.\nThe use of pretty quote throws discards that primary benefit of\nchoosing AsciiDoc in the first place.\n"}]}