vincent@massol.net
2014-10-17 15:36:32 UTC
I’ve read again both threads. Not an easy decision...
Some thoughts:
* I don't like any of the proposed solutions so far because they all make it harder to create links than what user already do in XWiki Syntax 2.0 or 2.1
* Solution 2 (forcing using the "doc" prefix when creating links to subwikis) is the solution that gathered the most votes. However when I think about solution 2 I think about xwiki.org and all the links I create every week from one wiki to another and I can't refrain from thinking that it's going to make more complex to create them.
* I can understand why some didn't like my proposal to have a shortcut syntax for links and a canonical one for typed references. Basically it's too complex for users.
In order to be complete, there's another possibility which is to change the delimiter for wikis or for reference types. Obviously it wouldn't be possible to change the delimiter for wikis (i.e. the ":" in "wiki:space.page") so remains the option to change the delimiter for reference types.
Here are some ideas for exploring this direction:
Solution 10
===========
* [[label>>wiki:space.page]]
* [[label>>doc::wiki:space.page]]
* [[label>>path::/some/path]]
* [[label>>http://xwiki.org]]
* [[label>>url::http://xwiki.org]]
* [[label>>user::evalica]]
* [[image:wiki:***@image.png]]
* [[image:doc::wiki:***@image.png]]
* [[image:icon::someicon.png]]
PROs:
* Syntax remains the shorter possible for links to docs and URLs
* Adding a new reference type doesn't break existing links/images
CONs:
* When using typed links/images, it's bit longer to type ("::" instead of ":")
* Small change of syntax for users but the majority of users use the shorthand notation
* Still a URI! (even if a weird one)
* Force to escape the ":" (with "~:") for spaces or documents starting with ":"
Solution 11
===========
Using URL-like notation:
* [[label>>wiki:space.page]]
* [[label>>doc://wiki:space.page]]
* [[label>>path:///some/path]]
* [[label>>http://xwiki.org]]
* [[label>>https://xwiki.org]]
* [[label>>url://http://xwiki.org]]
* [[label>>user://evalica]]
* [[image:wiki:***@image.png]]
* [[image:doc://wiki:***@image.png]]
* [[image:icon://someicon.png]]
Compared to solution 10:
PROs:
* Uses a notation closer to a URL (could be a CONs too!)
CONs:
* One more character to type "://" vs "::"
* A bit strange when linking to URLs using the typed syntax ("url://http://xwiki.org")
* Need to use the typed syntax for URLs other than "http" and "https" (e.g. for specific URL schemes, like "ftp": "url://ftp://192.168.0.1")
Solution 12
===========
Then there are other possible notations such as:
* [[label>>wiki:space.page]]
* [[label>>doc#wiki:space.page]]
* [[label>>path#/some/path]]
* [[label>>http://xwiki.org]]
* [[label>>url#http://xwiki.org]]
* [[label>>user#evalica]]
* [[image:wiki:***@image.png]]
* [[image:doc#wiki:***@image.png]]
* [[image:icon#someicon.png]]
Solution 13
===========
Or:
* [[label>>wiki:space.page]]
* [[label>>doc=wiki:space.page]]
* [[label>>path=/some/path]]
* [[label>>http://xwiki.org]]
* [[label>>url=http://xwiki.org]]
* [[label>>user=evalica]]
* [[image:wiki:***@image.png]]
* [[image:doc=wiki:***@image.png]]
* [[image:icon=someicon.png]]
Personally I'm still hesitating but seen that the majority of use cases are for links to documents, I think I'd like a solution that doesn't change the shorthand syntax for linking to documents.
So I'm still ok with Solution A (i.e. don't do anything) and baring that, solution 10 also seems acceptable to me, seen that we don't use the typed syntax that often so simple users won't see their habits changed.
WDYT?
Thanks
-Vincent
Some thoughts:
* I don't like any of the proposed solutions so far because they all make it harder to create links than what user already do in XWiki Syntax 2.0 or 2.1
* Solution 2 (forcing using the "doc" prefix when creating links to subwikis) is the solution that gathered the most votes. However when I think about solution 2 I think about xwiki.org and all the links I create every week from one wiki to another and I can't refrain from thinking that it's going to make more complex to create them.
* I can understand why some didn't like my proposal to have a shortcut syntax for links and a canonical one for typed references. Basically it's too complex for users.
In order to be complete, there's another possibility which is to change the delimiter for wikis or for reference types. Obviously it wouldn't be possible to change the delimiter for wikis (i.e. the ":" in "wiki:space.page") so remains the option to change the delimiter for reference types.
Here are some ideas for exploring this direction:
Solution 10
===========
* [[label>>wiki:space.page]]
* [[label>>doc::wiki:space.page]]
* [[label>>path::/some/path]]
* [[label>>http://xwiki.org]]
* [[label>>url::http://xwiki.org]]
* [[label>>user::evalica]]
* [[image:wiki:***@image.png]]
* [[image:doc::wiki:***@image.png]]
* [[image:icon::someicon.png]]
PROs:
* Syntax remains the shorter possible for links to docs and URLs
* Adding a new reference type doesn't break existing links/images
CONs:
* When using typed links/images, it's bit longer to type ("::" instead of ":")
* Small change of syntax for users but the majority of users use the shorthand notation
* Still a URI! (even if a weird one)
* Force to escape the ":" (with "~:") for spaces or documents starting with ":"
Solution 11
===========
Using URL-like notation:
* [[label>>wiki:space.page]]
* [[label>>doc://wiki:space.page]]
* [[label>>path:///some/path]]
* [[label>>http://xwiki.org]]
* [[label>>https://xwiki.org]]
* [[label>>url://http://xwiki.org]]
* [[label>>user://evalica]]
* [[image:wiki:***@image.png]]
* [[image:doc://wiki:***@image.png]]
* [[image:icon://someicon.png]]
Compared to solution 10:
PROs:
* Uses a notation closer to a URL (could be a CONs too!)
CONs:
* One more character to type "://" vs "::"
* A bit strange when linking to URLs using the typed syntax ("url://http://xwiki.org")
* Need to use the typed syntax for URLs other than "http" and "https" (e.g. for specific URL schemes, like "ftp": "url://ftp://192.168.0.1")
Solution 12
===========
Then there are other possible notations such as:
* [[label>>wiki:space.page]]
* [[label>>doc#wiki:space.page]]
* [[label>>path#/some/path]]
* [[label>>http://xwiki.org]]
* [[label>>url#http://xwiki.org]]
* [[label>>user#evalica]]
* [[image:wiki:***@image.png]]
* [[image:doc#wiki:***@image.png]]
* [[image:icon#someicon.png]]
Solution 13
===========
Or:
* [[label>>wiki:space.page]]
* [[label>>doc=wiki:space.page]]
* [[label>>path=/some/path]]
* [[label>>http://xwiki.org]]
* [[label>>url=http://xwiki.org]]
* [[label>>user=evalica]]
* [[image:wiki:***@image.png]]
* [[image:doc=wiki:***@image.png]]
* [[image:icon=someicon.png]]
Personally I'm still hesitating but seen that the majority of use cases are for links to documents, I think I'd like a solution that doesn't change the shorthand syntax for linking to documents.
So I'm still ok with Solution A (i.e. don't do anything) and baring that, solution 10 also seems acceptable to me, seen that we don't use the typed syntax that often so simple users won't see their habits changed.
WDYT?
Thanks
-Vincent
Hi devs,
Following this thread http://markmail.org/thread/vw3derowozijqalr it seems clear that we need to introduce a better syntax for links and images in XWiki Syntax 2.2 (in order to cope with use cases such as http://jira.xwiki.org/jira/browse/XRENDERING-290).
The need is to be able to plug new reference type handlers without breaking backward compatibility in XWiki Syntax 2.2 (since right now with XWiki Syntax 2.0 and 2.1 adding a new type reference handler would break backward compatibility).
So here are various proposals to that effect for XWiki Syntax 2.2 (I've only kept the interesting proposals from the previous thread). Please vote for the one you prefer or add new solutions if you have other better ideas.
Proposal 1
=========
Force XWiki Syntax 2.2 to *ALWAYS* use the full form when creating a link or image, i.e. all links would need to be written: [[label>>type:reference]]
* [[label>>doc:space.page]]
* [[label>>doc:wiki:space.page]]
* [[label>>path:/some/path]]
* [[label>>url:http://xwiki.org]]
* [[label>>user:evalica]]
* [[image:icon:someicon.png]]
* Harder to write links to documents which is the main use case
Proposal 2
=========
Same as with XWiki Syntax 2.1 but for links or images to subwikis force the user to use the "doc:" notation
* [[label>>space.page]] or [[label>>doc:space.page]]
* [[label>>doc:wiki:space.page]]
* [[label>>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
* [[label>>user:evalica]]
* [[image:icon:someicon.png]]
* Still easy to reference docs and images in the current wiki
* Close to current XWiki Syntax 2.1
* Harder to write links to documents in subwikis (for workspaces users for example, see example of xwiki.org)
Proposal 3
=========
Always define the type as a link or image parameter, i.e. separate subwiki notation from type.
* [[label>>space.page]] or [[label>>space.page||type="doc"]]
* [[label>>wiki:space.page]] or [[label>>wiki:space.page||type="doc"]]
* [[label>>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org||type="url"]]
* [[label>>evalica||type="user"]]
* [[image:someicon.png||type="icon"]]
* Still easy to reference docs
* Clear separation between subwiki and types
* Harder to write typed links
* Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks
-Vincent
Following this thread http://markmail.org/thread/vw3derowozijqalr it seems clear that we need to introduce a better syntax for links and images in XWiki Syntax 2.2 (in order to cope with use cases such as http://jira.xwiki.org/jira/browse/XRENDERING-290).
The need is to be able to plug new reference type handlers without breaking backward compatibility in XWiki Syntax 2.2 (since right now with XWiki Syntax 2.0 and 2.1 adding a new type reference handler would break backward compatibility).
So here are various proposals to that effect for XWiki Syntax 2.2 (I've only kept the interesting proposals from the previous thread). Please vote for the one you prefer or add new solutions if you have other better ideas.
Proposal 1
=========
Force XWiki Syntax 2.2 to *ALWAYS* use the full form when creating a link or image, i.e. all links would need to be written: [[label>>type:reference]]
* [[label>>doc:space.page]]
* [[label>>doc:wiki:space.page]]
* [[label>>path:/some/path]]
* [[label>>url:http://xwiki.org]]
* [[label>>user:evalica]]
* [[image:icon:someicon.png]]
* Harder to write links to documents which is the main use case
Proposal 2
=========
Same as with XWiki Syntax 2.1 but for links or images to subwikis force the user to use the "doc:" notation
* [[label>>space.page]] or [[label>>doc:space.page]]
* [[label>>doc:wiki:space.page]]
* [[label>>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
* [[label>>user:evalica]]
* [[image:icon:someicon.png]]
* Still easy to reference docs and images in the current wiki
* Close to current XWiki Syntax 2.1
* Harder to write links to documents in subwikis (for workspaces users for example, see example of xwiki.org)
Proposal 3
=========
Always define the type as a link or image parameter, i.e. separate subwiki notation from type.
* [[label>>space.page]] or [[label>>space.page||type="doc"]]
* [[label>>wiki:space.page]] or [[label>>wiki:space.page||type="doc"]]
* [[label>>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org||type="url"]]
* [[label>>evalica||type="user"]]
* [[image:someicon.png||type="icon"]]
* Still easy to reference docs
* Clear separation between subwiki and types
* Harder to write typed links
* Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks
-Vincent