Subject: Re: asciidoc 7--8 compatibility (was Re: pull-fetch-param.txt)

From: Stuart Rackham <[email-masked]>
Date: Thu, 05 Oct 2006 10:06:53 +1300

Hi Stefan

Stefan Richter wrote:
> Stuart Rackham wrote:
>> From the AsciiDoc User Guide
>> (http://www.methods.co.nz/asciidoc/userguide.html#X53):
>>
>> If you want to disable unconstrained quotes, the new alternative
>> constrained quotes syntax and the new index entry syntax then you can
>> define the attribute asciidoc7compatible (for example by using the -a
>> asciidoc7compatible command-line option).
> 
> Stuart,
> 
> the actual issues were:
> 
> 1.) Input which works with asciidoc 7 fails to build with asciidoc 8
> (after the intermediary XML step). This pair of tildes broke (but other
> occurences of tilde did not):
> 
> | * A suffix '~<n>' to a revision parameter means the commit
> |   object that is the <n>th generation grand-parent of the named
> |   commit object, following only the first parent.  I.e. rev~3 is

I've conditionally redefined subscript (tilde) and superscripting so 
they use the old replacements mechanism when asciidoc7compatible is 
defined rather than the asciidoc 8 default unconstrained quoting (patch 
for affected files attached).

> 
> 2.) Asciidoc 8 silently swallows characters from input which works with
> asciidoc 7. The two pluses in the following line vanished (but instances
> of single pluses per input line did not vanish):
> 
> | 	`+?<src>:<dst>`; that is, an optional plus `+`, followed

Fixed by asciidoc7compatible.

> 
> I wonder:
> 
>  - Are tilde and plus new special characters in asciidoc 8, or were they
> already special characters in asciidoc 7?
>        [ A pair of single pluses encloses monospaced text in asciidoc 8.
>          A pair of single tildes encloses subscripts. ]
> 
>  - If they were already special characters in asciidoc 7, what is the
> canonical way to escape them in asciidoc 7, 8, and hopefully 9?
>        [ If they weren't special characters in asciidoc 7, then we need
>          to use the asciidoc7compatible attribute. ]
> 
>  - Does asciidoc 7 accept the asciidoc7compatible attribute?

No.

> 
> Thanks.
> 
> 
> PS:
> 
> Junio, Stuart, here is another inconsistency between asciidoc 7 and 8.
> Please have a look at
> http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html .
> See the ASCII art above "SPECIFYING RANGES". The input
>        \  |  / \
>         \ | /   |
> produced
>    \  |  /         \ | /   |
> I.e. backslash-newline was interpreted by asciidoc 7 (or whatever you
> use to generate what is put online) as an escaped thus swallowed
> newline. But the output that I got here from asciidoc 8 (manpage as well
> as the html file) still has backslash and newline printed out.

Cheers, Stuart
Index: asciidoc.conf
===================================================================
--- asciidoc.conf	(revision 53)
+++ asciidoc.conf	(working copy)
@@ -62,9 +62,9 @@
 __=#emphasis
 ++=#monospaced
 \##=#unquoted
-endif::asciidoc7compatible[]
 ^=#superscript
 ~=#subscript
+endif::asciidoc7compatible[]
 
 [specialwords]
 emphasizedwords=
Index: xhtml11.conf
===================================================================
--- xhtml11.conf	(revision 53)
+++ xhtml11.conf	(working copy)
@@ -22,6 +22,12 @@
 \$=\$
 `=\`
 endif::asciimath[]
+ifdef::asciidoc7compatible[]
+# Superscripts.
+\^(.+?)\^=<sup>\1</sup>
+# Subscripts.
+~(.+?)~=<sub>\1</sub>
+endif::asciidoc7compatible[]
 
 [ruler-blockmacro]
 <hr />
Index: docbook.conf
===================================================================
--- docbook.conf	(revision 53)
+++ docbook.conf	(working copy)
@@ -18,6 +18,12 @@
 [replacements]
 # Line break markup is dropped (there is no DocBook line break tag).
 (?m)^(.*)\s\+$=\1
+ifdef::asciidoc7compatible[]
+# Superscripts.
+\^(.+?)\^=<superscript>\1</superscript>
+# Subscripts.
+~(.+?)~=<subscript>\1</subscript>
+endif::asciidoc7compatible[]
 
 [ruler-blockmacro]
 # Only applies to HTML so don't output anything.
Index: html4.conf
===================================================================
--- html4.conf	(revision 53)
+++ html4.conf	(working copy)
@@ -18,6 +18,12 @@
 [replacements]
 # Line break.
 (?m)^(.*)\s\+$=\1<br />
+ifdef::asciidoc7compatible[]
+# Superscripts.
+\^(.+?)\^=<sup>\1</sup>
+# Subscripts.
+~(.+?)~=<sub>\1</sub>
+endif::asciidoc7compatible[]
 
 [ruler-blockmacro]
 <hr />