6 May
2013
6 May
'13
9:40 a.m.
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 <vincent(a)massol.net> 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:space.page@image.png]]
* [[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:space.page@image.png]]
* [[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:space.page@image.png]] or
[[image:wiki:space.page@image.png||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