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

From: John Keeping <[email-masked]>
Date: Mon, 17 Dec 2012 09:44:46 +0000

On Sun, Dec 16, 2012 at 09:29:24PM -0800, Junio C Hamano wrote:
> John Keeping <[email-masked]> writes:
>>  Here `<name>` is the person's display name (for example
>>  ``Com M Itter'') and `<email>` is the person's email address
>> -([email-masked]'').  `LT` and `GT` are the literal less-than (\x3c)
>> +([email-masked]$$'').  `LT` and `GT` are the literal less-than (\x3c)
>>  and greater-than (\x3e) symbols.  These are required to delimit
>>  the email address from the other fields in the line.  Note that
>>  `<name>` and `<email>` are free-form and may contain any sequence
> 
> AsciiDoc 8.5.2 gives this:   
> 
>     asciidoc: WARNING: git-fast-import.txt: line 434: nested inline passthrough
> 
> Also in git-fast-import.1, there is this line:
> 
>     ... person\(cqs display name (for example `Com M Itter\(aq\(aq) and `<ema...
> 
> (notice two leftover `s); not that this is a new issue with this patch.
> 
> Which is puzzling, because the next input line formats better:
> 
>     ...  email address (\(lqcm@example\&.com\(rq)\&. ...

I wonder if you're hitting this bug, which is listed as fixed in
AsciiDoc 8.6.0 [1]:

    FIXED: Sometimes multiple double quoted text elements in the same
    paragraph were mistakenly seen as starting with an inline literal.

As you said in your other message, it may be better to avoid using the
pretty quotes, although I don't think just changing them to `monospace
output` is sufficient as monospace output is not distinguished in the
default man page output.  IMHO that's necessary for any examples that
contain whitespace.  Perhaps a patch series turning MAN_BOLD_LITERAL on
by default and then changing these examples to `monospace output`?

John

[1] http://www.methods.co.nz/asciidoc/CHANGELOG.html#_version_8_6_0_2010_08_16