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

John Keeping [off-list ref] writes:

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:

quoted

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

[snipped an example]

quoted

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.

The patch looks reasonable to me, too.  We were bitten by relying on
the description in AsciiDoc documentation (which shows the state of
their latest software) before; between the constructs that work, it
is safer to use the older, more vanilla and more common one.

Thanks.