[PATCH 3 of 3 STABLE V2] doc: add explanation about Mercurial specific escaping for subpaths

[Mads]

On 21/05/12 10:22, FUJIWARA Katsunori wrote:
> At Fri, 18 May 2012 15:20:35 -0500,
> Matt Mackall wrote:
>> On Wed, 2012-05-16 at 17:05 +0900, FUJIWARA Katsunori wrote:
>>> # HG changeset patch
>>> # User FUJIWARA Katsunori<foozy at lares.dti.ne.jp>
>>> # Date 1337155350 -32400
>>> # Branch stable
>>> # Node ID 7cd7ea68a04d5f28d664f6183a3e07011b1a89a0
>>> # Parent  c3eeae0a2e0ff4c0f493eb918f7458f2b12d93cb
>>> doc: add explanation about Mercurial specific escaping for subpaths
>>>
>>> diff -r c3eeae0a2e0f -r 7cd7ea68a04d mercurial/help/config.txt
>>> --- a/mercurial/help/config.txt	Wed May 16 17:02:30 2012 +0900
>>> +++ b/mercurial/help/config.txt	Wed May 16 17:02:30 2012 +0900
>>> @@ -1065,6 +1065,16 @@
>>>
>>>   rewrites ``http://server/foo-hg/`` into ``http://hg.server/foo/``.
>>>
>>> +.. note:: Even on Windows platforms, it is recommended to use ``/`` as
>>> +   the path delimiter for local paths instead of ``\``, because the latter is
>>> +   the special character for the regular expression.
>> Actually, the reason is that '/' is portable across all the supported
>> operating systems and '\' is not, and is thus our internal standard for
>> file naming.
>>
>>> +   For convenience, recent Mercurial escapes backslashes in
>>> +   ``replacement`` at first, and then treats backslashes followed by
>>> +   digits as back references of the regular expression. So, you can not
>>> +   specify "the path element starting with digits" with backslashes as
>>> +   path delimiters in ``replacement``.
>> Probably too much detail.
> Thank you for your comments.
>
> There is no documentation about Mercurial specific escaping for
> subpath configurations described in "For convenience, ...." paragraph
> above, so I think it should be explained at least for warning.
>
> What about this ?
>
>    .. note:: Even on Windows platforms, it is recommended to use ``/``
>       as the path delimiter for local paths instead of ``\``, because
>       the former is portable across all the supported operating systems
>       and the latter is not.

IMO it also matters that \ traditionally is used for other purposes - 
and that shows up for example in subpath replacements.

>       In addition to it, recent Mercurial escapes ``\`` in
>       ``replacement`` in the special way for backward
>       compatibility. This may cause unexpected behavior.

As we discussed in http://markmail.org/message/eelgmlqd7zks7nca this 
"special way" has fundamental problems. It uses the wrong kind of 
escaping and there is some replacements that it can't handle. The best 
way to fix that bug would be to remove the incorrect escape handling 
completely - even though that unfortunately not will be fully backward 
compatible.

Anyway, I don't think it is a good idea to add a "there is a bug here - 
we won't fix it and we can't describe how to work around it" section to 
the documentation.

/Mads