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

[Junio C Hamano <gitster@pobox.com>]

John Keeping <john@keeping.me.uk> 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 <peff@peff.net>
> Signed-off-by: John Keeping <john@keeping.me.uk>
> ---
>
> 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.

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.