20 Sep
2010
20 Sep
'10
10:40 a.m.
On Sep 17, 2010, at 1:46 PM, Denis Gervalle wrote:
Hi Vincent,
On Fri, Sep 17, 2010 at 08:12, Vincent Massol <vincent(a)massol.net> wrote:
You're oversimplifying a lot. First you haven't differentiated references from
links. They're 2 different concepts and exist independently of one another. Then
you're mixing 2.0 syntax and 2.1 syntax which are different (the @ sign is an example
of difference between both).
Hi,
I thought it would be good to summarize the rules I'm implementing/fixing
relative to escaping in link references for both XWiki Syntax 2.0 and the
new XWiki Syntax 2.1 I have started. This will later go in the XWiki Syntax
page on xwiki.org.
There are 2 set of rules:
- For entity references
- For link references
Entity References
==============
The rules are (independent of the XWiki Syntax):
- if you need a \ in any part of the reference then you need to double it
with \\
- For a : in a space name it's \:
- For a . in a page name it's \.
- For a @ in an attachment name it's \@
- For a ^ in an object name it's \^
- For a . in an object property name it's \.
Link References
=============
For XWiki Syntax 2.0
----------------------------
The rules are:
- if the link reference points to a document and you want a ?, #, @ or \ in
any part of the reference you need to escape them with \?, \#, \@ or \\.
Note that when resolving a link reference to a document the link reference
escapes are first unescaped and then the entity reference is unescaped. For
ex for: [[label>>my\.page]] will result in a link to a page named
"my.page"
and [[label>>my\?page]] to "my?page".
- if link reference points to a mailto then no escaping is performed at
all. Thus [[label>>mailto:john\@whatever.org]] will generate in HTML <a
href="mailto:john\@whatever.org">john\@whatever.org</a>
- same for link refs to URLs
- For link to attachments, only the entity reference escape is performed,
no additional escape is done for the link reference.
- For link to interwiki, if the interwiki path needs a @ then it must be
escaped with \@. Same for the interwiki alias. Example:
[[label>>what\@ever@wiki\@pedia]]
For XWiki Syntax 2.1
----------------------------
The rules are:
- if the link reference points to a document and you want a ?, # or \ in
any part of the reference you need to escape them with \?, \#, or \\.
- if link reference points to a mailto then no escaping is performed at
all.
- same for link refs to URLs
- For link to attachments, only the entity reference escape is performed,
no additional escape is done for the link reference.
- For link to interwiki, no escaping is performed at all (and ":" is not
allowed in the interwiki alias). Example:
[[label>>interwiki:wikipedia:what\\ever]] will generate an interwiki path of
what\\ever
Open Questions
=============
Do we want to allow \\ in any link references (mailto, attach, interwiki,
url, etc) and unescape it to \ or should we keep the rules defined above?
Well, it is really too complex, I cannot imagine that I should explain that
to an end-user. My feeling is that we need to be able to write a simplified
rule like this:
"In link reference, \ (backslash), : (colon), . (dot), @ (atsign) and ^
(circumflex) may have a special meaning, and may need to be escaped by
preceding them with backslash when used literally. In doubt, you may always
escape the special characters in link reference if you need them
litterally." Obviously, the implementation could be a clever mix of
the your initial
rules and support "over" escaping.
I would really like to see that as the rules for 2.1 syntax unless there is
strong reasons not to do so that I am not aware of.
WDYT ?
I'm not sure. I agree for references to documents but I don't think we should do
any escaping for the other types.
Thanks
-Vincent