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

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

Jeff King <peff@peff.net> writes:

> 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.