Jeff King <peff@xxxxxxxx> 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@xxxxxxxxxxx''). `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@xxxxxxxxxxx`). `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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html