From: Thomas Rast Date: Thu, 26 Apr 2012 09:42:41 GMT Subject: Re: [PATCH] docs: stop using asciidoc no-inline-literal Message-ID: <87d36uomlq.fsf@thomas.inf.ethz.ch> In-Reply-To: <20120426085156.GB22819@sigill.intra.peff.net> Jeff King writes: > On Thu, Apr 26, 2012 at 02:19:23AM -0400, Jeff King wrote: > >> I'd like to eventually stop building the documentation with >> no-inline-literal. It was an asciidoc7 compatibility thing, but we can >> probably drop that now. However, I suspect that would require us to >> simultaneously convert all of the `{tilde}` uses back into `~`. > > I took a look at this. There were about 200 sites that needed to be > fixed up. It was a pain, but it's now done. The resulting source is much > nicer, and as a bonus, it revealed (and fixed!) a ton of existing > formatting bugs. Great! > In asciidoc 7, backticks like `foo` produced a typographic > effect, but did not otherwise affect the syntax. In asciidoc > 8, backticks introduce an "inline literal" inside which markup > is not interpreted. To keep compatibility with existing > documents, asciidoc 8 has a "no-inline-literal" attribute to > keep the old behavior. We enabled this so that the > documentation could be built on either version. The switch was actually at asciidoc 8.4.1, as explained in 71c020c (Disable asciidoc 8.4.1+ semantics for `{plus}` and friends, 2009-07-25). > ifndef ASCIIDOC7 > -ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal > +ASCIIDOC_EXTRA += -a asciidoc7compatible > endif That of course raises the question what asciidoc7compatible means. I have no idea, and google hasn't exactly been helpful. The only thing I could find was http://www.methods.co.nz/asciidoc/chunked/apa.html It mostly seems to affect quoting rules. Do we really need it? As for the actual patch, I only did some "lazy verification" using git grep '`[^`]*[\\{]' Documentation/ That (unsurprisingly :-) turned up no mistakes on your part. However, some markup mistakes show up in git-fast-import.txt: diff --git i/Documentation/git-fast-import.txt w/Documentation/git-fast-import.txt index 2620d28..3e8fbd1 100644 --- i/Documentation/git-fast-import.txt +++ w/Documentation/git-fast-import.txt @@ -422,9 +422,9 @@ The `committer` command indicates who made this commit, and when they made it. 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'' in fixed-width font. In the process of debugging this, I noticed that the quoting rules are hilariously screwy. It seems that within a paragraph, saying ``foo'' means `bar` ^^^^^^^^^^^^^ treats the underlined part as a `-quoted chunk of text, and renders it appropriately using a fixed-width font. The trailing ` has no effect unless it is followed by another ` within the same paragraph. But the ` right at the start of the "quoted" text has no effect either! Moreover, this behaviour is the same regardless of the 'asciidoc7compatible' setting. I wonder if it has since been fixed, but the above might be a good idea anyway. (The quoting around \xAB is just for good measure.) -- Thomas Rast trast@{inf,student}.ethz.ch