git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Jeff King <peff@peff.net>
Date
Dec 15, 2012, 17:20 UTC
Message-ID
<20121215172018.GA18696@sigill.intra.peff.net>
In-Reply-To
<20121215150314.GC2725@river.lan>
On Sat, Dec 15, 2012 at 03:03:15PM +0000, John Keeping wrote:
Show 9 quoted lines
> 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.
Show 5 quoted lines
> 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
Previous: John KeepingNext: Junio C Hamano
Message 2 of 12 in “Documentation: don't link to example mail addresses”
  1. Documentation: don't link to example mail addressesJohn Keeping, Dec 15, 2012
  2. Jeff KingDec 15, 2012
  3. Junio C HamanoDec 15, 2012
  4. John KeepingDec 15, 2012
  5. Jeff KingDec 16, 2012
  6. Documentation: don't link to example mail addressesJohn Keeping, Dec 16, 2012
  7. Junio C HamanoDec 16, 2012
  8. Junio C HamanoDec 17, 2012
  9. Jeff KingDec 17, 2012
  10. Junio C HamanoDec 17, 2012
  11. Junio C HamanoDec 17, 2012
  12. John KeepingDec 17, 2012

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.