On Mon, Sep 20, 2010 at 10:49, Vincent Massol <[email protected]> wrote:
> > 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:[email protected]]] will generate in HTML <a > href="mailto:[email protected]";>[email protected]</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>>wh...@ever@wi...@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 :) > I was just talking about 2.1, and I would agree on anything that should be explained (vs implemented) simply. My main point was that escaping where no escaping is strictly required should be supported and simplify what should be explained. >From what I read of the current 2.0 rules, if you do not understand them fully, you may cause harm by over escaping something, and since knowing what require escaping or not is not simple, this will happen for sure. I have also completely understand the difference you make between document and link reference, but I am not sure the end user will get the difference. We really need to think it as simple as possible or there will be confusion and frustration. Denis > > 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 > > > > > > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs > -- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
