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

[Jeff King <peff@peff.net>]

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