From: Thomas Rast Date: Thu, 26 Apr 2012 13:09:51 GMT Subject: Re: [PATCH] docs: stop using asciidoc no-inline-literal Message-ID: <87obqe8wrk.fsf@thomas.inf.ethz.ch> In-Reply-To: <20120426125014.GB25067@sigill.intra.peff.net> Jeff King writes: >> Here `` is the person's display name (for example >> -``Com M Itter'') and `` 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 `` 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 >> `` and `` are free-form and may contain any sequence >> of bytes, except `LT`, `GT` and `LF`. `` 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