On Sep 17, 2010, at 8:12 AM, Vincent Massol wrote:
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
I had forgotten one proposal we have in jira which is to remove the ? and # symbols altogether by using something like this: [[label>>doc:whatever||queryString=... anchor=...]] If we do this then we don't need any escaping at all in link references (only the entity reference escapings will still be needed). This looks the simplest to me. BTW, for Denis/Fabio don't forget that we're *NOT* allowed to change anything for the XWiki Syntax 2.0 which is already set in stone. We can only make changes for 2.1 :) Thanks -Vincent
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?
Thanks -Vincent