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

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

From
Junio C Hamano <gitster@pobox.com>
Date
Dec 17, 2012, 19:57 UTC
Message-ID
<7vr4moladu.fsf@alter.siamese.dyndns.org>
In-Reply-To
<20121217120253.GA21858@sigill.intra.peff.net>
Jeff King <peff@peff.net> writes:
Show 20 quoted lines
> On Sun, Dec 16, 2012 at 06:24:58PM -0800, Junio C Hamano wrote:
>
>> I seem to be getting
>> 
>> (<tt>`\cm@example.com'').  `LT</tt> and <tt>GT</tt> are the literal less-than (\x3c)
>> 
>> out of this part in the resulting HTML output, which is probably not
>> what you wanted to see.
>> 
>> I have a feeling that it might be a better solution to stop using
>> these pretty quotes.  It's not like we use them a lot and a quick
>> scanning of "git grep '``'" output seems to tell me that many of
>> them should be `monospace output`, and the rest (mostly references
>> to section headers) can be "Section".
>
> Typographically speaking, I would also be just as happy to use regular
> double-quotes throughout.  But here's an example where they also caused
> a problem (which was fixed by moving to smart-quotes in f34e9ed):
>
>   http://thread.gmane.org/gmane.comp.version-control.git/163067
I agree with the typography argument.

Many monospaced fonts used in the windows where the programmers view the source of the docmentation, a 'normal' single quote does not slant by the same amount to the `opposite` quote, so ``a pair does not balance'' visually in the source. And the whole point of writing documentation in AsciiDoc is to keep the source readable. The use of pretty quote throws discards that primary benefit of choosing AsciiDoc in the first place.

Previous: Jeff KingNext: Junio C Hamano
Message 10 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.