From: Stuart Rackham <srackham@methods.co.nz>
Date: Tue, 03 Oct 2006 22:38:35 GMT
Subject: Re: pull-fetch-param.txt
Message-ID: <4522E66B.4080103@methods.co.nz>
In-Reply-To: <7v64f1np8i.fsf@assigned-by-dhcp.cox.net>

 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 Rackham


Junio C Hamano wrote:
> Stefan Richter <stefanr@s5r6.in-berlin.de> writes:
> 
>> Junio C Hamano wrote:
>>> It's a bit sad that asciidoc's nicer quoting features
>>> are not backward compatible.
>> Yes, this is awkward. Here comes the next candidate for quoting.
> 
> [Stuart Rackham CC'ed]
> 
> At this point I have to say
> 
> 	What the h*ck AsciiDoc people are thinking?
> 
> Heck, I thought we were one of the more important customers of
> asciidoc project and not breaking us meant at least something to
> them; our name is at the top of "Project using AsciiDoc" section
> of their website, http:/www.methods.co.nz/asciidoc/.  Apparently
> I was delusional.
> 
> Introducing nicer new features is a good thing, but you do not
> break existing documents without a good reason and an escape
> hatch.
> 
> Put it more mildly, I think we need to find out what their
> policy on backward compatibility is, and if it is "screw it --
> you should re-mark-up your documents to match the newer rule
> every time we have a new release.  By the way, you always have
> the option to stay at older releases of ours", then we should
> seriously consider switching the documentation format to
> something else.  I honestly hope it does not have to come to
> that.
> 
>> In pull-fetch-param.txt:
>>
>> ----8<----
>> <refspec>::
>> 	The canonical format of a <refspec> parameter is
>> 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
>> 	by the source ref, followed by a colon `:`, followed by
>> 	the destination ref.
>> +
>> The remote ref that matches <src>
>> is fetched, and if <dst> is not empty string, the local
>> ref that matches it is fast forwarded using <src>.
>> Again, if the optional plus `+` is used, the local ref
>> ---->8----
>>
>> "man git-fetch" and "man git-pull" show:
>> ----8<----
>>        <refspec>
>>               The  canonical  format of a <refspec> parameter is ?<src>:<dst>;
>>               that is, an optional plus, followed by the source ref,  followed
>>               by a colon :, followed by the destination ref.
>>
>>               The  remote  ref  that matches <src> is fetched, and if <dst> is
>>               not empty string, the local ref that matches  it  is  fast  for-
>>               warded  using  <src>. Again, if the optional plus + is used, the
>> ---->8----
>>
>> I.e. the first and second + were swallowed, but not the third one.
>> This is the fix for asciidoc 8.0.0:
>> 	`$$+$$?<src>:<dst>`; that is, an optional plus `+`, followed
> 
> Without looking at asciidoc 8.0 source, my guess is that it
> treats _anything_ that has two pluses on the same input line as
> quoted by some magical '+'-pair quote.   Can you try
> reformatting the original
> 
>> <refspec>::
>> 	The canonical format of a <refspec> parameter is
>> 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
>> 	by the source ref, followed by a colon `:`, followed by
>> 	the destination ref.
> 
> to something like
> 
>> <refspec>::
>> 	The canonical format of a <refspec> parameter is
>> 	`+?<src>:<dst>`; that is, an optional plus
>> 	`+`, followed
>> 	by the source ref, followed by a colon `:`, followed by
>> 	the destination ref.
> 
> and verify that conjecture?
> 
> We already had to deal with this with your patch for tilde.
> Arguably tilde and caret are rare enough in plain text so we can
> live with having to spell it as {caret} and {tilde}, but if my
> guess is correct, that means we have to spell plus '+' as {plus}
> with an appropriate entry in asciidoc.conf (or "\+" if it works
> in both older and newer versions).  As more ordinary characters
> are taken for special mark-up purposes, we would need to keep
> adding them to our list.  Where does the madness end?
> 
> Fortunately AsciiDoc 8.0 is still young.  Maybe they can find a
> fix for this in a way that does not break documents written for
> (at least recent versions of) AsciiDoc 7; it might have to break
> documents written for early betas and the initial release of
> 8.0, but that is _much_ better than breaking existing documents,
> in my extremely biased opinion as a very unhappy user.
>