[xwiki-devs] [Proposal][Model] String representation for Entity References: Escapes + breakages
23 Dec
2009
23 Dec
'09
3:42 p.m.
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>>special\\@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
23 Dec
23 Dec
3:46 p.m.
On Dec 23, 2009, at 3:42 PM, Vincent Massol wrote:
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>>special\\@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:"
Correction: This would be interpreted as a document with a page of
"wiki:page"
-Vincent
* 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
4:12 p.m.
On Wed, Dec 23, 2009 at 15:42, Vincent Massol <vincent(a)massol.net> wrote:
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
+1000 (at last :))
* 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>>special\\@page-name]]
{{/velocity}}
+1 for \
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:"
+1
* 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
+1
* It's hard to know for sure but we certainly have
various other
inconsistencies that exist now when using special reserved chars in
references
* the escaping itself which become a new special char in references names
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.
Backlinks are very difficult in xwiki/1.0, I would would say lets
migrate backlink for xwiki/2.0 syntax and parents.
WDYT?
Thanks
-Vincent
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Thomas Mortagne
4:13 p.m.
On Wed, Dec 23, 2009 at 16:12, Thomas Mortagne
<thomas.mortagne(a)xwiki.com> wrote:
--
Thomas Mortagne
On Wed, Dec 23, 2009 at 15:42, Vincent Massol
<vincent(a)massol.net> wrote:
I commented the wrong mail, obviously it's +1 for page="wiki:page"
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
+1000 (at last :))
* 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>>special\\@page-name]]
{{/velocity}}
+1 for \
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:"
+1 * 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
+1
* It's hard to know for sure but we certainly
have various other
inconsistencies that exist now when using special reserved chars in
references
* the escaping itself which become a new special char in references names
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.
Backlinks are very difficult in xwiki/1.0, I would would say lets
migrate backlink for xwiki/2.0 syntax and parents.
WDYT?
Thanks
-Vincent
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Thomas Mortagne
24 Dec
24 Dec
10:43 a.m.
To be even more precise, with the algorithm I currently have the
following rules apply:
* An attachment name cannot contain a "@" (it has to be escaped)
* A page name cannot contain a "." (it has to be escaped)
* A space name cannot contain a ":" (it has to be escaped)
The general rule is that a given entity reference name cannot contain
the separator for separating from its parent entity reference (it has
to be escaped).
These are pretty simple rules IMO (and this is one reason why you
cannot "skip" an entity reference separator as in "wiki:page").
Thanks
-Vincent
On Dec 23, 2009, at 3:42 PM, Vincent Massol wrote:
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>>special\\@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
10:47 a.m.
What about the \ character? Shouldn't be escaped also?
On Thu, Dec 24, 2009 at 11:43 AM, Vincent Massol <vincent(a)massol.net> wrote:
To be even more precise, with the algorithm I
currently have the
following rules apply:
* An attachment name cannot contain a "@" (it has to be escaped)
* A page name cannot contain a "." (it has to be escaped)
* A space name cannot contain a ":" (it has to be escaped)
The general rule is that a given entity reference name cannot contain
the separator for separating from its parent entity reference (it has
to be escaped).
These are pretty simple rules IMO (and this is one reason why you
cannot "skip" an entity reference separator as in "wiki:page").
Thanks
-Vincent
On Dec 23, 2009, at 3:42 PM, Vincent Massol wrote:
--
Cu stima,
Flavius Olaru
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>>special\\@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
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
10:53 a.m.
On Dec 24, 2009, at 10:47 AM, Flavius Olaru wrote:
What about the \ character? Shouldn't be escaped
also?
Yes I forgot that rule. You can have \ in any reference name by
escaping it too: \\
Thanks
-Vincent
On Thu, Dec 24, 2009 at 11:43 AM, Vincent Massol
<vincent(a)massol.net> wrote:
To be even more precise, with the algorithm I
currently have the
following rules apply:
* An attachment name cannot contain a "@" (it has to be escaped)
* A page name cannot contain a "." (it has to be escaped)
* A space name cannot contain a ":" (it has to be escaped)
The general rule is that a given entity reference name cannot contain
the separator for separating from its parent entity reference (it has
to be escaped).
These are pretty simple rules IMO (and this is one reason why you
cannot "skip" an entity reference separator as in "wiki:page").
Thanks
-Vincent
On Dec 23, 2009, at 3:42 PM, Vincent Massol wrote:
--
Cu stima,
Flavius Olaru
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs 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>>special\\@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
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
5:15 p.m.
On Dec 24, 2009, at 10:53 AM, Vincent Massol wrote:
On Dec 24, 2009, at 10:47 AM, Flavius Olaru wrote:
What about the \ character? Shouldn't be
escaped also?
Yes I forgot that rule. You can have \ in any reference name by
escaping it too: \\
Thanks
-Vincent
On Thu, Dec 24, 2009 at 11:43 AM, Vincent Massol
<vincent(a)massol.net> wrote:
To be even more precise, with the algorithm I
currently have the
following rules apply:
* An attachment name cannot contain a "@" (it has to be escaped)
* A page name cannot contain a "." (it has to be escaped)
* A space name cannot contain a ":" (it has to be escaped)
The general rule is that a given entity reference name cannot
contain
the separator for separating from its parent entity reference (it
has
to be escaped).
These are pretty simple rules IMO (and this is one reason why you
cannot "skip" an entity reference separator as in "wiki:page").
Thanks
-Vincent
On Dec 23, 2009, at 3:42 PM, Vincent Massol wrote:
--
Cu stima,
Flavius Olaru
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs 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>>special\\@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
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
5:16 p.m.
On Dec 24, 2009, at 10:43 AM, Vincent Massol wrote:
To be even more precise, with the algorithm I
currently have the
following rules apply:
* An attachment name cannot contain a "@" (it has to be escaped)
* A page name cannot contain a "." (it has to be escaped)
* A space name cannot contain a ":" (it has to be escaped)
Note that when we implement nested spaces a space will not be able to
contain "." either.
Thanks
-Vincent
The general rule is that a given entity reference name cannot
contain the separator for separating from its parent entity
reference (it has to be escaped).
These are pretty simple rules IMO (and this is one reason why you
cannot "skip" an entity reference separator as in "wiki:page").
Thanks
-Vincent
On Dec 23, 2009, at 3:42 PM, Vincent Massol wrote:
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>>special\\@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
25 Dec
25 Dec
12:33 p.m.
On Dec 24, 2009, at 5:16 PM, Vincent Massol wrote:
On Dec 24, 2009, at 10:43 AM, Vincent Massol wrote:
Actually we need to not allow "." in space names right now, otherwise
it'll be too hard to move to it later on.
Thanks
-Vincent
To be even more precise, with the algorithm I
currently have the
following rules apply:
* An attachment name cannot contain a "@" (it has to be escaped)
* A page name cannot contain a "." (it has to be escaped)
* A space name cannot contain a ":" (it has to be escaped)
Note that when we implement nested spaces a space will not be able
to contain "." either.
Thanks
-Vincent
The general rule is that a given entity reference name cannot
contain the separator for separating from its parent entity
reference (it has to be escaped).
These are pretty simple rules IMO (and this is one reason why you
cannot "skip" an entity reference separator as in "wiki:page").
Thanks
-Vincent
On Dec 23, 2009, at 3:42 PM, Vincent Massol wrote:
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>>special\\@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
12:42 p.m.
On Dec 25, 2009, at 12:33 PM, Vincent Massol wrote:
On Dec 24, 2009, at 5:16 PM, Vincent Massol wrote:
hmmm.... not much we can do if we don't have nested spaces actually.
The only thing I can think of is to escape the "." char when
serializing.
-Vincent
On Dec 24, 2009, at 10:43 AM, Vincent Massol wrote:
Actually we need to not allow "." in space names right now,
otherwise it'll be too hard to move to it later on. To be even more precise, with the algorithm I
currently have the
following rules apply:
* An attachment name cannot contain a "@" (it has to be escaped)
* A page name cannot contain a "." (it has to be escaped)
* A space name cannot contain a ":" (it has to be escaped)
Note that when we implement nested spaces a space will not be able
to contain "." either. Thanks
-Vincent
Thanks
-Vincent
The general rule is that a given entity reference name cannot
contain the separator for separating from its parent entity
reference (it has to be escaped).
These are pretty simple rules IMO (and this is one reason why you
cannot "skip" an entity reference separator as in "wiki:page").
Thanks
-Vincent
On Dec 23, 2009, at 3:42 PM, Vincent Massol wrote:
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>>special\\@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
8 p.m.
On Fri, Dec 25, 2009 at 12:42, Vincent Massol <vincent(a)massol.net> wrote:
On Dec 25, 2009, at 12:33 PM, Vincent Massol wrote:
Yes, don't see anything else either but at least that's the most important part.
On Dec 24, 2009, at 5:16 PM, Vincent Massol wrote:
hmmm.... not much we can do if we don't have nested spaces actually.
The only thing I can think of is to escape the "." char when
serializing.
On Dec 24, 2009, at 10:43 AM, Vincent Massol wrote:
Actually we need to not allow "." in space names right now,
otherwise it'll be too hard to move to it later on. To be even more precise, with the algorithm I
currently have the
following rules apply:
* An attachment name cannot contain a "@" (it has to be escaped)
* A page name cannot contain a "." (it has to be escaped)
* A space name cannot contain a ":" (it has to be escaped)
Note that when we implement nested spaces a space will not be able
to contain "." either.
-Vincent
--
Thomas Mortagne
Thanks
-Vincent
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
Thanks
-Vincent
The general rule is that a given entity reference name cannot
contain the separator for separating from its parent entity
reference (it has to be escaped).
These are pretty simple rules IMO (and this is one reason why you
cannot "skip" an entity reference separator as in "wiki:page").
Thanks
-Vincent
On Dec 23, 2009, at 3:42 PM, Vincent Massol wrote:
> 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>>special\\@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
>
5379
days inactive
5381
days old
11 comments
3 participants
participants (3)
-
Flavius Olaru -
Thomas Mortagne -
Vincent Massol