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

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

Jeff King <peff@peff.net> 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 `<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''

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