[PATCH] Documentation: don't link to example mail addresses

Mail addresses in documentation are converted into mailto: hyperlinks in
the HTML output and footnotes in man pages.  This isn't desirable for
cases where the address is used as an example and is not valid.

Particularly annoying is the example "jane@laptop.(none)" which appears
in git-shortlog(1) as "jane@laptop[1].(none)", with note 1 saying:

	1. jane@laptop
	   mailto:jane@laptop

Fix this by quoting example mail addresses with "$$", preventing
Asciidoc from processing them.

In the case of mailmap.txt, render the address monospaced so that it
matches the block examples surrounding that paragraph.

Signed-off-by: John Keeping <redacted>
---

I can't see any other uses of the "$$" quote in the documentation, so
it's probably worth noting that I've tested this with Asciidoc 8.6.8,
although I can't see anything in the changelog to indicate that
Asciidoc's treatment of it has changed recently.

 Documentation/git-fast-import.txt | 2 +-
 Documentation/git-tag.txt         | 2 +-
 Documentation/mailmap.txt         | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index d1844ea..05913cc 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt

@@ -427,7 +427,7 @@ they made it.
 
 Here `<name>` is the person's display name (for example
 ``Com M Itter'') and `<email>` is the person's email address
-(``cm@example.com'').  `LT` and `GT` are the literal less-than (\x3c)
+(``$$cm@example.com$$'').  `LT` and `GT` are the literal less-than (\x3c)
 and greater-than (\x3e) symbols.  These are required to delimit
 the email address from the other fields in the line.  Note that
 `<name>` and `<email>` are free-form and may contain any sequence

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 247534e..ed63edb 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt

@@ -129,7 +129,7 @@ This option is only applicable when listing tags without annotation lines.
 CONFIGURATION
 -------------
 By default, 'git tag' in sign-with-default mode (-s) will use your
-committer identity (of the form "Your Name <your@email.address>") to
+committer identity (of the form "Your Name $$<your@email.address>$$") to
 find a key.  If you want to use a different default key, you can specify
 it in the repository configuration as follows:
 

diff --git a/Documentation/mailmap.txt b/Documentation/mailmap.txt
index 288f04e..dd89fca 100644
--- a/Documentation/mailmap.txt
+++ b/Documentation/mailmap.txt

@@ -46,7 +46,7 @@ Jane Doe         <jane@desktop.(none)>
 Joe R. Developer <joe@example.com>
 ------------
 
-Note how there is no need for an entry for <jane@laptop.(none)>, because the
+Note how there is no need for an entry for `<jane@laptop.(none)>`, because the
 real name of that author is already correct.
 
 Example 2: Your repository contains commits from the following

-- 
1.8.0

On Sat, Dec 15, 2012 at 03:03:15PM +0000, John Keeping wrote:

Mail addresses in documentation are converted into mailto: hyperlinks in
the HTML output and footnotes in man pages.  This isn't desirable for
cases where the address is used as an example and is not valid.

Particularly annoying is the example "jane@laptop.(none)" which appears
in git-shortlog(1) as "jane@laptop[1].(none)", with note 1 saying:

	1. jane@laptop
	   mailto:jane@laptop

Thanks, this is definitely worth fixing.

Fix this by quoting example mail addresses with "$$", preventing
Asciidoc from processing them.

In the case of mailmap.txt, render the address monospaced so that it
matches the block examples surrounding that paragraph.

I think I'd just render them monospace everywhere. We are very
inconsistent about which form of quotes we use in the documentation (I
think because most of the developers read the source directly and not
the rendered asciidoc). And then we don't have to worry about the "$$"
construct (and IMHO it makes the source much more readable, and marking
the address as a literal looks good in the output, too).

-Peff

On Sat, Dec 15, 2012 at 12:20:18PM -0500, Jeff King wrote:

On Sat, Dec 15, 2012 at 03:03:15PM +0000, John Keeping wrote:

quoted

Mail addresses in documentation are converted into mailto: hyperlinks in
the HTML output and footnotes in man pages.  This isn't desirable for
cases where the address is used as an example and is not valid.

Particularly annoying is the example "jane@laptop.(none)" which appears
in git-shortlog(1) as "jane@laptop[1].(none)", with note 1 saying:

	1. jane@laptop
	   mailto:jane@laptop

Thanks, this is definitely worth fixing.

quoted

Fix this by quoting example mail addresses with "$$", preventing
Asciidoc from processing them.

In the case of mailmap.txt, render the address monospaced so that it
matches the block examples surrounding that paragraph.

I think I'd just render them monospace everywhere. We are very
inconsistent about which form of quotes we use in the documentation (I
think because most of the developers read the source directly and not
the rendered asciidoc). And then we don't have to worry about the "$$"
construct (and IMHO it makes the source much more readable, and marking
the address as a literal looks good in the output, too).

I agree that the source is more readable as monospaced, but I think we
need to keep the quotes around the text in git-tag(1) and probably
git-fast-import(1) so that it is differentiated from the surrounding
text in the man page output.

I just tried this and got strange results.  Taking the example in
git-tag(1):

    ...of the form ``Your Name [off-list ref]''

I tried this to preserve the quotes and make the entire quoted text
monospaced (I don't think we want to have just the email address
monospaced):

    ...of the form ```Your Name [off-list ref]`''

which had the desired effect - smart quotes and everything inside
rendered monospaced - BUT the email address is hyperlinked!

