Re: [xwiki-devs] [VOTE] New Link and Image syntax for XWiki Syntax 2.2

2 May 2013

Hi Jeremie,

On May 2, 2013, at 10:46 AM, Jeremie BOUSQUET &lt;jeremie.bousquet(a)gmail.com&gt; wrote:

...
  Hi all,

 Le 2 mai 2013 10:16, "Denis Gervalle" &lt;dgl(a)softec.lu&gt; a écrit :

 On Thu, May 2, 2013 at 8:36 AM, Vincent Massol &lt;vincent(a)massol.net&gt; wrote:

> 
> On May 1, 2013, at 7:44 PM, Denis Gervalle &lt;dgl(a)softec.lu&gt; wrote:
> 
>> Hi Vincent,
>> 
>> On Wed, May 1, 2013 at 7:48 AM, Vincent Massol &lt;vincent(a)massol.net&gt;
> wrote:
>> 
>>> Hi Denis,
>>> 
>>> On Apr 30, 2013, at 11:21 PM, Denis Gervalle &lt;dgl(a)softec.lu&gt; wrote:
>>> 
>>>> On Tue, Apr 30, 2013 at 7:58 PM, Vincent Massol
&lt;vincent(a)massol.net&gt;
>>> wrote:
>>>> 
>>>>> Hi Denis,
>>>>> 
>>>>> On Apr 30, 2013, at 1:26 PM, Denis Gervalle &lt;dgl(a)softec.lu&gt;
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 < 
vincent(a)massol.net
 >> 
>>>>> wrote:
>>>>>> 
>>>>>>> Typos below.
>>>>>>> 
>>>>>>> On Apr 30, 2013, at 11:02 AM, Vincent Massol
&lt;vincent(a)massol.net&gt;
>>>>> 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: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]]
>>>>>>> 
>>>>>>> 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: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"]]
>>>>>>> 
>>>>>>> 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: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 

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

Re: [xwiki-devs] [VOTE] New Link and Image syntax for XWiki Syntax 2.2