New thread started, please consider this one closed and use the new thread entitled "[VOTE] New Link and Image syntax for XWiki Syntax 2.2"
Thanks -Vincent On Apr 30, 2013, at 10:22 AM, Vincent Massol <[email protected]> wrote: > Hi Thomas, > > On Apr 30, 2013, at 9:50 AM, Thomas Mortagne <[email protected]> > wrote: > >> On Mon, Apr 29, 2013 at 6:56 PM, Vincent Massol <[email protected]> wrote: >>> >>> On Apr 29, 2013, at 6:13 PM, Thomas Mortagne <[email protected]> >>> wrote: >>> >>>> On Mon, Apr 29, 2013 at 12:27 AM, Thomas Mortagne >>>> <[email protected]> wrote: >>>>> On Sun, Apr 28, 2013 at 8:27 PM, Vincent Massol <[email protected]> >>>>> wrote: >>>>>> >>>>>> On Apr 28, 2013, at 6:43 PM, Thomas Mortagne <[email protected]> >>>>>> wrote: >>>>>> >>>>>>> On Fri, Apr 26, 2013 at 10:11 AM, Vincent Massol <[email protected]> >>>>>>> wrote: >>>>>>>> Hi devs, >>>>>>>> >>>>>>>> I've started implementing XRENDERING-290 (I've spent already 1 day on >>>>>>>> it and have most of it done) but as I progressed I've realized we need >>>>>>>> to decide on something. >>>>>>>> >>>>>>>> It's an interesting problem! :) >>>>>>>> >>>>>>>> So the issues asks for support a "user" prefix in links to link to >>>>>>>> user profiles such as in: [[label>>user:evalica]] >>>>>>>> >>>>>>>> Explanation of Problem >>>>>>>> ================== >>>>>>>> >>>>>>>> I started with implementing a new Reference Type Parser to add support >>>>>>>> for the "user" prefix. I soon realized that we cannot implement this >>>>>>>> in XWiki Syntax 2.1 since it means if a user currently has >>>>>>>> [[label>>user:evalica]] it means pointing to the "user" wiki and to >>>>>>>> the page named "evalica". >>>>>>> >>>>>>> No this is not what this reference mean, this reference mean current >>>>>>> wiki, current space and page names "user:evalica". >>>>>> >>>>>> Indeed, good remark :) >>>>>> >>>>>> Now I don't think it changes the rest of the email. For example you >>>>>> could imagine a user named "vincent.massol" and the reference would be: >>>>>> "user:vincent.massol"… :) >>>>> >>>>> Right now a user with a dot would not work well but nothing prevent >>>>> having a document named "user:evalica" so yes it does not change the >>>>> issue. >>>>> >>>>>> >>>>>> Thanks >>>>>> -Vincent >>>>>> >>>>>>>> Thus we need to add this in a new syntax only (i.e. XWiki Syntax 2.2). >>>>>>>> >>>>>>>> Now the problem is that currently Reference Type Parsers are >>>>>>>> components and implementing a new component means it's going to be >>>>>>>> available to XWiki Syntax 2.1. So I spent a substantial amount of time >>>>>>>> to allow syntaxes to specifically specify the list of prefixes that >>>>>>>> they support. This is done, I just need to push it. >>>>>>>> >>>>>>>> Now this all looked good till I started implementing the >>>>>>>> UserXHTMLLinkTypeRenderer… I realized that I would need to be able to >>>>>>>> transform a String (supposed to represent a username) into a User >>>>>>>> reference and even though we don't have an API for this ATM this would >>>>>>>> normally mean to depend on the Platform User module… which is a big no >>>>>>>> go since Rendering cannot depend on Platform. >>>>>>>> >>>>>>>> Side Note:I also realized that XRENDERING-290 could also be extended >>>>>>>> to support displaying the user's avatar with image:user:evalica. This >>>>>>>> is currently done with the {{useravatar}} macro (which is also wrongly >>>>>>>> located in Rendering and should be in platform for the reason >>>>>>>> explained!!). >>>>>>>> >>>>>>>> So I thought I could just have the UserResourceReferenceTypeParser and >>>>>>>> UserXHTMLLinkTypeRenderer classes implemented in the Platform User >>>>>>>> module but that still meant that the XWiki Syntax 2.2 needs to reserve >>>>>>>> the "user" prefix. >>>>>>>> >>>>>>>> Then I realized that any time we will want to add support for a new >>>>>>>> prefix we would need to introduce a new Syntax version which is a huge >>>>>>>> PITA and a pity. >>>>>>>> >>>>>>>> I thought about several solutions. >>>>>>>> >>>>>>>> Solution 1 >>>>>>>> ======== >>>>>>>> >>>>>>>> * Consider that each syntax can reserve prefix type namespaces and >>>>>>>> this just means that if the user wants to write a link to a document a >>>>>>>> wiki named after one of these prefixes then he needs to use the full >>>>>>>> format: [[label>>doc:<wikiname>:….]] >>>>>>>> * Thus XWiki Syntax 2.2 would just add the "user" prefix to the >>>>>>>> reserved list of prefix type namespaces. >>>>>>>> >>>>>>>> PRO: >>>>>>>> * I have this code ready to be pushed on my computer >>>>>>>> * Doesn't change the current XWiki Syntax notation >>>>>>>> >>>>>>>> CONS: >>>>>>>> * Requires a new syntax whenever a new type parser is added (after a >>>>>>>> syntax has been released as final) >>>>>>>> * Creates a relationship between the syntax and implementations (the >>>>>>>> User module will provide an impl. for supporting the reserved "user" >>>>>>>> namespace). >>>> >>>> -1, does not make any sense to me. Link type is supposed to be >>>> expendable and is not supposed to be finite list of types. >>>> >>>>>>>> >>>>>>>> Solution 2 >>>>>>>> ======== >>>>>>>> >>>>>>>> * Don't implement support for linking to users using resource types >>>>>>>> and add a {{userlink}} macro and move both macros in platform. >>>>>>>> >>>>>>>> PRO: >>>>>>>> * Simple, no need for a new XWiki Syntax >>>>>>>> >>>>>>>> CONS: >>>>>>>> * Not integrated in the syntax >>>>>>>> * Not very logical since as a user you would want to write: >>>>>>>> [[label>>user:evalica]] >>>> >>>> This "solution" is the same as not doing anything. I don't really care >>>> about having user reference but we will need to introduce new link >>>> types that's for sure so we will have to find a solution to make link >>>> type syntax stronger at some point. >>>> >>>>>>>> >>>>>>>> Solution 3 >>>>>>>> ======== >>>>>>>> >>>>>>>> Force XWiki Syntax 2.2 to *ALWAYS* use the full form when creating a >>>>>>>> link, i.e. all links to doc would need to be written: >>>>>>>> [[label>>doc:reference]] >>>>>>>> >>>>>>>> PRO: >>>>>>>> * Solves all future needs for new reference types and makes the syntax >>>>>>>> extensible for this. >>>>>>>> >>>>>>>> CONS: >>>>>>>> * Harder to write links to documents and users will need to get used >>>>>>>> to it >>>>>>>> >>>>>>>> Solution 4 >>>>>>>> ======== >>>>>>>> >>>>>>>> Invent a new syntax when you wish to write links using a type prefix >>>>>>>> and keep the current link syntax for references to documents: >>>>>>>> * Ref to a doc: [[label>>docref]] (e.g. [[label>>xwiki:Main.WebHome]]) >>>>>>>> * Ref to anything but using the type prefix: >>>>>>>> [[label>>>prefix:reference]] (e.g. [[label>>>doc:doc:Main.WebHome]]: >>>>>>>> link to a wiki named "doc") >>>>>>>> >>>>>>>> PRO: >>>>>>>> * Still easy to make refs to documents >>>>>>>> * Makes the syntax extensible by allowing new types to be added >>>>>>>> >>>>>>>> CONS: >>>>>>>> * Changes the syntaxes since it means introducing a new link notation >>>>>>>> [[label>>>ref]]. Also means that references to docs cannot start with >>>>>>>> ">" anymore (but that's not a real issue IMO) >>>>>>>> * A bit more complex to implement obviously since it needs a change to >>>>>>>> the javacc parser >>>> >>>> Solution 5 >>>> ======== >>>> >>>> Separate the type from the first level type and keep the same fallack >>>> we have now when the type is not explicitely provide. >>>> >>>> Here are some example: >>>> * [[label>>docref]] >>>> * [[label>>http://someexternalurl]] >>>> * [[label>>docref||type="doc"]] >>>> * [[label>>/bin/view/Space/Page||type="path"]] >>> >>> Just to be sure we understand fully, you're proposing to remove the support >>> for prefixes as part of the reference, right? >>> >>> The fallback would only be for URL and if no URL is found then it would be >>> considered as a doc reference. >>> >>> So for example the following: [[label>>wiki:space.page]] would become a >>> link to a document named "wiki:space.page" and not a link to a document in >>> the wiki wiki, space space and page page, right? >> >> I tough "does not break all the current document ref without explicit >> type" was clear. > > Thomas, be sure that if I ask it's because I didn't understand something, > that's all… > > Since I'm proposing to do the implementation myself I need to be sure I > understand what everyone is proposing. And I'm glad I asked here because I > didn't get it the first time. > >> Again all I propose is to not have the type in the >> reference anymore but in the link parameter, >> [[label>>wiki:space.page]] will stay a link to wiki wiki, space space >> and page page before you did not provided a type and it's not a URL. >> The behaviour of not typed reference won't change a bit from the >> current behaviour, just think about xwiki/2.0. > > ok, got it now, thanks! > >>>> PROS: >>>> * does not break all the current document ref without explicit type >>>> * makes clear what is the type of the reference and what is the actual type >>>> >>>> CONS: >>>> * change the syntax of explicitly typed links (but not really bigger than >>>> 4) >>>> * harder to type reference in non xwiki/2.x syntax that would not >>>> support link parameters >>> >>> Other CONs: >>> * Makes it longer/harder to create a link. Compare: >>> [[label>>evalica||type="user"]] to [[label>>user:evalica]] >>> * Makes it harder to read (see example from previous line) >>> >>> Thanks >>> -Vincent >>> >>> PS: You still didn't say which one you prefer. Since you added Solution 5, >>> should we assume that it's your preference so far? :) >> >> You did not read my mail fully. > > For some reason you seem to be thinking I'm having some fun not reading your > email. Well just so that you know: I'm not… :) I try my best reading > everything and if I ask stuff it's because I couldn't find the answer or it > wasn't clear to me… > > In any case, no need to answer now since I'm going to send a new mail with a > VOTE with all options since I believe a new syntax is really important and > I'd like to make sure we all agree. > > Thanks > -Vincent > >>>>>>>> >>>>>>>> Conclusion >>>>>>>> ========== >>>>>>>> >>>>>>>> My POV: >>>>>>>> * The more correct solution is solution 3 but it makes harder to write >>>>>>>> links to documents so I believe that's going to be a problem since >>>>>>>> it's the main use case. >>>>>>>> * Solution 1 is already implemented on my computer and I just need to >>>>>>>> make a push to have it so the simplest for me. I think it could be >>>>>>>> acceptable since we don't introduce new type parsers all the time. But >>>>>>>> it's not perfect obviously. >>>>>>>> * Solution 4 is the most tempting for me even though it's more work. >>>>>>>> I've suggested ">>>" but we could imagine a different notation. Other >>>>>>>> ideas include using [[label>>doc:doc:Main.WebHome||typed="true"]] (ie >>>>>>>> setting a "type" param to mention that it's referring to a typed >>>>>>>> reference). It has the advantage of not requiring changes to the >>>>>>>> javacc parser but it has more chars to type for the user and is thus >>>>>>>> more complex for the user. >>>>>>>> >>>>>>>> Do you have an opinion? WDYT? Should I push what I have for now and >>>>>>>> make changes later? >>>>>>>> >>>>>>>> Thanks >>>>>>>> -Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
