Hi,
Since I'm writing the new Model part for Entity References (document
and attachment for now but we can imagine objects and object
properties later on). I'd like to propose 2 things:
* A syntax for escaping special characters in references
* Some changes to the supported reference syntax
Escapes
=======
I'd like to propose using the backslash (i.e. \ ) character.
For example: "a page name with \: some \. special \@ characters"
Rationale:
* it's a well known char for escapes, all devs know about it
* using "~" would be confusing with the wiki syntax
Known issue:
* when in the velocity macro you need to be careful to use a double
escape since \ is the velocity char for escaping. Ex:
{{velocity}}
[[label>>specia...@page-name]]
{{/velocity}}
Breakages
=========
Since we'll know have a generic factory/serializer for all entity
types we need to make the syntax more consistent. This means that the
following syntax will not work anymore:
* ex: "wiki:page". This would be interpreted as a document with a page
of "page" and a space of "wiki:"
* When using the "default" factory, only default values would be used
(right now it's a mix between current doc values and default values).
Suggested defaults: "xwiki" for Wiki, "XWiki" for space, "WebHome" for
page and "" for attachment name. Note that one idea is to make these
defaults configurable in the xwiki config file
* It's hard to know for sure but we certainly have various other
inconsistencies that exist now when using special reserved chars in
references
We have 2 options here:
* Make XE 2.2 not backward compatible for some references. Advertise
it in the release notes and explain to users how they should change
their names if they use "exotic" names
* Create an automatic converter, for example as a database migrator
that would read all documents in the wiki, call getLinks() on each
document, send the links to the old parser (would need to extract it
somewhere and ensure it behaves as now) and send the link to the new
parser and compare. If there's a difference, escape the char and save.
This would also need to be done for document parent references, the
backlink table and all object properties that allow wiki syntax or
velocity. Note that it wouldn't fix any generated name (using velocity
for ex).
The automatic converter option is really hard to do so I'm leaning
more towards the first solution. That would need to be properly
handled since it could potentially cause quite a few broken links.
WDYT?
Thanks
-Vincent
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