Switching the smart Asciidoc double quotes (``...'') for "normal" double
quotes ("...") produces the desired result, but IMHO doesn't look quite
as good (on the other hand it looks like there are many more use of
"..." than ``...'' in the Git documentation).

[While searching, the only other example I could find is in
git-commit(1) where `A U Thor [off-list ref]` is rendered
monospaced without quotes, but I think this hurts readability in the man
page output - expect a follow-up patch if we resolve this in the
direction of having quotes and monospaced text.]

At this point I've exhausted my Asciidoc knowledge and I'm not entirely
happy with any of these options.  Suggestions?

John

On Sat, Dec 15, 2012 at 06:24:09PM +0000, John Keeping wrote:

quoted

I think I'd just render them monospace everywhere. We are very
inconsistent about which form of quotes we use in the documentation (I
think because most of the developers read the source directly and not
the rendered asciidoc). And then we don't have to worry about the "$$"
construct (and IMHO it makes the source much more readable, and marking
the address as a literal looks good in the output, too).

I agree that the source is more readable as monospaced, but I think we
need to keep the quotes around the text in git-tag(1) and probably
git-fast-import(1) so that it is differentiated from the surrounding
text in the man page output.

Hmm, good point. I use MAN_BOLD_LITERAL, which serves that purpose, but
I guess not everyone does (and it is not the default; I wonder if it
should be).  But if MAN_BOLD_LITERAL is not in use, then `` literals
have zero typographical impact in the manpages.

So maybe we do need to do something else. I was just hoping we could get
away with something more readable in the source.

By my reading of the asciidoc user guide, the mechanism that is hurting
us is that mailto is an inline macro, and that foo@bar automatically
triggers that inline macro. Furthermore, the right way to suppress
expansion of macros is with a backslash escape. Doing this:

diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index d1844ea..68bca1a 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt

@@ -427,7 +427,7 @@ Here `<name>` is the person's display name (for example
 
 Here `<name>` is the person's display name (for example
 ``Com M Itter'') and `<email>` is the person's email address
-(``cm@example.com'').  `LT` and `GT` are the literal less-than (\x3c)
+(``\cm@example.com'').  `LT` and `GT` are the literal less-than (\x3c)
 and greater-than (\x3e) symbols.  These are required to delimit
 the email address from the other fields in the line.  Note that
 `<name>` and `<email>` are free-form and may contain any sequence

seems to produce the output we want. I think it's a little less ugly
than the "$$" quoting, but not by much. No clue if one is accepted by
more asciidoc versions or not.

-Peff

Email addresses in documentation are converted into mailto: hyperlinks
in the HTML output and footnotes in man pages.  This isn't desirable for
cases where the address is used as an example and is not valid.

Particularly annoying is the example "jane@laptop.(none)" which appears
in git-shortlog(1) as "jane@laptop[1].(none)", with note 1 saying:

	1. jane@laptop
	   mailto:jane@laptop

Fix this by escaping these email addresses with a leading backslash, to
prevent Asciidoc expanding them as inline macros.

In the case of mailmap.txt, render the address monospaced so that it
matches the block examples surrounding that paragraph.

Helped-by: Jeff King [off-list ref]
Signed-off-by: John Keeping <redacted>
---

On Sun, Dec 16, 2012 at 07:04:05AM -0500, Jeff King wrote:

Furthermore, the right way to suppress
expansion of macros is with a backslash escape.

[snipped an example]

I think it's a little less ugly
than the "$$" quoting, but not by much. No clue if one is accepted by
more asciidoc versions or not.

From a quick reading of the Asciidoc changelog, I think backslash

escaping should be supported just as well as "$$" quoting, which leaves
the minimal patch looking like this.

 Documentation/git-fast-import.txt | 2 +-
 Documentation/git-tag.txt         | 2 +-
 Documentation/mailmap.txt         | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index d1844ea..68bca1a 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt

@@ -427,7 +427,7 @@ they made it.
 
 Here `<name>` is the person's display name (for example
 ``Com M Itter'') and `<email>` is the person's email address
-(``cm@example.com'').  `LT` and `GT` are the literal less-than (\x3c)
+(``\cm@example.com'').  `LT` and `GT` are the literal less-than (\x3c)
 and greater-than (\x3e) symbols.  These are required to delimit
 the email address from the other fields in the line.  Note that
 `<name>` and `<email>` are free-form and may contain any sequence

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 247534e..2f1c0c3 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt

@@ -129,7 +129,7 @@ This option is only applicable when listing tags without annotation lines.
 CONFIGURATION
 -------------
 By default, 'git tag' in sign-with-default mode (-s) will use your
-committer identity (of the form "Your Name <your@email.address>") to
+committer identity (of the form "Your Name <\your@email.address>") to
 find a key.  If you want to use a different default key, you can specify
 it in the repository configuration as follows:
 

diff --git a/Documentation/mailmap.txt b/Documentation/mailmap.txt
index 288f04e..dd89fca 100644
--- a/Documentation/mailmap.txt
+++ b/Documentation/mailmap.txt

@@ -46,7 +46,7 @@ Jane Doe         <jane@desktop.(none)>
 Joe R. Developer <joe@example.com>
 ------------
 
-Note how there is no need for an entry for <jane@laptop.(none)>, because the
+Note how there is no need for an entry for `<jane@laptop.(none)>`, because the
 real name of that author is already correct.
 
 Example 2: Your repository contains commits from the following

-- 
1.8.0.2