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 :) 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
