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

From: John Keeping <john@keeping.me.uk>
Date: Dec 17, 2012, 09:44 UTC
Message-ID: <20121217094446.GA24036@river.lan>
In-Reply-To: <7vobhtnt57.fsf@alter.siamese.dyndns.org>

On Sun, Dec 16, 2012 at 09:29:24PM -0800, Junio C Hamano wrote:

Show 22 quoted lines

> John Keeping <john@keeping.me.uk> writes:
>>  Here `<name>` is the person's display name (for example
>>  ``Com M Itter'') and `<email>` is the person's email address
>> -(``cm@example.com'').  `LT` and `GT` are the literal less-than (\x3c)
>> +(``$$cm@example.com$$'').  `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