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

Jeff King [off-list ref] writes:

quoted

 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