[xwiki-devs] [VOTE] New Link and Image syntax for XWiki Syntax 2.2
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]] Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]] CONS: * 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 Examples: * [[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:doc:wiki:[email protected]]] * [[image:icon:someicon.png]] PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1 CONS: * 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. Examples: * [[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:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]] PRO: * Still easy to reference docs * Clear separation between subwiki and types CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters Thanks -Vincent
My vote below (please only vote for 1 proposal! :)) On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[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:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
+1 for proposal 3. Thanks -Vincent
Thanks -Vincent
Hello, +1 for proposal 3. Raluca. On Tue, Apr 30, 2013 at 12:02 PM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[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:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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:wiki:[email protected]]] or [[image:wiki:[email protected] ||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Typos below. On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org||type="url"]] Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks -Vincent
Hi devs, I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal. If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now). So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1 Thanks, On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
+1 for Proposal 2 Thanks, Caty On Tue, Apr 30, 2013 at 2:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
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
On Tue, Apr 30, 2013 at 2:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter)
+1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL).
Are you referring to URI? because URN and URL are complementary. An URL is not a URN. +1 for proposal 2, but as Thomas, I'm not fully decided. Thanks, Marius
Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
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
On Tue, Apr 30, 2013 at 5:29 PM, Marius Dumitru Florea < [email protected]> wrote:
On Tue, Apr 30, 2013 at 2:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter)
+1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL).
Are you referring to URI? because URN and URL are complementary. An URL is not a URN.
My bad, obviously, I was thinking URI and not URN (which is what we could mainly use for URI of our internal ressource however).
+1 for proposal 2, but as Thomas, I'm not fully decided.
Thanks, Marius
Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org ]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
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
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
Hi Denis, On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
I also prefer URIs but my problem with solution 2 is having to prefix with "doc:" for links to subwikis. This is pretty common. I had proposed another solution in the other thread with a different notation for proper URI notations. The idea was to use the shortcut notation when you wanted to use document references for simplicity reasons and use the proper syntax when you use proper URIs. Maybe that solution wasn't that bad. I'm putting it again here (with a difference using [[[…]]] instead of >>> as I had said since that doesn't work for images): * Shortcut notation for doc refs: [[label>>docref]] * General notations for URIs: [[[label>>type:reference]]] * Shortcut notation for images: [[image:docref]] * General notation for URIs in images: [[[image:type:reference]]] It looks clunky at first but it isn't really since it represents what we want: * shortcut notation for doc URIs * full notation for any URI WDYT? Thanks -Vincent
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks -Vincent
On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
I also prefer URIs but my problem with solution 2 is having to prefix with "doc:" for links to subwikis. This is pretty common.
I do not see why this is so annoying, we type http:// to start URLs, and I do not feel anyone has ever complains. So, solution 1 is not that bad, and solution 2 is only a feature over it, for those who use very basic feature. It compare to the omnibox of chrome that try to be clever and works in most situations, but some still require you to enter the http:// prefix.
I had proposed another solution in the other thread with a different notation for proper URI notations. The idea was to use the shortcut notation when you wanted to use document references for simplicity reasons and use the proper syntax when you use proper URIs.
Maybe that solution wasn't that bad. I'm putting it again here (with a difference using [[[…]]] instead of >>> as I had said since that doesn't work for images):
* Shortcut notation for doc refs: [[label>>docref]] * General notations for URIs: [[[label>>type:reference]]] * Shortcut notation for images: [[image:docref]] * General notation for URIs in images: [[[image:type:reference]]]
It looks clunky at first but it isn't really since it represents what we want: * shortcut notation for doc URIs * full notation for any URI
WDYT?
This again increase complexity (from a user POV) for very little benefit IMO. It look odd and again it cannot be applied anywhere, like in macros. So I see this fourth solution not much better than solution 3.
Thanks -Vincent
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org ]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
Hi Denis, On Apr 30, 2013, at 11:21 PM, Denis Gervalle <[email protected]> wrote:
On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
I also prefer URIs but my problem with solution 2 is having to prefix with "doc:" for links to subwikis. This is pretty common.
I do not see why this is so annoying, we type http:// to start URLs, and I do not feel anyone has ever complains.
Yes but we don't type URLs often at all… We navigate by clicking. Imagine that every time you click on a link you had to instead type it, it would become quickly an issue… In any case I think the main issue now is that 1) we have already offered a simpler way for users to type references to docs and 2) other wikis also propose this simpler way. Because of these 2 points, I'm not sure we can ever go back to making it harder to type references to docs...
So, solution 1 is not that bad, and solution 2 is only a feature over it, for those who use very basic feature. It compare to the omnibox of chrome that try to be clever and works in most situations, but some still require you to enter the http:// prefix.
I had proposed another solution in the other thread with a different notation for proper URI notations. The idea was to use the shortcut notation when you wanted to use document references for simplicity reasons and use the proper syntax when you use proper URIs.
Maybe that solution wasn't that bad. I'm putting it again here (with a difference using [[[…]]] instead of >>> as I had said since that doesn't work for images):
* Shortcut notation for doc refs: [[label>>docref]] * General notations for URIs: [[[label>>type:reference]]] * Shortcut notation for images: [[image:docref]] * General notation for URIs in images: [[[image:type:reference]]]
It looks clunky at first but it isn't really since it represents what we want: * shortcut notation for doc URIs * full notation for any URI
WDYT?
This again increase complexity (from a user POV) for very little benefit IMO. It look odd and again it cannot be applied anywhere, like in macros. So I see this fourth solution not much better than solution 3.
You're not very logical here :) You said you wanted URIs and solution 4 is about URIs while solution 3 isn't about URIs so you should prefer solution 4 over solution 3 normally :) If you're keen on URIs (as I am, thanks for reminding me that in your email btw :)), then I believe solution 4 is currently the best one. Thanks -Vincent
Thanks -Vincent
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org ]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
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
Hi Vincent, On Wed, May 1, 2013 at 7:48 AM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 11:21 PM, Denis Gervalle <[email protected]> wrote:
On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
I also prefer URIs but my problem with solution 2 is having to prefix with "doc:" for links to subwikis. This is pretty common.
I do not see why this is so annoying, we type http:// to start URLs, and I do not feel anyone has ever complains.
Yes but we don't type URLs often at all… We navigate by clicking. Imagine that every time you click on a link you had to instead type it, it would become quickly an issue…
Are we talking about navigating the wiki ? no, we are talking about editing hyperlinked documents, and you need to type the http:// as soon as you refer a document outside of your current server. Isn't that comparable to linking document in another wiki ?
In any case I think the main issue now is that 1) we have already offered a simpler way for users to type references to docs and 2) other wikis also propose this simpler way. Because of these 2 points, I'm not sure we can ever go back to making it harder to type references to docs...
I do not believe 1) is a good argument. First, if users prefer simpler syntax for subwiki's links compare to an extensible URI base syntax, they may simply continue to use syntax 2.1. Second, are there so much users with that preference, that also use multiple wikis with links between them ? Finally, we also provide other means to create documents then writing them using the xwiki syntax. We could also think about improving the editor to insert link/image more easily. So is the limitation of solution 2, imposed by the need for flexibility, so blocker, as you seems to believe ? Regarding point 2), I have not enough knowledge of other wikis, but it could be interesting to elaborate and see how and which of those other wikis really support easy interwiki links in there syntax, while providing at the same time support to different kind of ressources. I may be wrong, but I do not believe there will be numerous competitor with those criteria.
So, solution 1 is not that bad, and solution 2 is only a feature over it, for those who use very basic feature. It compare to the omnibox of chrome that try to be clever and works in most situations, but some still require you to enter the http:// prefix.
I had proposed another solution in the other thread with a different notation for proper URI notations. The idea was to use the shortcut notation when you wanted to use document references for simplicity reasons and use the proper syntax when you use proper URIs.
Maybe that solution wasn't that bad. I'm putting it again here (with a difference using [[[…]]] instead of >>> as I had said since that doesn't work for images):
* Shortcut notation for doc refs: [[label>>docref]] * General notations for URIs: [[[label>>type:reference]]] * Shortcut notation for images: [[image:docref]] * General notation for URIs in images: [[[image:type:reference]]]
It looks clunky at first but it isn't really since it represents what we want: * shortcut notation for doc URIs * full notation for any URI
WDYT?
This again increase complexity (from a user POV) for very little benefit IMO. It look odd and again it cannot be applied anywhere, like in macros. So I see this fourth solution not much better than solution 3.
You're not very logical here :) You said you wanted URIs and solution 4 is about URIs while solution 3 isn't about URIs so you should prefer solution 4 over solution 3 normally :)
Have I said the contrary ? 4 is better than 3, but not that much IMO since we still have the split issue. 4 solve the problem for your current needs, but does not lead to a general way of identifying ressources in XWiki. Having a consistant solution is also important, and a good way to simplify the user experience. If you're keen on URIs (as I am, thanks for reminding me that in your email
btw :)), then I believe solution 4 is currently the best one.
I do not agree, if you're keen on URIs (and I am) Solution 1 is the best one, considering it will only affect a new syntax.
Thanks -Vincent
Thanks -Vincent
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url: http://xwiki.org ]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
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
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
On May 1, 2013, at 7:44 PM, Denis Gervalle <[email protected]> wrote:
Hi Vincent,
On Wed, May 1, 2013 at 7:48 AM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 11:21 PM, Denis Gervalle <[email protected]> wrote:
On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
I also prefer URIs but my problem with solution 2 is having to prefix with "doc:" for links to subwikis. This is pretty common.
I do not see why this is so annoying, we type http:// to start URLs, and I do not feel anyone has ever complains.
Yes but we don't type URLs often at all… We navigate by clicking. Imagine that every time you click on a link you had to instead type it, it would become quickly an issue…
Are we talking about navigating the wiki ? no, we are talking about editing hyperlinked documents, and you need to type the http:// as soon as you refer a document outside of your current server. Isn't that comparable to linking document in another wiki ?
I never ever type a URL! The only thing I do is copy paste URLs into documents…
In any case I think the main issue now is that 1) we have already offered a simpler way for users to type references to docs and 2) other wikis also propose this simpler way. Because of these 2 points, I'm not sure we can ever go back to making it harder to type references to docs...
I do not believe 1) is a good argument. First, if users prefer simpler syntax for subwiki's links compare to an extensible URI base syntax, they may simply continue to use syntax 2.1.
Bad argument because our goal is to move users to the latest syntax. The idea is that the latest syntax is better so, no, we cannot say to users that they should stay on the old syntax because it's nicer to type link refs… :)
Second, are there so much users with that preference, that also use multiple wikis with links between them ?
I think so, especially since we're making XEM the default (first step was virtual=1 by default, second step is to be able to create wikis by default).
Finally, we also provide other means to create documents then writing them using the xwiki syntax. We could also think about improving the editor to insert link/image more easily.
IMO this fails the concept of the wiki syntax which is to be extra simple and quick to use. So yes auto completion on linking/images is a good thing we need in the future but if we could also have a simple syntax at least for doc ref it would be good.
So is the limitation of solution 2, imposed by the need for flexibility, so blocker, as you seems to believe ?
- Solution 1 is nice because it's simple and coherent. But harder to write doc refs - Solution 2 is slightly less nice because not coherent. Simple to write doc refs but not cross wikis. - Solution 3 is less nice because it drops the concept of URIs which could prove useful in the future for other things in XWiki - Solution 4: is less nice than 1 because less coherent but at the same level of coherency as solution 2 and 3 and at the same time it doesn't have the drawback of solution 2. It's very close to solution 3 but keeping the concept of URIs.
Regarding point 2), I have not enough knowledge of other wikis, but it could be interesting to elaborate and see how and which of those other wikis really support easy interwiki links in there syntax, while providing at the same time support to different kind of ressources. I may be wrong, but I do not believe there will be numerous competitor with those criteria.
They don't have this concept. But we need to be careful, we cannot allow to be powerful and complex. We need to be powerful and simple. So making the main use case hard just for supporting other use cases that are used 5% of the time is not a good solution IMO.
So, solution 1 is not that bad, and solution 2 is only a feature over it, for those who use very basic feature. It compare to the omnibox of chrome that try to be clever and works in most situations, but some still require you to enter the http:// prefix.
I had proposed another solution in the other thread with a different notation for proper URI notations. The idea was to use the shortcut notation when you wanted to use document references for simplicity reasons and use the proper syntax when you use proper URIs.
Maybe that solution wasn't that bad. I'm putting it again here (with a difference using [[[…]]] instead of >>> as I had said since that doesn't work for images):
* Shortcut notation for doc refs: [[label>>docref]] * General notations for URIs: [[[label>>type:reference]]] * Shortcut notation for images: [[image:docref]] * General notation for URIs in images: [[[image:type:reference]]]
It looks clunky at first but it isn't really since it represents what we want: * shortcut notation for doc URIs * full notation for any URI
WDYT?
This again increase complexity (from a user POV) for very little benefit IMO. It look odd and again it cannot be applied anywhere, like in macros. So I see this fourth solution not much better than solution 3.
You're not very logical here :) You said you wanted URIs and solution 4 is about URIs while solution 3 isn't about URIs so you should prefer solution 4 over solution 3 normally :)
Have I said the contrary ? 4 is better than 3, but not that much IMO since we still have the split issue. 4 solve the problem for your current needs, but does not lead to a general way of identifying ressources in XWiki.
It does! It's like solution 1 actually. Again here it is (and again we could think of another syntax if we want, we don't have to use [[[…]]], we could use for example [[[label>>type:reference]]] Now just because we want to make it easy to type doc ref we also allow a **shortcut** (not the canonical way!): [[label>>docref]]
Having a consistant solution is also important, and a good way to simplify the user experience.
Yes but only solution 1 provides this but at a big cost which I currently consider too large. Of course since this is an important decision I'd like to know what others think too.
If you're keen on URIs (as I am, thanks for reminding me that in your email
btw :)), then I believe solution 4 is currently the best one.
I do not agree, if you're keen on URIs (and I am) Solution 1 is the best one, considering it will only affect a new syntax.
Thanks -Vincent
Thanks -Vincent
Thanks -Vincent
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
> 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]] > > Examples: > * [[label>>doc:space.page]] > * [[label>>doc:wiki:space.page]] > * [[label>>path:/some/path]] > * [[label>>url:http://xwiki.org]] > * [[label>>user:evalica]] > * [[image:doc:wiki:[email protected]]] > * [[image:icon:someicon.png]] > > CONS: > * 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 > > Examples: > * [[label>>space.page]] or [[label>>doc:space.page]] > * [[label>>doc:wiki:space.page]] > * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
> * [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url: http://xwiki.org ]]
> * [[label>>user:evalica]] > * [[image:doc:wiki:[email protected]]] > * [[image:icon:someicon.png]] > > PRO: > * Still easy to reference docs and images in the current wiki > * Close to current XWiki Syntax 2.1 > > CONS: > * 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. > > Examples: > * [[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"]]
Should be [[label>>/some/path||type="path"]]
> * [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
> * [[label>>evalica||type="user"]] > * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] > * [[image:someicon.png||type="icon"]] > > PRO: > * Still easy to reference docs > * Clear separation between subwiki and types > > CONS: > * Harder to write typed links > * Harder to write references in non xwiki/2.x syntax that would not support link parameters > > Thanks > -Vincent
On May 2, 2013, at 8:36 AM, Vincent Massol <[email protected]> wrote:
On May 1, 2013, at 7:44 PM, Denis Gervalle <[email protected]> wrote:
Hi Vincent,
On Wed, May 1, 2013 at 7:48 AM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 11:21 PM, Denis Gervalle <[email protected]> wrote:
On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
I also prefer URIs but my problem with solution 2 is having to prefix with "doc:" for links to subwikis. This is pretty common.
I do not see why this is so annoying, we type http:// to start URLs, and I do not feel anyone has ever complains.
Yes but we don't type URLs often at all… We navigate by clicking. Imagine that every time you click on a link you had to instead type it, it would become quickly an issue…
Are we talking about navigating the wiki ? no, we are talking about editing hyperlinked documents, and you need to type the http:// as soon as you refer a document outside of your current server. Isn't that comparable to linking document in another wiki ?
I never ever type a URL! The only thing I do is copy paste URLs into documents…
In any case I think the main issue now is that 1) we have already offered a simpler way for users to type references to docs and 2) other wikis also propose this simpler way. Because of these 2 points, I'm not sure we can ever go back to making it harder to type references to docs...
I do not believe 1) is a good argument. First, if users prefer simpler syntax for subwiki's links compare to an extensible URI base syntax, they may simply continue to use syntax 2.1.
Bad argument because our goal is to move users to the latest syntax. The idea is that the latest syntax is better so, no, we cannot say to users that they should stay on the old syntax because it's nicer to type link refs… :)
Second, are there so much users with that preference, that also use multiple wikis with links between them ?
I think so, especially since we're making XEM the default (first step was virtual=1 by default, second step is to be able to create wikis by default).
Finally, we also provide other means to create documents then writing them using the xwiki syntax. We could also think about improving the editor to insert link/image more easily.
IMO this fails the concept of the wiki syntax which is to be extra simple and quick to use. So yes auto completion on linking/images is a good thing we need in the future but if we could also have a simple syntax at least for doc ref it would be good.
So is the limitation of solution 2, imposed by the need for flexibility, so blocker, as you seems to believe ?
- Solution 1 is nice because it's simple and coherent. But harder to write doc refs - Solution 2 is slightly less nice because not coherent. Simple to write doc refs but not cross wikis. - Solution 3 is less nice because it drops the concept of URIs which could prove useful in the future for other things in XWiki - Solution 4: is less nice than 1 because less coherent but at the same level of coherency as solution 2 and 3 and at the same time it doesn't have the drawback of solution 2. It's very close to solution 3 but keeping the concept of URIs.
Regarding point 2), I have not enough knowledge of other wikis, but it could be interesting to elaborate and see how and which of those other wikis really support easy interwiki links in there syntax, while providing at the same time support to different kind of ressources. I may be wrong, but I do not believe there will be numerous competitor with those criteria.
They don't have this concept. But we need to be careful, we cannot allow to be powerful and complex. We need to be powerful and simple. So making the main use case hard just for supporting other use cases that are used 5% of the time is not a good solution IMO.
So, solution 1 is not that bad, and solution 2 is only a feature over it, for those who use very basic feature. It compare to the omnibox of chrome that try to be clever and works in most situations, but some still require you to enter the http:// prefix.
I had proposed another solution in the other thread with a different notation for proper URI notations. The idea was to use the shortcut notation when you wanted to use document references for simplicity reasons and use the proper syntax when you use proper URIs.
Maybe that solution wasn't that bad. I'm putting it again here (with a difference using [[[…]]] instead of >>> as I had said since that doesn't work for images):
* Shortcut notation for doc refs: [[label>>docref]] * General notations for URIs: [[[label>>type:reference]]] * Shortcut notation for images: [[image:docref]] * General notation for URIs in images: [[[image:type:reference]]]
It looks clunky at first but it isn't really since it represents what we want: * shortcut notation for doc URIs * full notation for any URI
WDYT?
This again increase complexity (from a user POV) for very little benefit IMO. It look odd and again it cannot be applied anywhere, like in macros. So I see this fourth solution not much better than solution 3.
You're not very logical here :) You said you wanted URIs and solution 4 is about URIs while solution 3 isn't about URIs so you should prefer solution 4 over solution 3 normally :)
Have I said the contrary ? 4 is better than 3, but not that much IMO since we still have the split issue. 4 solve the problem for your current needs, but does not lead to a general way of identifying ressources in XWiki.
It does! It's like solution 1 actually. Again here it is (and again we could think of another syntax if we want, we don't have to use [[[…]]], we could use for example
didn't finish my sentence… :) I meant to say that we could some other markup if we didn't want to have 3 [[[ and ]]]. Thanks -Vincent
[[[label>>type:reference]]]
Now just because we want to make it easy to type doc ref we also allow a **shortcut** (not the canonical way!):
[[label>>docref]]
Having a consistant solution is also important, and a good way to simplify the user experience.
Yes but only solution 1 provides this but at a big cost which I currently consider too large.
Of course since this is an important decision I'd like to know what others think too.
If you're keen on URIs (as I am, thanks for reminding me that in your email
btw :)), then I believe solution 4 is currently the best one.
I do not agree, if you're keen on URIs (and I am) Solution 1 is the best one, considering it will only affect a new syntax.
Thanks -Vincent
Thanks -Vincent
Thanks -Vincent
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
> Typos below. > > On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote: > >> 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]] >> >> Examples: >> * [[label>>doc:space.page]] >> * [[label>>doc:wiki:space.page]] >> * [[label>>path:/some/path]] >> * [[label>>url:http://xwiki.org]] >> * [[label>>user:evalica]] >> * [[image:doc:wiki:[email protected]]] >> * [[image:icon:someicon.png]] >> >> CONS: >> * 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 >> >> Examples: >> * [[label>>space.page]] or [[label>>doc:space.page]] >> * [[label>>doc:wiki:space.page]] >> * [[label>>>path:/some/path]] > > Should be [[label>>path:/some/path]] > >> * [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]] > > Should be [[label>>http://xwiki.org]] or [[label>>url: http://xwiki.org ]] > >> * [[label>>user:evalica]] >> * [[image:doc:wiki:[email protected]]] >> * [[image:icon:someicon.png]] >> >> PRO: >> * Still easy to reference docs and images in the current wiki >> * Close to current XWiki Syntax 2.1 >> >> CONS: >> * 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. >> >> Examples: >> * [[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"]] > > Should be [[label>>/some/path||type="path"]] > >> * [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org > ||type="url"]] > > Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org > ||type="url"]] > > Thanks > -Vincent > >> * [[label>>evalica||type="user"]] >> * [[image:wiki:[email protected]]] or > [[image:wiki:[email protected]||type="doc"]] >> * [[image:someicon.png||type="icon"]] >> >> PRO: >> * Still easy to reference docs >> * Clear separation between subwiki and types >> >> CONS: >> * Harder to write typed links >> * Harder to write references in non xwiki/2.x syntax that would not > support link parameters >> >> Thanks >> -Vincent
On Thu, May 2, 2013 at 8:36 AM, Vincent Massol <[email protected]> wrote:
On May 1, 2013, at 7:44 PM, Denis Gervalle <[email protected]> wrote:
Hi Vincent,
On Wed, May 1, 2013 at 7:48 AM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 11:21 PM, Denis Gervalle <[email protected]> wrote:
On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
I also prefer URIs but my problem with solution 2 is having to prefix with "doc:" for links to subwikis. This is pretty common.
I do not see why this is so annoying, we type http:// to start URLs, and I do not feel anyone has ever complains.
Yes but we don't type URLs often at all… We navigate by clicking. Imagine that every time you click on a link you had to instead type it, it would become quickly an issue…
Are we talking about navigating the wiki ? no, we are talking about editing hyperlinked documents, and you need to type the http:// as soon as you refer a document outside of your current server. Isn't that comparable to linking document in another wiki ?
I never ever type a URL! The only thing I do is copy paste URLs into documents…
In any case I think the main issue now is that 1) we have already offered a simpler way for users to type references to docs and 2) other wikis also propose this simpler way. Because of these 2 points, I'm not sure we can ever go back to making it harder to type references to docs...
I do not believe 1) is a good argument. First, if users prefer simpler syntax for subwiki's links compare to an extensible URI base syntax, they may simply continue to use syntax 2.1.
Bad argument because our goal is to move users to the latest syntax. The idea is that the latest syntax is better so, no, we cannot say to users that they should stay on the old syntax because it's nicer to type link refs… :)
Second, are there so much users with that preference, that also use multiple wikis with links between them ?
I think so, especially since we're making XEM the default (first step was virtual=1 by default, second step is to be able to create wikis by default).
While we do so, we do not deploy anything to create more than one wiki in our default flavor. And anyway, you said earlier that, mainly, solution 1) is bad because we have already provided a simpler solution. But using solution 2), it became only true for user of multiple wikis, that do link between those wikis, and that write those links by hand. I continue to think this is not the majority of our user currently.
Finally, we also provide other means to create documents then writing them using the xwiki syntax. We could also think about improving the editor to insert link/image more easily.
IMO this fails the concept of the wiki syntax which is to be extra simple and quick to use. So yes auto completion on linking/images is a good thing we need in the future but if we could also have a simple syntax at least for doc ref it would be good.
Well, using a doc: prefix for document reference is IMO far simpler than to remember that your reference are interpreted differently depending on an additional [] or any other tricky syntax.
So is the limitation of solution 2, imposed by the need for flexibility, so blocker, as you seems to believe ?
- Solution 1 is nice because it's simple and coherent. But harder to write doc refs - Solution 2 is slightly less nice because not coherent. Simple to write doc refs but not cross wikis. - Solution 3 is less nice because it drops the concept of URIs which could prove useful in the future for other things in XWiki - Solution 4: is less nice than 1 because less coherent but at the same level of coherency as solution 2 and 3 and at the same time it doesn't have the drawback of solution 2. It's very close to solution 3 but keeping the concept of URIs.
IMO, you bias your conclusion by considering the multiwiki situation, with cross-linking as the default most used configuration.
Regarding point 2), I have not enough knowledge of other wikis, but it could be interesting to elaborate and see how and which of those other wikis really support easy interwiki links in there syntax, while providing at the same time support to different kind of ressources. I may be wrong, but I do not believe there will be numerous competitor with those criteria.
They don't have this concept. But we need to be careful, we cannot allow to be powerful and complex. We need to be powerful and simple. So making the main use case hard just for supporting other use cases that are used 5% of the time is not a good solution IMO.
Again, this is not fair, the main use case is link to local document, this is why I prefer solution 2) than 1).
So, solution 1 is not that bad, and solution 2 is only a feature over it, for those who use very basic feature. It compare to the omnibox of chrome that try to be clever and works in most situations, but some still require you to enter the http:// prefix.
I had proposed another solution in the other thread with a different notation for proper URI notations. The idea was to use the shortcut notation when you wanted to use document references for simplicity reasons and use the proper syntax when you use proper URIs.
Maybe that solution wasn't that bad. I'm putting it again here (with a difference using [[[…]]] instead of >>> as I had said since that doesn't work for images):
* Shortcut notation for doc refs: [[label>>docref]] * General notations for URIs: [[[label>>type:reference]]] * Shortcut notation for images: [[image:docref]] * General notation for URIs in images: [[[image:type:reference]]]
It looks clunky at first but it isn't really since it represents what we want: * shortcut notation for doc URIs * full notation for any URI
WDYT?
This again increase complexity (from a user POV) for very little benefit IMO. It look odd and again it cannot be applied anywhere, like in macros. So I see this fourth solution not much better than solution 3.
You're not very logical here :) You said you wanted URIs and solution 4 is about URIs while solution 3 isn't about URIs so you should prefer solution 4 over solution 3 normally :)
Have I said the contrary ? 4 is better than 3, but not that much IMO since we still have the split issue. 4 solve the problem for your current needs, but does not lead to a general way of identifying ressources in XWiki.
It does! It's like solution 1 actually. Again here it is (and again we could think of another syntax if we want, we don't have to use [[[…]]], we could use for example
[[[label>>type:reference]]]
Now just because we want to make it easy to type doc ref we also allow a **shortcut** (not the canonical way!):
[[label>>docref]]
Having a consistant solution is also important, and a good way to simplify the user experience.
Yes but only solution 1 provides this but at a big cost which I currently consider too large.
Of course since this is an important decision I'd like to know what others think too.
I would like other opinions as well, especially of how others see the cost of 1), and about which is the main use case ?
If you're keen on URIs (as I am, thanks for reminding me that in your email
btw :)), then I believe solution 4 is currently the best one.
I do not agree, if you're keen on URIs (and I am) Solution 1 is the best one, considering it will only affect a new syntax.
Thanks -Vincent
Thanks -Vincent
Thanks -Vincent
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]
wrote:
> Typos below. > > On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]>
wrote:
> >> Hi devs, >> >> Following this thread http://markmail.org/thread/vw3derowozijqalrit > 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]] >> >> Examples: >> * [[label>>doc:space.page]] >> * [[label>>doc:wiki:space.page]] >> * [[label>>path:/some/path]] >> * [[label>>url:http://xwiki.org]] >> * [[label>>user:evalica]] >> * [[image:doc:wiki:[email protected]]] >> * [[image:icon:someicon.png]] >> >> CONS: >> * 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 >> >> Examples: >> * [[label>>space.page]] or [[label>>doc:space.page]] >> * [[label>>doc:wiki:space.page]] >> * [[label>>>path:/some/path]] > > Should be [[label>>path:/some/path]] > >> * [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]] > > Should be [[label>>http://xwiki.org]] or [[label>>url: http://xwiki.org ]] > >> * [[label>>user:evalica]] >> * [[image:doc:wiki:[email protected]]] >> * [[image:icon:someicon.png]] >> >> PRO: >> * Still easy to reference docs and images in the current wiki >> * Close to current XWiki Syntax 2.1 >> >> CONS: >> * 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. >> >> Examples: >> * [[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"]] > > Should be [[label>>/some/path||type="path"]] > >> * [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org > ||type="url"]] > > Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org > ||type="url"]] > > Thanks > -Vincent > >> * [[label>>evalica||type="user"]] >> * [[image:wiki:[email protected]]] or > [[image:wiki:[email protected]||type="doc"]] >> * [[image:someicon.png||type="icon"]] >> >> PRO: >> * Still easy to reference docs >> * Clear separation between subwiki and types >> >> CONS: >> * Harder to write typed links >> * Harder to write references in non xwiki/2.x syntax that would not > support link parameters >> >> Thanks >> -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
Hi all, Le 2 mai 2013 10:16, "Denis Gervalle" <[email protected]> a écrit :
On Thu, May 2, 2013 at 8:36 AM, Vincent Massol <[email protected]> wrote:
On May 1, 2013, at 7:44 PM, Denis Gervalle <[email protected]> wrote:
Hi Vincent,
On Wed, May 1, 2013 at 7:48 AM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 11:21 PM, Denis Gervalle <[email protected]> wrote:
On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote:
> Hi devs, > > I have a very bad feeling with proposal 3, since it split the identifier, > which makes its main part to loose its meaning when taken alone.
So
you
> cannot comunicate the whole information easily on different channels (think > about copy/pasting such reference ?). This is also really verbose, sometime > it looks odd, and I found it to be complex from a user view point. > Moreover, it could not be easily applied in other situation than links, > while ressource identification is not limited to links (think about a macro > arguments ?, see MotionComposer macro that imitate image: for an example). > I know it is hard, but I am currently -1 for this proposal. > > If we look at large, what we really need and intend to achieve is to have > an extensible syntax to identify ressources in XWiki. There is obviously a > ready made standardized syntax for such purpose: URN. Proposal 1 is really > near that specification (but too verbose for URL), but I agree with Thomas > that users will complains to be forced to use doc: everywhere. This is > precisely why I made proposal 2, which will fully avoid that constrains for > user of single wikis (a lot of our user since XE was our mostly downloaded > distribution until now). > > So my vote are (sorry Vincent, but your request to have a truly single vote > is far too restrictive for this matter) > +1 to really conform with a URN syntax as much as possible (remove the > useless verbosity for URL). > Proposal 1: +0 > Proposal 2: +1 > Proposal 3: -1
I also prefer URIs but my problem with solution 2 is having to prefix with "doc:" for links to subwikis. This is pretty common.
I do not see why this is so annoying, we type http:// to start URLs, and I do not feel anyone has ever complains.
Yes but we don't type URLs often at all… We navigate by clicking. Imagine that every time you click on a link you had to instead type it, it would become quickly an issue…
Are we talking about navigating the wiki ? no, we are talking about editing hyperlinked documents, and you need to type the http:// as soon as you refer a document outside of your current server. Isn't that comparable to linking document in another wiki ?
I never ever type a URL! The only thing I do is copy paste URLs into documents…
In any case I think the main issue now is that 1) we have already offered a simpler way for users to type references to docs and 2) other wikis also propose this simpler way. Because of these 2 points, I'm not sure we can ever go back to making it harder to type references to docs...
I do not believe 1) is a good argument. First, if users prefer simpler syntax for subwiki's links compare to an extensible URI base syntax, they may simply continue to use syntax 2.1.
Bad argument because our goal is to move users to the latest syntax. The idea is that the latest syntax is better so, no, we cannot say to users that they should stay on the old syntax because it's nicer to type link refs… :)
Second, are there so much users with that preference, that also use multiple wikis with links between them ?
I think so, especially since we're making XEM the default (first step was virtual=1 by default, second step is to be able to create wikis by default).
While we do so, we do not deploy anything to create more than one wiki in our default flavor. And anyway, you said earlier that, mainly, solution 1) is bad because we have already provided a simpler solution. But using solution 2), it became only true for user of multiple wikis, that do link between those wikis, and that write those links by hand. I continue to think this is not the majority of our user currently.
Finally, we also provide other means to create documents then writing them using the xwiki syntax. We could also think about improving the
editor to
insert link/image more easily.
IMO this fails the concept of the wiki syntax which is to be extra simple and quick to use. So yes auto completion on linking/images is a good thing we need in the future but if we could also have a simple syntax at least for doc ref it would be good.
Well, using a doc: prefix for document reference is IMO far simpler than to remember that your reference are interpreted differently depending on an additional [] or any other tricky syntax.
So is the limitation of solution 2, imposed by the need for
flexibility,
so
blocker, as you seems to believe ?
- Solution 1 is nice because it's simple and coherent. But harder to write doc refs - Solution 2 is slightly less nice because not coherent. Simple to write doc refs but not cross wikis. - Solution 3 is less nice because it drops the concept of URIs which could prove useful in the future for other things in XWiki - Solution 4: is less nice than 1 because less coherent but at the same level of coherency as solution 2 and 3 and at the same time it doesn't have the drawback of solution 2. It's very close to solution 3 but keeping the concept of URIs.
IMO, you bias your conclusion by considering the multiwiki situation, with cross-linking as the default most used configuration.
Regarding point 2), I have not enough knowledge of other wikis, but it could be interesting to elaborate and see how and which of those other wikis really support easy interwiki links in there syntax, while providing at the same time support to different kind of ressources. I may be
wrong,
but I do not believe there will be numerous competitor with those criteria.
They don't have this concept. But we need to be careful, we cannot allow to be powerful and complex. We need to be powerful and simple. So making the main use case hard just for supporting other use cases that are used 5% of the time is not a good solution IMO.
Again, this is not fair, the main use case is link to local document, this is why I prefer solution 2) than 1).
So, solution 1 is not that bad, and solution 2 is only a feature over it, for those who use very basic feature. It compare to the omnibox of chrome that try to be clever and works
in
most
situations, but some still require you to enter the http:// prefix.
I had proposed another solution in the other thread with a different notation for proper URI notations. The idea was to use the shortcut notation when you wanted to use document references for simplicity reasons and use the proper syntax when you use proper URIs.
Maybe that solution wasn't that bad. I'm putting it again here (with a difference using [[[…]]] instead of >>> as I had said since that doesn't work for images):
* Shortcut notation for doc refs: [[label>>docref]] * General notations for URIs: [[[label>>type:reference]]] * Shortcut notation for images: [[image:docref]] * General notation for URIs in images: [[[image:type:reference]]]
It looks clunky at first but it isn't really since it represents what we want: * shortcut notation for doc URIs * full notation for any URI
WDYT?
This again increase complexity (from a user POV) for very little benefit IMO. It look odd and again it cannot be applied anywhere, like in macros. So I see this fourth solution not much better than solution 3.
You're not very logical here :) You said you wanted URIs and solution 4 is about URIs while solution 3 isn't about URIs so you should prefer solution 4 over solution 3 normally :)
Have I said the contrary ? 4 is better than 3, but not that much IMO since we still have the split issue. 4 solve the problem for your current needs, but does not lead to a general way of identifying ressources in XWiki.
It does! It's like solution 1 actually. Again here it is (and again we could think of another syntax if we want, we don't have to use [[[…]]], we could use for example
[[[label>>type:reference]]]
Now just because we want to make it easy to type doc ref we also allow a **shortcut** (not the canonical way!):
[[label>>docref]]
Having a consistant solution is also important, and a good way to simplify the user experience.
Yes but only solution 1 provides this but at a big cost which I currently consider too large.
Of course since this is an important decision I'd like to know what others think too.
I would like other opinions as well, especially of how others see the cost of 1), and about which is the main use case ?
Personally I would prefer solution 2, because it has the least impact on main use case. I'm not sure about cross wiki or workspace links, because currently I have a mono wiki instance. But it seems logical to have much more intra wiki links. Also, I'm not sure about what would bring those new syntaxes to the user. I think they don't really care about coherence, as long as it's intuitive and most of all easy to type. If I remember well, the concept of defaulting to "doc" type has been there from the beginning. Also if I understood well, main issue is adding new type prefix to link syntax. But does it / will it really happen so frequently ? Isn't it normal to create a new syntax in this case ? I think it's the main point to decide. That being said, I'm not sure about what would have been my feedback on syntax 2.0 before it was released :) Br, Jeremie
If you're keen on URIs (as I am, thanks for reminding me that in your email
btw :)), then I believe solution 4 is currently the best one.
I do not agree, if you're keen on URIs (and I am) Solution 1 is the
best
one, considering it will only affect a new syntax.
Thanks -Vincent
Thanks -Vincent
Thanks -Vincent
> Thanks, > > > > On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol < [email protected]
wrote: > >> Typos below. >> >> On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote: >> >>> Hi devs, >>> >>> Following this thread http://markmail.org/thread/vw3derowozijqalrit >> 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]] >>> >>> Examples: >>> * [[label>>doc:space.page]] >>> * [[label>>doc:wiki:space.page]] >>> * [[label>>path:/some/path]] >>> * [[label>>url:http://xwiki.org]] >>> * [[label>>user:evalica]] >>> * [[image:doc:wiki:[email protected]]] >>> * [[image:icon:someicon.png]] >>> >>> CONS: >>> * 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 >>> >>> Examples: >>> * [[label>>space.page]] or [[label>>doc:space.page]] >>> * [[label>>doc:wiki:space.page]] >>> * [[label>>>path:/some/path]] >> >> Should be [[label>>path:/some/path]] >> >>> * [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org ]] >> >> Should be [[label>>http://xwiki.org]] or [[label>>url: http://xwiki.org ]] >> >>> * [[label>>user:evalica]] >>> * [[image:doc:wiki:[email protected]]] >>> * [[image:icon:someicon.png]] >>> >>> PRO: >>> * Still easy to reference docs and images in the current wiki >>> * Close to current XWiki Syntax 2.1 >>> >>> CONS: >>> * 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. >>> >>> Examples: >>> * [[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"]] >> >> Should be [[label>>/some/path||type="path"]] >> >>> * [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org >> ||type="url"]] >> >> Should be [[label>>http://xwiki.org]] or [[label>> http://xwiki.org >> ||type="url"]] >> >> Thanks >> -Vincent >> >>> * [[label>>evalica||type="user"]] >>> * [[image:wiki:[email protected]]] or >> [[image:wiki:[email protected]||type="doc"]] >>> * [[image:someicon.png||type="icon"]] >>> >>> PRO: >>> * Still easy to reference docs >>> * Clear separation between subwiki and types >>> >>> CONS: >>> * Harder to write typed links >>> * Harder to write references in non xwiki/2.x syntax that would not >> support link parameters >>> >>> 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
Hi Jeremie, On May 2, 2013, at 10:46 AM, Jeremie BOUSQUET <[email protected]> wrote:
Hi all,
Le 2 mai 2013 10:16, "Denis Gervalle" <[email protected]> a écrit :
On Thu, May 2, 2013 at 8:36 AM, Vincent Massol <[email protected]> wrote:
On May 1, 2013, at 7:44 PM, Denis Gervalle <[email protected]> wrote:
Hi Vincent,
On Wed, May 1, 2013 at 7:48 AM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 11:21 PM, Denis Gervalle <[email protected]> wrote:
On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol <[email protected]> wrote:
> Hi Denis, > > On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote: > >> Hi devs, >> >> I have a very bad feeling with proposal 3, since it split the identifier, >> which makes its main part to loose its meaning when taken alone.
So
you
>> cannot comunicate the whole information easily on different channels > (think >> about copy/pasting such reference ?). This is also really verbose, > sometime >> it looks odd, and I found it to be complex from a user view point. >> Moreover, it could not be easily applied in other situation than links, >> while ressource identification is not limited to links (think about a > macro >> arguments ?, see MotionComposer macro that imitate image: for an > example). >> I know it is hard, but I am currently -1 for this proposal. >> >> If we look at large, what we really need and intend to achieve is to have >> an extensible syntax to identify ressources in XWiki. There is obviously > a >> ready made standardized syntax for such purpose: URN. Proposal 1 is > really >> near that specification (but too verbose for URL), but I agree with > Thomas >> that users will complains to be forced to use doc: everywhere. This is >> precisely why I made proposal 2, which will fully avoid that constrains > for >> user of single wikis (a lot of our user since XE was our mostly > downloaded >> distribution until now). >> >> So my vote are (sorry Vincent, but your request to have a truly single > vote >> is far too restrictive for this matter) >> +1 to really conform with a URN syntax as much as possible (remove the >> useless verbosity for URL). >> Proposal 1: +0 >> Proposal 2: +1 >> Proposal 3: -1 > > I also prefer URIs but my problem with solution 2 is having to prefix with > "doc:" for links to subwikis. This is pretty common.
I do not see why this is so annoying, we type http:// to start URLs, and I do not feel anyone has ever complains.
Yes but we don't type URLs often at all… We navigate by clicking. Imagine that every time you click on a link you had to instead type it, it would become quickly an issue…
Are we talking about navigating the wiki ? no, we are talking about editing hyperlinked documents, and you need to type the http:// as soon as you refer a document outside of your current server. Isn't that comparable to linking document in another wiki ?
I never ever type a URL! The only thing I do is copy paste URLs into documents…
In any case I think the main issue now is that 1) we have already offered a simpler way for users to type references to docs and 2) other wikis also propose this simpler way. Because of these 2 points, I'm not sure we can ever go back to making it harder to type references to docs...
I do not believe 1) is a good argument. First, if users prefer simpler syntax for subwiki's links compare to an extensible URI base syntax, they may simply continue to use syntax 2.1.
Bad argument because our goal is to move users to the latest syntax. The idea is that the latest syntax is better so, no, we cannot say to users that they should stay on the old syntax because it's nicer to type link refs… :)
Second, are there so much users with that preference, that also use multiple wikis with links between them ?
I think so, especially since we're making XEM the default (first step was virtual=1 by default, second step is to be able to create wikis by default).
While we do so, we do not deploy anything to create more than one wiki in our default flavor. And anyway, you said earlier that, mainly, solution 1) is bad because we have already provided a simpler solution. But using solution 2), it became only true for user of multiple wikis, that do link between those wikis, and that write those links by hand. I continue to think this is not the majority of our user currently.
Finally, we also provide other means to create documents then writing them using the xwiki syntax. We could also think about improving the
editor to
insert link/image more easily.
IMO this fails the concept of the wiki syntax which is to be extra simple and quick to use. So yes auto completion on linking/images is a good thing we need in the future but if we could also have a simple syntax at least for doc ref it would be good.
Well, using a doc: prefix for document reference is IMO far simpler than to remember that your reference are interpreted differently depending on an additional [] or any other tricky syntax.
So is the limitation of solution 2, imposed by the need for
flexibility,
so
blocker, as you seems to believe ?
- Solution 1 is nice because it's simple and coherent. But harder to write doc refs - Solution 2 is slightly less nice because not coherent. Simple to write doc refs but not cross wikis. - Solution 3 is less nice because it drops the concept of URIs which could prove useful in the future for other things in XWiki - Solution 4: is less nice than 1 because less coherent but at the same level of coherency as solution 2 and 3 and at the same time it doesn't have the drawback of solution 2. It's very close to solution 3 but keeping the concept of URIs.
IMO, you bias your conclusion by considering the multiwiki situation, with cross-linking as the default most used configuration.
Regarding point 2), I have not enough knowledge of other wikis, but it could be interesting to elaborate and see how and which of those other wikis really support easy interwiki links in there syntax, while providing at the same time support to different kind of ressources. I may be
wrong,
but I do not believe there will be numerous competitor with those criteria.
They don't have this concept. But we need to be careful, we cannot allow to be powerful and complex. We need to be powerful and simple. So making the main use case hard just for supporting other use cases that are used 5% of the time is not a good solution IMO.
Again, this is not fair, the main use case is link to local document, this is why I prefer solution 2) than 1).
So, solution 1 is not that bad, and solution 2 is only a feature over it, for those who use very basic feature. It compare to the omnibox of chrome that try to be clever and works
in
most
situations, but some still require you to enter the http:// prefix.
> I had proposed another solution in the other thread with a different > notation for proper URI notations. The idea was to use the shortcut > notation when you wanted to use document references for simplicity reasons > and use the proper syntax when you use proper URIs. > > Maybe that solution wasn't that bad. I'm putting it again here (with a > difference using [[[…]]] instead of >>> as I had said since that doesn't > work for images): > > * Shortcut notation for doc refs: [[label>>docref]] > * General notations for URIs: [[[label>>type:reference]]] > * Shortcut notation for images: [[image:docref]] > * General notation for URIs in images: [[[image:type:reference]]] > > It looks clunky at first but it isn't really since it represents what we > want: > * shortcut notation for doc URIs > * full notation for any URI > > WDYT? >
This again increase complexity (from a user POV) for very little benefit IMO. It look odd and again it cannot be applied anywhere, like in macros. So I see this fourth solution not much better than solution 3.
You're not very logical here :) You said you wanted URIs and solution 4 is about URIs while solution 3 isn't about URIs so you should prefer solution 4 over solution 3 normally :)
Have I said the contrary ? 4 is better than 3, but not that much IMO since we still have the split issue. 4 solve the problem for your current needs, but does not lead to a general way of identifying ressources in XWiki.
It does! It's like solution 1 actually. Again here it is (and again we could think of another syntax if we want, we don't have to use [[[…]]], we could use for example
[[[label>>type:reference]]]
Now just because we want to make it easy to type doc ref we also allow a **shortcut** (not the canonical way!):
[[label>>docref]]
Having a consistant solution is also important, and a good way to simplify the user experience.
Yes but only solution 1 provides this but at a big cost which I currently consider too large.
Of course since this is an important decision I'd like to know what others think too.
I would like other opinions as well, especially of how others see the cost of 1), and about which is the main use case ?
Personally I would prefer solution 2, because it has the least impact on main use case. I'm not sure about cross wiki or workspace links, because currently I have a mono wiki instance. But it seems logical to have much more intra wiki links. Also, I'm not sure about what would bring those new syntaxes to the user. I think they don't really care about coherence, as long as it's intuitive and most of all easy to type. If I remember well, the concept of defaulting to "doc" type has been there from the beginning.
Also if I understood well, main issue is adding new type prefix to link syntax. But does it / will it really happen so frequently ? Isn't it normal to create a new syntax in this case ? I think it's the main point to decide.
You're perfectly right. This is why I also proposed that solution in my first brainstorming email (solution 1): http://xwiki.markmail.org/thread/vw3derowozijqalr Note that the only issue is that even if we reserve some namespaces, users will still need to use the "doc:" syntax if they have a wiki named "user", "path", "icon", "attach", "doc", etc.. Thanks -Vincent
That being said, I'm not sure about what would have been my feedback on syntax 2.0 before it was released :)
Br, Jeremie
If you're keen on URIs (as I am, thanks for reminding me that in your email
btw :)), then I believe solution 4 is currently the best one.
I do not agree, if you're keen on URIs (and I am) Solution 1 is the
best
one, considering it will only affect a new syntax.
Thanks -Vincent
Thanks -Vincent
> Thanks > -Vincent > >> Thanks, >> >> >> >> On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol < [email protected]
> wrote: >> >>> Typos below. >>> >>> On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> > wrote: >>> >>>> Hi devs, >>>> >>>> Following this thread http://markmail.org/thread/vw3derowozijqalrit >>> 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]] >>>> >>>> Examples: >>>> * [[label>>doc:space.page]] >>>> * [[label>>doc:wiki:space.page]] >>>> * [[label>>path:/some/path]] >>>> * [[label>>url:http://xwiki.org]] >>>> * [[label>>user:evalica]] >>>> * [[image:doc:wiki:[email protected]]] >>>> * [[image:icon:someicon.png]] >>>> >>>> CONS: >>>> * 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 >>>> >>>> Examples: >>>> * [[label>>space.page]] or [[label>>doc:space.page]] >>>> * [[label>>doc:wiki:space.page]] >>>> * [[label>>>path:/some/path]] >>> >>> Should be [[label>>path:/some/path]] >>> >>>> * [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org ]] >>> >>> Should be [[label>>http://xwiki.org]] or [[label>>url: http://xwiki.org > ]] >>> >>>> * [[label>>user:evalica]] >>>> * [[image:doc:wiki:[email protected]]] >>>> * [[image:icon:someicon.png]] >>>> >>>> PRO: >>>> * Still easy to reference docs and images in the current wiki >>>> * Close to current XWiki Syntax 2.1 >>>> >>>> CONS: >>>> * 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. >>>> >>>> Examples: >>>> * [[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"]] >>> >>> Should be [[label>>/some/path||type="path"]] >>> >>>> * [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org >>> ||type="url"]] >>> >>> Should be [[label>>http://xwiki.org]] or [[label>> http://xwiki.org >>> ||type="url"]] >>> >>> Thanks >>> -Vincent >>> >>>> * [[label>>evalica||type="user"]] >>>> * [[image:wiki:[email protected]]] or >>> [[image:wiki:[email protected]||type="doc"]] >>>> * [[image:someicon.png||type="icon"]] >>>> >>>> PRO: >>>> * Still easy to reference docs >>>> * Clear separation between subwiki and types >>>> >>>> CONS: >>>> * Harder to write typed links >>>> * Harder to write references in non xwiki/2.x syntax that would not >>> support link parameters >>>> >>>> Thanks >>>> -Vincent
On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Apr 30, 2013, at 1:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
I also prefer URIs but my problem with solution 2 is having to prefix with "doc:" for links to subwikis. This is pretty common.
I had proposed another solution in the other thread with a different notation for proper URI notations. The idea was to use the shortcut notation when you wanted to use document references for simplicity reasons and use the proper syntax when you use proper URIs.
Maybe that solution wasn't that bad. I'm putting it again here (with a difference using [[[…]]] instead of >>> as I had said since that doesn't work for images):
* Shortcut notation for doc refs: [[label>>docref]] * General notations for URIs: [[[label>>type:reference]]] * Shortcut notation for images: [[image:docref]] * General notation for URIs in images: [[[image:type:reference]]]
It looks clunky at first but it isn't really since it represents what we want: * shortcut notation for doc URIs * full notation for any URI
I don't like too much having two different syntaxes for links and I agree with Denis that it keep the choice very close to wiki syntax. It's also the hardest proposal to implement. IMO if the main reason to defeat 3 is that we need full reference outside of wiki syntax (and I think it is) then we need to forget about wiki syntax solutions and only think about the reference itself.
WDYT?
Thanks -Vincent
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On Tue, Apr 30, 2013 at 1:26 PM, Denis Gervalle <[email protected]> wrote:
Hi devs,
I have a very bad feeling with proposal 3, since it split the identifier, which makes its main part to loose its meaning when taken alone. So you cannot comunicate the whole information easily on different channels (think about copy/pasting such reference ?). This is also really verbose, sometime it looks odd, and I found it to be complex from a user view point. Moreover, it could not be easily applied in other situation than links, while ressource identification is not limited to links (think about a macro arguments ?, see MotionComposer macro that imitate image: for an example). I know it is hard, but I am currently -1 for this proposal.
You are right to vote -1 when it worth it and I agree with your on that one so I change my vote to 2).
If we look at large, what we really need and intend to achieve is to have an extensible syntax to identify ressources in XWiki. There is obviously a ready made standardized syntax for such purpose: URN. Proposal 1 is really near that specification (but too verbose for URL), but I agree with Thomas that users will complains to be forced to use doc: everywhere. This is precisely why I made proposal 2, which will fully avoid that constrains for user of single wikis (a lot of our user since XE was our mostly downloaded distribution until now).
So my vote are (sorry Vincent, but your request to have a truly single vote is far too restrictive for this matter) +1 to really conform with a URN syntax as much as possible (remove the useless verbosity for URL). Proposal 1: +0 Proposal 2: +1 Proposal 3: -1
Thanks,
On Tue, Apr 30, 2013 at 12:30 PM, Vincent Massol <[email protected]> wrote:
Typos below.
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[label>>space.page]] or [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>>path:/some/path]]
Should be [[label>>path:/some/path]]
* [[label>>http://xwiki.org]] or [[label>>>url:http://xwiki.org]]
Should be [[label>>http://xwiki.org]] or [[label>>url:http://xwiki.org]]
* [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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"]]
Should be [[label>>/some/path||type="path"]]
* [[label>>http://xwiki.org]] or [[label>>>http://xwiki.org ||type="url"]]
Should be [[label>>http://xwiki.org]] or [[label>>http://xwiki.org ||type="url"]]
Thanks -Vincent
* [[label>>evalica||type="user"]] * [[image:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
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
-- Thomas Mortagne
Hi everyone, After listening to all discussions and thinking more about it (and talking to Thomas), I see only 2 good solutions now: Solution A ======== * Don't do anything, i.e. accept that when we add a new prefix handler we break users who use the short notation for wikis named after the prefix. We would put in the release notes and in the syntax guide that users should use the full notation in case they have a wiki named "user" for example when we add the "user" prefix (similar to what we say now for all other prefixes: "doc", "attach", "url", "mailto", etc). * IMO this solution is better than the proposed solution 2, i.e. usage of [[label>>doc:extension.Extension.My Macro]] for links to multiwikis which is really too long and too much a change for users Solution B ======== * Have a shortcut notation (same as with xwiki/2.0 syntax): [[label>>ref]] where ref can be a ref to a doc or to a URL * Canonical notation: [[[label>>prefix:reference]]] for links and [[[image:…]]] for images * This is the only real solution IMO that allows both: ** extensibility without breaking existing pages ** still preserve the ability to easily and quickly reference documents * We already triple characters in our syntax: ((( and {{{. So it's not something new to add [[[ For me it's logical to have a canonical syntax for links/images and a simplified one for the main use case of a wiki, which is to create links to documents. This is so much the core of a wiki that having a simple syntax is a must have. Thanks -Vincent On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[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:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks -Vincent
On May 6, 2013, at 9:40 AM, Vincent Massol <[email protected]> wrote:
Hi everyone,
After listening to all discussions and thinking more about it (and talking to Thomas), I see only 2 good solutions now:
Just to be clear: the 2 solutions below are my view of the problem, not Thomas's. Thomas just proposed solution A but without saying if he thinks it's the best solution or not. Thanks -Vincent
Solution A ========
* Don't do anything, i.e. accept that when we add a new prefix handler we break users who use the short notation for wikis named after the prefix. We would put in the release notes and in the syntax guide that users should use the full notation in case they have a wiki named "user" for example when we add the "user" prefix (similar to what we say now for all other prefixes: "doc", "attach", "url", "mailto", etc). * IMO this solution is better than the proposed solution 2, i.e. usage of [[label>>doc:extension.Extension.My Macro]] for links to multiwikis which is really too long and too much a change for users
Solution B ========
* Have a shortcut notation (same as with xwiki/2.0 syntax): [[label>>ref]] where ref can be a ref to a doc or to a URL * Canonical notation: [[[label>>prefix:reference]]] for links and [[[image:…]]] for images * This is the only real solution IMO that allows both: ** extensibility without breaking existing pages ** still preserve the ability to easily and quickly reference documents * We already triple characters in our syntax: ((( and {{{. So it's not something new to add [[[
For me it's logical to have a canonical syntax for links/images and a simplified one for the main use case of a wiki, which is to create links to documents. This is so much the core of a wiki that having a simple syntax is a must have.
Thanks -Vincent
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[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:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks -Vincent
Hi Vincent, I do not see the real benefit of B, since as I have already mention, IMO, a reference should be resolvable by itself outside of a given syntactical context. Moreover, the canonical reference could be used in A, on a voluntary basis, for those wanting to ensure unbreakable inter-wiki references (which is solution 2 without enforcement). So, I am still +1 for 2, +0 for A (and 1), and -1 for B (and 3) due to the context issue. However, I might reconsider my vote on B if many show their interest for it (more easily than I would have for 3). PS: If we adopt A, it could be worth to have a configuration property to deactivate some prefixes, allowing some legacy migration more easily. On Mon, May 6, 2013 at 9:40 AM, Vincent Massol <[email protected]> wrote:
Hi everyone,
After listening to all discussions and thinking more about it (and talking to Thomas), I see only 2 good solutions now:
Solution A ========
* Don't do anything, i.e. accept that when we add a new prefix handler we break users who use the short notation for wikis named after the prefix. We would put in the release notes and in the syntax guide that users should use the full notation in case they have a wiki named "user" for example when we add the "user" prefix (similar to what we say now for all other prefixes: "doc", "attach", "url", "mailto", etc). * IMO this solution is better than the proposed solution 2, i.e. usage of [[label>>doc:extension.Extension.My Macro]] for links to multiwikis which is really too long and too much a change for users
Solution B ========
* Have a shortcut notation (same as with xwiki/2.0 syntax): [[label>>ref]] where ref can be a ref to a doc or to a URL * Canonical notation: [[[label>>prefix:reference]]] for links and [[[image:…]]] for images * This is the only real solution IMO that allows both: ** extensibility without breaking existing pages ** still preserve the ability to easily and quickly reference documents * We already triple characters in our syntax: ((( and {{{. So it's not something new to add [[[
For me it's logical to have a canonical syntax for links/images and a simplified one for the main use case of a wiki, which is to create links to documents. This is so much the core of a wiki that having a simple syntax is a must have.
Thanks -Vincent
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[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:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
I still prefer solution 2. I'm fine with A. Regarding B, I think it is technically a very good solution but it makes the wiki syntax more cryptic. The first wiki syntaxes were simple and natural. You could understand constructs like: * item * item _underline_ , /italics/ , -strikethrough- without even reading the syntax help. I don't think many will understand the difference between [[[ and [[ links without reading the XWiki syntax help. While when looking at [[label>>doc:foo:Bar.Page]] you may understand right away that it's a link to a document (in a different wiki). Thanks, Marius On Mon, May 6, 2013 at 3:55 PM, Denis Gervalle <[email protected]> wrote:
Hi Vincent,
I do not see the real benefit of B, since as I have already mention, IMO, a reference should be resolvable by itself outside of a given syntactical context. Moreover, the canonical reference could be used in A, on a voluntary basis, for those wanting to ensure unbreakable inter-wiki references (which is solution 2 without enforcement).
So, I am still +1 for 2, +0 for A (and 1), and -1 for B (and 3) due to the context issue. However, I might reconsider my vote on B if many show their interest for it (more easily than I would have for 3).
PS: If we adopt A, it could be worth to have a configuration property to deactivate some prefixes, allowing some legacy migration more easily.
On Mon, May 6, 2013 at 9:40 AM, Vincent Massol <[email protected]> wrote:
Hi everyone,
After listening to all discussions and thinking more about it (and talking to Thomas), I see only 2 good solutions now:
Solution A ========
* Don't do anything, i.e. accept that when we add a new prefix handler we break users who use the short notation for wikis named after the prefix. We would put in the release notes and in the syntax guide that users should use the full notation in case they have a wiki named "user" for example when we add the "user" prefix (similar to what we say now for all other prefixes: "doc", "attach", "url", "mailto", etc). * IMO this solution is better than the proposed solution 2, i.e. usage of [[label>>doc:extension.Extension.My Macro]] for links to multiwikis which is really too long and too much a change for users
Solution B ========
* Have a shortcut notation (same as with xwiki/2.0 syntax): [[label>>ref]] where ref can be a ref to a doc or to a URL * Canonical notation: [[[label>>prefix:reference]]] for links and [[[image:…]]] for images * This is the only real solution IMO that allows both: ** extensibility without breaking existing pages ** still preserve the ability to easily and quickly reference documents * We already triple characters in our syntax: ((( and {{{. So it's not something new to add [[[
For me it's logical to have a canonical syntax for links/images and a simplified one for the main use case of a wiki, which is to create links to documents. This is so much the core of a wiki that having a simple syntax is a must have.
Thanks -Vincent
On Apr 30, 2013, at 11:02 AM, Vincent Massol <[email protected]> wrote:
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]]
Examples: * [[label>>doc:space.page]] * [[label>>doc:wiki:space.page]] * [[label>>path:/some/path]] * [[label>>url:http://xwiki.org]] * [[label>>user:evalica]] * [[image:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
CONS: * 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
Examples: * [[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:doc:wiki:[email protected]]] * [[image:icon:someicon.png]]
PRO: * Still easy to reference docs and images in the current wiki * Close to current XWiki Syntax 2.1
CONS: * 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.
Examples: * [[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:wiki:[email protected]]] or [[image:wiki:[email protected]||type="doc"]] * [[image:someicon.png||type="icon"]]
PRO: * Still easy to reference docs * Clear separation between subwiki and types
CONS: * Harder to write typed links * Harder to write references in non xwiki/2.x syntax that would not support link parameters
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
participants (7)
-
Denis Gervalle -
Ecaterina Moraru (Valica) -
Jeremie BOUSQUET -
Marius Dumitru Florea -
Raluca Stavro -
Thomas Mortagne -
Vincent Massol