Re: [PATCH] docs: stop using asciidoc no-inline-literal

[Thomas Rast <trast@student.ethz.ch>]

Jeff King <peff@peff.net> 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)
>> -and greater-than (\x3e) symbols.  These are required to delimit
>> +`Com M Itter`) and `<email>` is the person's email address
>> +(`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
>>  of bytes, except `LT`, `GT` and `LF`.  `<name>` is typically UTF-8 encoded.
>> 
>> On my box (asciidoc 8.4.5) the preimage renders as
>> 
>>   `Com M Itter''
>
> Sorry, do you mean that it is screwed up only after my patch, or that in
> reviewing, you noticed that it is always screwed up?

The markup has always had this form, but I can't tell if it's just my
version of asciidoc that makes a mess of it, or a general problem.  [1]
has a correctly formatted copy so that would suggest a narrower problem.

> Yeah, I ran into some weird stuff, too. The gitweb.conf doc behaves
> oddly with `$projname`; I solved it by using "+" to use a teletype face
> without making it literal (since it doesn't actually have any asciidoc
> metacharacters).
>
> Even though I carefully reviewed the output before and after my patch,
> it makes me slightly concerned that somebody with a different asciidoc
> version will get different results. On the other hand, it's nice to
> clean up a mess, so I'm willing to try it and see if we get any bug
> reports.

Your change should _reduce_ the number of places it can break, since the
interpretation of `..` becomes _simpler_.  If it really turns out to
vary wildly afterwards, I'd suggest changing to some other markup
format.


[1] http://cs.swan.ac.uk/~csoliver/ok-sat-library/internet_html/doc/doc/Git/1.7.8.4/Documentation/git-fast-import.html

-- 
Thomas Rast
trast@{inf,student}.ethz.ch