[Need proposal] How to show "conflicting" macro parameters

classic Classic list List threaded Threaded
20 messages Options
Reply | Threaded
Open this post in threaded view
|

[Need proposal] How to show "conflicting" macro parameters

Thomas Mortagne
Administrator
Hi xwikiers,

In the contact of bringing new Page concept (OK 7.4 is starting to get
old) to the API and macros too we decided (1) to introduce a "page"
shortcut property (even if we keep the reference/type for other
types).

While it's nicer for wiki syntax, one issue is that on WYSIWYG macros
UI side, which display all properties, it means ending up with
conflicting parameters that needs to be displayed as such.

I don't really have much clue on how best to display this so I'm
searching for ideas :)

Then I will add in the macro descriptor what's required for whatever
UI we want to build (group and sub groups of properties, etc.).

1: http://design.xwiki.org/xwiki/bin/view/Proposal/DeprecatingSpaceAndSpaceReference#HMacros

Thanks,
--
Thomas Mortagnes
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Marius Dumitru Florea
For groups of parameters we could use tabs:

----------8<----------
Param 1
[input]

Param 2 | Param 3 | Param 4 <--- a group of 3 parameters displayed using
tabs (we take into account only the value of the parameter from the active
tab)
[input for param 2]

Param 5
[input]
---------->8----------

But if you want to support subgroups of parameters also then it becomes
more complicated.

Thanks,
Marius

On Mon, Jul 2, 2018 at 11:52 AM, Thomas Mortagne <[hidden email]>
wrote:

> Hi xwikiers,
>
> In the contact of bringing new Page concept (OK 7.4 is starting to get
> old) to the API and macros too we decided (1) to introduce a "page"
> shortcut property (even if we keep the reference/type for other
> types).
>
> While it's nicer for wiki syntax, one issue is that on WYSIWYG macros
> UI side, which display all properties, it means ending up with
> conflicting parameters that needs to be displayed as such.
>
> I don't really have much clue on how best to display this so I'm
> searching for ideas :)
>
> Then I will add in the macro descriptor what's required for whatever
> UI we want to build (group and sub groups of properties, etc.).
>
> 1: http://design.xwiki.org/xwiki/bin/view/Proposal/
> DeprecatingSpaceAndSpaceReference#HMacros
>
> Thanks,
> --
> Thomas Mortagnes
>
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Thomas Mortagne
Administrator
Here are more details on the actual use case we need to support:

In include/Display macro either you set:

* "reference" and "type" (which default to DOCUMENT)
* or you set "page"


On Wed, Jul 4, 2018 at 10:57 AM, Marius Dumitru Florea
<[hidden email]> wrote:

> For groups of parameters we could use tabs:
>
> ----------8<----------
> Param 1
> [input]
>
> Param 2 | Param 3 | Param 4 <--- a group of 3 parameters displayed using
> tabs (we take into account only the value of the parameter from the active
> tab)
> [input for param 2]
>
> Param 5
> [input]
> ---------->8----------
>
> But if you want to support subgroups of parameters also then it becomes
> more complicated.
>
> Thanks,
> Marius
>
> On Mon, Jul 2, 2018 at 11:52 AM, Thomas Mortagne <[hidden email]>
> wrote:
>
>> Hi xwikiers,
>>
>> In the contact of bringing new Page concept (OK 7.4 is starting to get
>> old) to the API and macros too we decided (1) to introduce a "page"
>> shortcut property (even if we keep the reference/type for other
>> types).
>>
>> While it's nicer for wiki syntax, one issue is that on WYSIWYG macros
>> UI side, which display all properties, it means ending up with
>> conflicting parameters that needs to be displayed as such.
>>
>> I don't really have much clue on how best to display this so I'm
>> searching for ideas :)
>>
>> Then I will add in the macro descriptor what's required for whatever
>> UI we want to build (group and sub groups of properties, etc.).
>>
>> 1: http://design.xwiki.org/xwiki/bin/view/Proposal/
>> DeprecatingSpaceAndSpaceReference#HMacros
>>
>> Thanks,
>> --
>> Thomas Mortagnes
>>



--
Thomas Mortagne
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

vmassol
Administrator


> On 4 Jul 2018, at 12:07, Thomas Mortagne <[hidden email]> wrote:
>
> Here are more details on the actual use case we need to support:
>
> In include/Display macro either you set:
>
> * "reference" and "type" (which default to DOCUMENT)
> * or you set “page"

Globally I think we need to add 3 concepts to macro parameter descriptor:

1) The concept of “deprecated” parameter. For example for “document” in the include macro.
2) The concept of aliases or groups, i.e the ability to list parameters that are mutually exclusive. Example: reference + type vs page for display/include macros. This would mean that in the Macro Dialog UI if you select one of those the other gets unselected/cleared out (you cannot have mutually exclusive params have values).
3) The concept of Advanced parameters. For example, we should put reference + type as advanced parameters so that they are not shown to the user by default (and so that the page parameter is more highlighted). Users would need to click on Advanced to see advanced parameters. I think we’re doing something automatic today (I don’t remember the details) to try to hide some parameters but we should probably review this.

WDYT?

Thanks
-Vincent



>
>
> On Wed, Jul 4, 2018 at 10:57 AM, Marius Dumitru Florea
> <[hidden email]> wrote:
>> For groups of parameters we could use tabs:
>>
>> ----------8<----------
>> Param 1
>> [input]
>>
>> Param 2 | Param 3 | Param 4 <--- a group of 3 parameters displayed using
>> tabs (we take into account only the value of the parameter from the active
>> tab)
>> [input for param 2]
>>
>> Param 5
>> [input]
>> ---------->8----------
>>
>> But if you want to support subgroups of parameters also then it becomes
>> more complicated.
>>
>> Thanks,
>> Marius
>>
>> On Mon, Jul 2, 2018 at 11:52 AM, Thomas Mortagne <[hidden email]>
>> wrote:
>>
>>> Hi xwikiers,
>>>
>>> In the contact of bringing new Page concept (OK 7.4 is starting to get
>>> old) to the API and macros too we decided (1) to introduce a "page"
>>> shortcut property (even if we keep the reference/type for other
>>> types).
>>>
>>> While it's nicer for wiki syntax, one issue is that on WYSIWYG macros
>>> UI side, which display all properties, it means ending up with
>>> conflicting parameters that needs to be displayed as such.
>>>
>>> I don't really have much clue on how best to display this so I'm
>>> searching for ideas :)
>>>
>>> Then I will add in the macro descriptor what's required for whatever
>>> UI we want to build (group and sub groups of properties, etc.).
>>>
>>> 1: http://design.xwiki.org/xwiki/bin/view/Proposal/
>>> DeprecatingSpaceAndSpaceReference#HMacros
>>>
>>> Thanks,
>>> --
>>> Thomas Mortagnes
>>>
>
>
>
> --
> Thomas Mortagne

Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

vmassol
Administrator


> On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]> wrote:
>
>
>
>> On 4 Jul 2018, at 12:07, Thomas Mortagne <[hidden email]> wrote:
>>
>> Here are more details on the actual use case we need to support:
>>
>> In include/Display macro either you set:
>>
>> * "reference" and "type" (which default to DOCUMENT)
>> * or you set “page"
>
> Globally I think we need to add 3 concepts to macro parameter descriptor:
>
> 1) The concept of “deprecated” parameter. For example for “document” in the include macro.
> 2) The concept of aliases or groups, i.e the ability to list parameters that are mutually exclusive. Example: reference + type vs page for display/include macros. This would mean that in the Macro Dialog UI if you select one of those the other gets unselected/cleared out (you cannot have mutually exclusive params have values).
> 3) The concept of Advanced parameters. For example, we should put reference + type as advanced parameters so that they are not shown to the user by default (and so that the page parameter is more highlighted). Users would need to click on Advanced to see advanced parameters. I think we’re doing something automatic today (I don’t remember the details) to try to hide some parameters but we should probably review this.
>
> WDYT?

Ping!

Do we agree about this? If we do we can then create jira issue about it and take it for implementation.

Thanks
-Vincent

>
> Thanks
> -Vincent
>
>
>
>>
>>
>> On Wed, Jul 4, 2018 at 10:57 AM, Marius Dumitru Florea
>> <[hidden email]> wrote:
>>> For groups of parameters we could use tabs:
>>>
>>> ----------8<----------
>>> Param 1
>>> [input]
>>>
>>> Param 2 | Param 3 | Param 4 <--- a group of 3 parameters displayed using
>>> tabs (we take into account only the value of the parameter from the active
>>> tab)
>>> [input for param 2]
>>>
>>> Param 5
>>> [input]
>>> ---------->8----------
>>>
>>> But if you want to support subgroups of parameters also then it becomes
>>> more complicated.
>>>
>>> Thanks,
>>> Marius
>>>
>>> On Mon, Jul 2, 2018 at 11:52 AM, Thomas Mortagne <[hidden email]>
>>> wrote:
>>>
>>>> Hi xwikiers,
>>>>
>>>> In the contact of bringing new Page concept (OK 7.4 is starting to get
>>>> old) to the API and macros too we decided (1) to introduce a "page"
>>>> shortcut property (even if we keep the reference/type for other
>>>> types).
>>>>
>>>> While it's nicer for wiki syntax, one issue is that on WYSIWYG macros
>>>> UI side, which display all properties, it means ending up with
>>>> conflicting parameters that needs to be displayed as such.
>>>>
>>>> I don't really have much clue on how best to display this so I'm
>>>> searching for ideas :)
>>>>
>>>> Then I will add in the macro descriptor what's required for whatever
>>>> UI we want to build (group and sub groups of properties, etc.).
>>>>
>>>> 1: http://design.xwiki.org/xwiki/bin/view/Proposal/
>>>> DeprecatingSpaceAndSpaceReference#HMacros
>>>>
>>>> Thanks,
>>>> --
>>>> Thomas Mortagnes
>>>>
>>
>>
>>
>> --
>> Thomas Mortagne
>

Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Adel Atallah
On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <[hidden email]> wrote:

>
>
>
> > On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]> wrote:
> >
> >
> >
> >> On 4 Jul 2018, at 12:07, Thomas Mortagne <[hidden email]> wrote:
> >>
> >> Here are more details on the actual use case we need to support:
> >>
> >> In include/Display macro either you set:
> >>
> >> * "reference" and "type" (which default to DOCUMENT)
> >> * or you set “page"
> >
> > Globally I think we need to add 3 concepts to macro parameter descriptor:
> >
> > 1) The concept of “deprecated” parameter. For example for “document” in the include macro.
> > 2) The concept of aliases or groups, i.e the ability to list parameters that are mutually exclusive. Example: reference + type vs page for display/include macros. This would mean that in the Macro Dialog UI if you select one of those the other gets unselected/cleared out (you cannot have mutually exclusive params have values).
> > 3) The concept of Advanced parameters. For example, we should put reference + type as advanced parameters so that they are not shown to the user by default (and so that the page parameter is more highlighted). Users would need to click on Advanced to see advanced parameters. I think we’re doing something automatic today (I don’t remember the details) to try to hide some parameters but we should probably review this.
> >
> > WDYT?
>
> Ping!
>
> Do we agree about this? If we do we can then create jira issue about it and take it for implementation.

+1, I can create the jira issue if it's ok.

>
> Thanks
> -Vincent
>
> >
> > Thanks
> > -Vincent
> >
> >
> >
> >>
> >>
> >> On Wed, Jul 4, 2018 at 10:57 AM, Marius Dumitru Florea
> >> <[hidden email]> wrote:
> >>> For groups of parameters we could use tabs:
> >>>
> >>> ----------8<----------
> >>> Param 1
> >>> [input]
> >>>
> >>> Param 2 | Param 3 | Param 4 <--- a group of 3 parameters displayed using
> >>> tabs (we take into account only the value of the parameter from the active
> >>> tab)
> >>> [input for param 2]
> >>>
> >>> Param 5
> >>> [input]
> >>> ---------->8----------
> >>>
> >>> But if you want to support subgroups of parameters also then it becomes
> >>> more complicated.
> >>>
> >>> Thanks,
> >>> Marius
> >>>
> >>> On Mon, Jul 2, 2018 at 11:52 AM, Thomas Mortagne <[hidden email]>
> >>> wrote:
> >>>
> >>>> Hi xwikiers,
> >>>>
> >>>> In the contact of bringing new Page concept (OK 7.4 is starting to get
> >>>> old) to the API and macros too we decided (1) to introduce a "page"
> >>>> shortcut property (even if we keep the reference/type for other
> >>>> types).
> >>>>
> >>>> While it's nicer for wiki syntax, one issue is that on WYSIWYG macros
> >>>> UI side, which display all properties, it means ending up with
> >>>> conflicting parameters that needs to be displayed as such.
> >>>>
> >>>> I don't really have much clue on how best to display this so I'm
> >>>> searching for ideas :)
> >>>>
> >>>> Then I will add in the macro descriptor what's required for whatever
> >>>> UI we want to build (group and sub groups of properties, etc.).
> >>>>
> >>>> 1: http://design.xwiki.org/xwiki/bin/view/Proposal/
> >>>> DeprecatingSpaceAndSpaceReference#HMacros
> >>>>
> >>>> Thanks,
> >>>> --
> >>>> Thomas Mortagnes
> >>>>
> >>
> >>
> >>
> >> --
> >> Thomas Mortagne
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

vmassol
Administrator


> On 19 Sep 2018, at 14:47, Adel Atallah <[hidden email]> wrote:
>
> On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <[hidden email]> wrote:
>>
>>
>>
>>> On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]> wrote:
>>>
>>>
>>>
>>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <[hidden email]> wrote:
>>>>
>>>> Here are more details on the actual use case we need to support:
>>>>
>>>> In include/Display macro either you set:
>>>>
>>>> * "reference" and "type" (which default to DOCUMENT)
>>>> * or you set “page"
>>>
>>> Globally I think we need to add 3 concepts to macro parameter descriptor:
>>>
>>> 1) The concept of “deprecated” parameter. For example for “document” in the include macro.
>>> 2) The concept of aliases or groups, i.e the ability to list parameters that are mutually exclusive. Example: reference + type vs page for display/include macros. This would mean that in the Macro Dialog UI if you select one of those the other gets unselected/cleared out (you cannot have mutually exclusive params have values).
>>> 3) The concept of Advanced parameters. For example, we should put reference + type as advanced parameters so that they are not shown to the user by default (and so that the page parameter is more highlighted). Users would need to click on Advanced to see advanced parameters. I think we’re doing something automatic today (I don’t remember the details) to try to hide some parameters but we should probably review this.
>>>
>>> WDYT?
>>
>> Ping!
>>
>> Do we agree about this? If we do we can then create jira issue about it and take it for implementation.
>
> +1, I can create the jira issue if it's ok.

Please do :)

@Marius: Ok for you?

thanks
-Vincent

[snip]


Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Marius Dumitru Florea
On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <[hidden email]> wrote:

>
>
> > On 19 Sep 2018, at 14:47, Adel Atallah <[hidden email]> wrote:
> >
> > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <[hidden email]>
> wrote:
> >>
> >>
> >>
> >>> On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]> wrote:
> >>>
> >>>
> >>>
> >>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <[hidden email]>
> wrote:
> >>>>
> >>>> Here are more details on the actual use case we need to support:
> >>>>
> >>>> In include/Display macro either you set:
> >>>>
> >>>> * "reference" and "type" (which default to DOCUMENT)
> >>>> * or you set “page"
> >>>
> >>> Globally I think we need to add 3 concepts to macro parameter
> descriptor:
> >>>
> >>> 1) The concept of “deprecated” parameter. For example for “document”
> in the include macro.
> >>> 2) The concept of aliases or groups, i.e the ability to list
> parameters that are mutually exclusive. Example: reference + type vs page
> for display/include macros. This would mean that in the Macro Dialog UI if
> you select one of those the other gets unselected/cleared out (you cannot
> have mutually exclusive params have values).
> >>> 3) The concept of Advanced parameters. For example, we should put
> reference + type as advanced parameters so that they are not shown to the
> user by default (and so that the page parameter is more highlighted). Users
> would need to click on Advanced to see advanced parameters. I think we’re
> doing something automatic today (I don’t remember the details) to try to
> hide some parameters but we should probably review this.
> >>>
> >>> WDYT?
> >>
> >> Ping!
> >>
> >> Do we agree about this? If we do we can then create jira issue about it
> and take it for implementation.
> >
> > +1, I can create the jira issue if it's ok.
>
> Please do :)
>
>

> @Marius: Ok for you?
>

Yes.


>
> thanks
> -Vincent
>
> [snip]
>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Adel Atallah
Hello everyone,

So what we thought about with Vincent for implementing the "concept of
aliases or groups" would be to actually have two new annotations that
we would use on macro properties.
The first one is a "Group" annotation which is meant to indicate that
some properties are part of the same group, obviously.
The second is an "Alternative" annotation which is meant to indicate
that only one property / group of properties can be used (among the
ones that are part of the alternative).
Here is an example:
We want for the Include macro to be able to specify either:
the "reference" and "type" parameters
or
the "page" parameter
For that, we will change the IncludeMacroParameters java class like this:

@Alternative("reference")
@Group("entityReference")
public void setReference(String reference)

@Alternative("reference")
@Group("entityReference")
public void setType(EntityType type)

@Alternative("reference")
public void setPage(String page)

In the WYSIWYG side, we will only be able to specify either the
"reference" and the "type" or the "page" parameter.

WDYT?

Thanks,
Adel

On Tue, Sep 25, 2018 at 11:51 AM Marius Dumitru Florea
<[hidden email]> wrote:

>
> On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <[hidden email]> wrote:
>
> >
> >
> > > On 19 Sep 2018, at 14:47, Adel Atallah <[hidden email]> wrote:
> > >
> > > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <[hidden email]>
> > wrote:
> > >>
> > >>
> > >>
> > >>> On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]> wrote:
> > >>>
> > >>>
> > >>>
> > >>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <[hidden email]>
> > wrote:
> > >>>>
> > >>>> Here are more details on the actual use case we need to support:
> > >>>>
> > >>>> In include/Display macro either you set:
> > >>>>
> > >>>> * "reference" and "type" (which default to DOCUMENT)
> > >>>> * or you set “page"
> > >>>
> > >>> Globally I think we need to add 3 concepts to macro parameter
> > descriptor:
> > >>>
> > >>> 1) The concept of “deprecated” parameter. For example for “document”
> > in the include macro.
> > >>> 2) The concept of aliases or groups, i.e the ability to list
> > parameters that are mutually exclusive. Example: reference + type vs page
> > for display/include macros. This would mean that in the Macro Dialog UI if
> > you select one of those the other gets unselected/cleared out (you cannot
> > have mutually exclusive params have values).
> > >>> 3) The concept of Advanced parameters. For example, we should put
> > reference + type as advanced parameters so that they are not shown to the
> > user by default (and so that the page parameter is more highlighted). Users
> > would need to click on Advanced to see advanced parameters. I think we’re
> > doing something automatic today (I don’t remember the details) to try to
> > hide some parameters but we should probably review this.
> > >>>
> > >>> WDYT?
> > >>
> > >> Ping!
> > >>
> > >> Do we agree about this? If we do we can then create jira issue about it
> > and take it for implementation.
> > >
> > > +1, I can create the jira issue if it's ok.
> >
> > Please do :)
> >
> >
>
> > @Marius: Ok for you?
> >
>
> Yes.
>
>
> >
> > thanks
> > -Vincent
> >
> > [snip]
> >
> >
> >
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Thomas Mortagne
Administrator
Note: this should be done at xwiki-commons-properties level. Macro
parameters are just one use case.
On Wed, Nov 7, 2018 at 4:34 PM Adel Atallah <[hidden email]> wrote:

>
> Hello everyone,
>
> So what we thought about with Vincent for implementing the "concept of
> aliases or groups" would be to actually have two new annotations that
> we would use on macro properties.
> The first one is a "Group" annotation which is meant to indicate that
> some properties are part of the same group, obviously.
> The second is an "Alternative" annotation which is meant to indicate
> that only one property / group of properties can be used (among the
> ones that are part of the alternative).
> Here is an example:
> We want for the Include macro to be able to specify either:
> the "reference" and "type" parameters
> or
> the "page" parameter
> For that, we will change the IncludeMacroParameters java class like this:
>
> @Alternative("reference")
> @Group("entityReference")
> public void setReference(String reference)
>
> @Alternative("reference")
> @Group("entityReference")
> public void setType(EntityType type)
>
> @Alternative("reference")
> public void setPage(String page)
>
> In the WYSIWYG side, we will only be able to specify either the
> "reference" and the "type" or the "page" parameter.
>
> WDYT?
>
> Thanks,
> Adel
>
> On Tue, Sep 25, 2018 at 11:51 AM Marius Dumitru Florea
> <[hidden email]> wrote:
> >
> > On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <[hidden email]> wrote:
> >
> > >
> > >
> > > > On 19 Sep 2018, at 14:47, Adel Atallah <[hidden email]> wrote:
> > > >
> > > > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <[hidden email]>
> > > wrote:
> > > >>
> > > >>
> > > >>
> > > >>> On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]> wrote:
> > > >>>
> > > >>>
> > > >>>
> > > >>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <[hidden email]>
> > > wrote:
> > > >>>>
> > > >>>> Here are more details on the actual use case we need to support:
> > > >>>>
> > > >>>> In include/Display macro either you set:
> > > >>>>
> > > >>>> * "reference" and "type" (which default to DOCUMENT)
> > > >>>> * or you set “page"
> > > >>>
> > > >>> Globally I think we need to add 3 concepts to macro parameter
> > > descriptor:
> > > >>>
> > > >>> 1) The concept of “deprecated” parameter. For example for “document”
> > > in the include macro.
> > > >>> 2) The concept of aliases or groups, i.e the ability to list
> > > parameters that are mutually exclusive. Example: reference + type vs page
> > > for display/include macros. This would mean that in the Macro Dialog UI if
> > > you select one of those the other gets unselected/cleared out (you cannot
> > > have mutually exclusive params have values).
> > > >>> 3) The concept of Advanced parameters. For example, we should put
> > > reference + type as advanced parameters so that they are not shown to the
> > > user by default (and so that the page parameter is more highlighted). Users
> > > would need to click on Advanced to see advanced parameters. I think we’re
> > > doing something automatic today (I don’t remember the details) to try to
> > > hide some parameters but we should probably review this.
> > > >>>
> > > >>> WDYT?
> > > >>
> > > >> Ping!
> > > >>
> > > >> Do we agree about this? If we do we can then create jira issue about it
> > > and take it for implementation.
> > > >
> > > > +1, I can create the jira issue if it's ok.
> > >
> > > Please do :)
> > >
> > >
> >
> > > @Marius: Ok for you?
> > >
> >
> > Yes.
> >
> >
> > >
> > > thanks
> > > -Vincent
> > >
> > > [snip]
> > >
> > >
> > >



--
Thomas Mortagne
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Marius Dumitru Florea
In reply to this post by Adel Atallah
On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah <[hidden email]> wrote:

> Hello everyone,
>
> So what we thought about with Vincent for implementing the "concept of
> aliases or groups" would be to actually have two new annotations that
> we would use on macro properties.
> The first one is a "Group" annotation which is meant to indicate that
> some properties are part of the same group, obviously.
> The second is an "Alternative" annotation which is meant to indicate
> that only one property / group of properties can be used (among the
> ones that are part of the alternative).
> Here is an example:
> We want for the Include macro to be able to specify either:
> the "reference" and "type" parameters
> or
> the "page" parameter
> For that, we will change the IncludeMacroParameters java class like this:
>
> @Alternative("reference")
> @Group("entityReference")
> public void setReference(String reference)
>
> @Alternative("reference")
> @Group("entityReference")
> public void setType(EntityType type)
>
> @Alternative("reference")
> public void setPage(String page)
>
> In the WYSIWYG side, we will only be able to specify either the
> "reference" and the "type" or the "page" parameter.
>

I think it would make more sense, at least in this case, to have the
alternative as an attribute of the group, because semantically the
"entityReference" group is an alternative to the page parameter. You can't
say that the type parameter alone is an alternative to the page parameter.

The @Group annotation is clear. No doubt about it. I'm not sure about
the @Alternative annotation. I'm thinking that the "alternative" is also a
group, where only one item from the group can be used, which could be
expressed with an attribute of the @Group annotation.


>
> WDYT?
>
> Thanks,
> Adel
>
> On Tue, Sep 25, 2018 at 11:51 AM Marius Dumitru Florea
> <[hidden email]> wrote:
> >
> > On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <[hidden email]>
> wrote:
> >
> > >
> > >
> > > > On 19 Sep 2018, at 14:47, Adel Atallah <[hidden email]>
> wrote:
> > > >
> > > > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <[hidden email]>
> > > wrote:
> > > >>
> > > >>
> > > >>
> > > >>> On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]>
> wrote:
> > > >>>
> > > >>>
> > > >>>
> > > >>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <
> [hidden email]>
> > > wrote:
> > > >>>>
> > > >>>> Here are more details on the actual use case we need to support:
> > > >>>>
> > > >>>> In include/Display macro either you set:
> > > >>>>
> > > >>>> * "reference" and "type" (which default to DOCUMENT)
> > > >>>> * or you set “page"
> > > >>>
> > > >>> Globally I think we need to add 3 concepts to macro parameter
> > > descriptor:
> > > >>>
> > > >>> 1) The concept of “deprecated” parameter. For example for
> “document”
> > > in the include macro.
> > > >>> 2) The concept of aliases or groups, i.e the ability to list
> > > parameters that are mutually exclusive. Example: reference + type vs
> page
> > > for display/include macros. This would mean that in the Macro Dialog
> UI if
> > > you select one of those the other gets unselected/cleared out (you
> cannot
> > > have mutually exclusive params have values).
> > > >>> 3) The concept of Advanced parameters. For example, we should put
> > > reference + type as advanced parameters so that they are not shown to
> the
> > > user by default (and so that the page parameter is more highlighted).
> Users
> > > would need to click on Advanced to see advanced parameters. I think
> we’re
> > > doing something automatic today (I don’t remember the details) to try
> to
> > > hide some parameters but we should probably review this.
> > > >>>
> > > >>> WDYT?
> > > >>
> > > >> Ping!
> > > >>
> > > >> Do we agree about this? If we do we can then create jira issue
> about it
> > > and take it for implementation.
> > > >
> > > > +1, I can create the jira issue if it's ok.
> > >
> > > Please do :)
> > >
> > >
> >
> > > @Marius: Ok for you?
> > >
> >
> > Yes.
> >
> >
> > >
> > > thanks
> > > -Vincent
> > >
> > > [snip]
> > >
> > >
> > >
>
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

vmassol
Administrator
Hi,

> On 9 Nov 2018, at 11:20, Marius Dumitru Florea <[hidden email]> wrote:
>
> On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah <[hidden email]> wrote:
>
>> Hello everyone,
>>
>> So what we thought about with Vincent for implementing the "concept of
>> aliases or groups" would be to actually have two new annotations that
>> we would use on macro properties.
>> The first one is a "Group" annotation which is meant to indicate that
>> some properties are part of the same group, obviously.
>> The second is an "Alternative" annotation which is meant to indicate
>> that only one property / group of properties can be used (among the
>> ones that are part of the alternative).
>> Here is an example:
>> We want for the Include macro to be able to specify either:
>> the "reference" and "type" parameters
>> or
>> the "page" parameter
>> For that, we will change the IncludeMacroParameters java class like this:
>>
>> @Alternative("reference")
>> @Group("entityReference")
>> public void setReference(String reference)
>>
>> @Alternative("reference")
>> @Group("entityReference")
>> public void setType(EntityType type)
>>
>> @Alternative("reference")
>> public void setPage(String page)
>>
>> In the WYSIWYG side, we will only be able to specify either the
>> "reference" and the "type" or the "page" parameter.
>>
>
> I think it would make more sense, at least in this case, to have the
> alternative as an attribute of the group, because semantically the
> "entityReference" group is an alternative to the page parameter. You can't
> say that the type parameter alone is an alternative to the page parameter.
>
> The @Group annotation is clear. No doubt about it. I'm not sure about
> the @Alternative annotation. I'm thinking that the "alternative" is also a
> group, where only one item from the group can be used, which could be
> expressed with an attribute of the @Group annotation.

For me the concepts of Groups and Alternatives are separate. For example you could imagine defining a group of properties so that the WYSIWYG would display them together, one under another or with some box border around them.

Alternatives don’t need to be on groups. You can have alternatives on individual properties or alternatives between 1 property and a group or alternatives between one group and another.

Thanks
-Vincent

[snip]


Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Adel Atallah
In reply to this post by Marius Dumitru Florea
On Fri, Nov 9, 2018 at 11:20 AM Marius Dumitru Florea
<[hidden email]> wrote:

>
> On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah <[hidden email]> wrote:
>
> > Hello everyone,
> >
> > So what we thought about with Vincent for implementing the "concept of
> > aliases or groups" would be to actually have two new annotations that
> > we would use on macro properties.
> > The first one is a "Group" annotation which is meant to indicate that
> > some properties are part of the same group, obviously.
> > The second is an "Alternative" annotation which is meant to indicate
> > that only one property / group of properties can be used (among the
> > ones that are part of the alternative).
> > Here is an example:
> > We want for the Include macro to be able to specify either:
> > the "reference" and "type" parameters
> > or
> > the "page" parameter
> > For that, we will change the IncludeMacroParameters java class like this:
> >
> > @Alternative("reference")
> > @Group("entityReference")
> > public void setReference(String reference)
> >
> > @Alternative("reference")
> > @Group("entityReference")
> > public void setType(EntityType type)
> >
> > @Alternative("reference")
> > public void setPage(String page)
> >
> > In the WYSIWYG side, we will only be able to specify either the
> > "reference" and the "type" or the "page" parameter.
> >
>
> I think it would make more sense, at least in this case, to have the
> alternative as an attribute of the group, because semantically the
> "entityReference" group is an alternative to the page parameter. You can't
> say that the type parameter alone is an alternative to the page parameter.
>
> The @Group annotation is clear. No doubt about it. I'm not sure about
> the @Alternative annotation. I'm thinking that the "alternative" is also a
> group, where only one item from the group can be used, which could be
> expressed with an attribute of the @Group annotation.

Thanks for the suggestion, but how can it be used? If I retake my previous
example, will it be:

@Group(name = "entityReference", alternative = "reference")
public void setReference(String reference)

@Group(name = "entityReference", alternative = "reference")
public void setType(EntityType type)

@Group(name = "page", alternative = "reference")
public void setPage(String page)

?

>
>
> >
> > WDYT?
> >
> > Thanks,
> > Adel
> >
> > On Tue, Sep 25, 2018 at 11:51 AM Marius Dumitru Florea
> > <[hidden email]> wrote:
> > >
> > > On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <[hidden email]>
> > wrote:
> > >
> > > >
> > > >
> > > > > On 19 Sep 2018, at 14:47, Adel Atallah <[hidden email]>
> > wrote:
> > > > >
> > > > > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <[hidden email]>
> > > > wrote:
> > > > >>
> > > > >>
> > > > >>
> > > > >>> On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]>
> > wrote:
> > > > >>>
> > > > >>>
> > > > >>>
> > > > >>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <
> > [hidden email]>
> > > > wrote:
> > > > >>>>
> > > > >>>> Here are more details on the actual use case we need to support:
> > > > >>>>
> > > > >>>> In include/Display macro either you set:
> > > > >>>>
> > > > >>>> * "reference" and "type" (which default to DOCUMENT)
> > > > >>>> * or you set “page"
> > > > >>>
> > > > >>> Globally I think we need to add 3 concepts to macro parameter
> > > > descriptor:
> > > > >>>
> > > > >>> 1) The concept of “deprecated” parameter. For example for
> > “document”
> > > > in the include macro.
> > > > >>> 2) The concept of aliases or groups, i.e the ability to list
> > > > parameters that are mutually exclusive. Example: reference + type vs
> > page
> > > > for display/include macros. This would mean that in the Macro Dialog
> > UI if
> > > > you select one of those the other gets unselected/cleared out (you
> > cannot
> > > > have mutually exclusive params have values).
> > > > >>> 3) The concept of Advanced parameters. For example, we should put
> > > > reference + type as advanced parameters so that they are not shown to
> > the
> > > > user by default (and so that the page parameter is more highlighted).
> > Users
> > > > would need to click on Advanced to see advanced parameters. I think
> > we’re
> > > > doing something automatic today (I don’t remember the details) to try
> > to
> > > > hide some parameters but we should probably review this.
> > > > >>>
> > > > >>> WDYT?
> > > > >>
> > > > >> Ping!
> > > > >>
> > > > >> Do we agree about this? If we do we can then create jira issue
> > about it
> > > > and take it for implementation.
> > > > >
> > > > > +1, I can create the jira issue if it's ok.
> > > >
> > > > Please do :)
> > > >
> > > >
> > >
> > > > @Marius: Ok for you?
> > > >
> > >
> > > Yes.
> > >
> > >
> > > >
> > > > thanks
> > > > -Vincent
> > > >
> > > > [snip]
> > > >
> > > >
> > > >
> >
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Marius Dumitru Florea
In reply to this post by vmassol
On Fri, Nov 9, 2018 at 12:29 PM Vincent Massol <[hidden email]> wrote:

> Hi,
>
> > On 9 Nov 2018, at 11:20, Marius Dumitru Florea <
> [hidden email]> wrote:
> >
> > On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah <[hidden email]>
> wrote:
> >
> >> Hello everyone,
> >>
> >> So what we thought about with Vincent for implementing the "concept of
> >> aliases or groups" would be to actually have two new annotations that
> >> we would use on macro properties.
> >> The first one is a "Group" annotation which is meant to indicate that
> >> some properties are part of the same group, obviously.
> >> The second is an "Alternative" annotation which is meant to indicate
> >> that only one property / group of properties can be used (among the
> >> ones that are part of the alternative).
> >> Here is an example:
> >> We want for the Include macro to be able to specify either:
> >> the "reference" and "type" parameters
> >> or
> >> the "page" parameter
> >> For that, we will change the IncludeMacroParameters java class like
> this:
> >>
> >> @Alternative("reference")
> >> @Group("entityReference")
> >> public void setReference(String reference)
> >>
> >> @Alternative("reference")
> >> @Group("entityReference")
> >> public void setType(EntityType type)
> >>
> >> @Alternative("reference")
> >> public void setPage(String page)
> >>
> >> In the WYSIWYG side, we will only be able to specify either the
> >> "reference" and the "type" or the "page" parameter.
> >>
> >
> > I think it would make more sense, at least in this case, to have the
> > alternative as an attribute of the group, because semantically the
> > "entityReference" group is an alternative to the page parameter. You
> can't
> > say that the type parameter alone is an alternative to the page
> parameter.
> >
> > The @Group annotation is clear. No doubt about it. I'm not sure about
> > the @Alternative annotation. I'm thinking that the "alternative" is also
> a
> > group, where only one item from the group can be used, which could be
> > expressed with an attribute of the @Group annotation.
>
> For me the concepts of Groups and Alternatives are separate. For example
> you could imagine defining a group of properties so that the WYSIWYG would
> display them together, one under another or with some box border around
> them.
>
>

> Alternatives don’t need to be on groups.


I did not say the alternatives must be **on** groups. I said the
alternatives **are** groups. When you have two alternative parameters then
those 2 parameters are in an alternative **group**. That's what I said.
Whether the groups is used just for display or for enforcing exclusive
usage is something that could be expressed using annotation attributes.


> You can have alternatives on individual properties or alternatives between
> 1 property and a group or alternatives between one group and another.
>
> Thanks
> -Vincent
>
> [snip]
>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Marius Dumitru Florea
In reply to this post by Adel Atallah
Try to view the macro parameters listed as a boolean expression. For the
include macro we would have:

(page XOR (reference AND type) XOR document) OR section OR context

* the parentheses define the parameter groups
* the boolean operators specify the relation between the members of a group

We then need to express this using Java annotations. In any case, this is a
**tree** structure (not a flat structure).

On Fri, Nov 9, 2018 at 12:30 PM Adel Atallah <[hidden email]> wrote:

> On Fri, Nov 9, 2018 at 11:20 AM Marius Dumitru Florea
> <[hidden email]> wrote:
> >
> > On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah <[hidden email]>
> wrote:
> >
> > > Hello everyone,
> > >
> > > So what we thought about with Vincent for implementing the "concept of
> > > aliases or groups" would be to actually have two new annotations that
> > > we would use on macro properties.
> > > The first one is a "Group" annotation which is meant to indicate that
> > > some properties are part of the same group, obviously.
> > > The second is an "Alternative" annotation which is meant to indicate
> > > that only one property / group of properties can be used (among the
> > > ones that are part of the alternative).
> > > Here is an example:
> > > We want for the Include macro to be able to specify either:
> > > the "reference" and "type" parameters
> > > or
> > > the "page" parameter
> > > For that, we will change the IncludeMacroParameters java class like
> this:
> > >
> > > @Alternative("reference")
> > > @Group("entityReference")
> > > public void setReference(String reference)
> > >
> > > @Alternative("reference")
> > > @Group("entityReference")
> > > public void setType(EntityType type)
> > >
> > > @Alternative("reference")
> > > public void setPage(String page)
> > >
> > > In the WYSIWYG side, we will only be able to specify either the
> > > "reference" and the "type" or the "page" parameter.
> > >
> >
> > I think it would make more sense, at least in this case, to have the
> > alternative as an attribute of the group, because semantically the
> > "entityReference" group is an alternative to the page parameter. You
> can't
> > say that the type parameter alone is an alternative to the page
> parameter.
> >
> > The @Group annotation is clear. No doubt about it. I'm not sure about
> > the @Alternative annotation. I'm thinking that the "alternative" is also
> a
> > group, where only one item from the group can be used, which could be
> > expressed with an attribute of the @Group annotation.
>
> Thanks for the suggestion, but how can it be used? If I retake my previous
> example, will it be:
>
> @Group(name = "entityReference", alternative = "reference")
> public void setReference(String reference)
>
> @Group(name = "entityReference", alternative = "reference")
> public void setType(EntityType type)
>
> @Group(name = "page", alternative = "reference")
> public void setPage(String page)
>
> ?
> >
> >
> > >
> > > WDYT?
> > >
> > > Thanks,
> > > Adel
> > >
> > > On Tue, Sep 25, 2018 at 11:51 AM Marius Dumitru Florea
> > > <[hidden email]> wrote:
> > > >
> > > > On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <[hidden email]>
> > > wrote:
> > > >
> > > > >
> > > > >
> > > > > > On 19 Sep 2018, at 14:47, Adel Atallah <[hidden email]>
> > > wrote:
> > > > > >
> > > > > > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <
> [hidden email]>
> > > > > wrote:
> > > > > >>
> > > > > >>
> > > > > >>
> > > > > >>> On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]>
> > > wrote:
> > > > > >>>
> > > > > >>>
> > > > > >>>
> > > > > >>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <
> > > [hidden email]>
> > > > > wrote:
> > > > > >>>>
> > > > > >>>> Here are more details on the actual use case we need to
> support:
> > > > > >>>>
> > > > > >>>> In include/Display macro either you set:
> > > > > >>>>
> > > > > >>>> * "reference" and "type" (which default to DOCUMENT)
> > > > > >>>> * or you set “page"
> > > > > >>>
> > > > > >>> Globally I think we need to add 3 concepts to macro parameter
> > > > > descriptor:
> > > > > >>>
> > > > > >>> 1) The concept of “deprecated” parameter. For example for
> > > “document”
> > > > > in the include macro.
> > > > > >>> 2) The concept of aliases or groups, i.e the ability to list
> > > > > parameters that are mutually exclusive. Example: reference + type
> vs
> > > page
> > > > > for display/include macros. This would mean that in the Macro
> Dialog
> > > UI if
> > > > > you select one of those the other gets unselected/cleared out (you
> > > cannot
> > > > > have mutually exclusive params have values).
> > > > > >>> 3) The concept of Advanced parameters. For example, we should
> put
> > > > > reference + type as advanced parameters so that they are not shown
> to
> > > the
> > > > > user by default (and so that the page parameter is more
> highlighted).
> > > Users
> > > > > would need to click on Advanced to see advanced parameters. I think
> > > we’re
> > > > > doing something automatic today (I don’t remember the details) to
> try
> > > to
> > > > > hide some parameters but we should probably review this.
> > > > > >>>
> > > > > >>> WDYT?
> > > > > >>
> > > > > >> Ping!
> > > > > >>
> > > > > >> Do we agree about this? If we do we can then create jira issue
> > > about it
> > > > > and take it for implementation.
> > > > > >
> > > > > > +1, I can create the jira issue if it's ok.
> > > > >
> > > > > Please do :)
> > > > >
> > > > >
> > > >
> > > > > @Marius: Ok for you?
> > > > >
> > > >
> > > > Yes.
> > > >
> > > >
> > > > >
> > > > > thanks
> > > > > -Vincent
> > > > >
> > > > > [snip]
> > > > >
> > > > >
> > > > >
> > >
>
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Adel Atallah
In reply to this post by Marius Dumitru Florea
On Fri, Nov 9, 2018 at 11:57 AM Marius Dumitru Florea
<[hidden email]> wrote:

>
> On Fri, Nov 9, 2018 at 12:29 PM Vincent Massol <[hidden email]> wrote:
>
> > Hi,
> >
> > > On 9 Nov 2018, at 11:20, Marius Dumitru Florea <
> > [hidden email]> wrote:
> > >
> > > On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah <[hidden email]>
> > wrote:
> > >
> > >> Hello everyone,
> > >>
> > >> So what we thought about with Vincent for implementing the "concept of
> > >> aliases or groups" would be to actually have two new annotations that
> > >> we would use on macro properties.
> > >> The first one is a "Group" annotation which is meant to indicate that
> > >> some properties are part of the same group, obviously.
> > >> The second is an "Alternative" annotation which is meant to indicate
> > >> that only one property / group of properties can be used (among the
> > >> ones that are part of the alternative).
> > >> Here is an example:
> > >> We want for the Include macro to be able to specify either:
> > >> the "reference" and "type" parameters
> > >> or
> > >> the "page" parameter
> > >> For that, we will change the IncludeMacroParameters java class like
> > this:
> > >>
> > >> @Alternative("reference")
> > >> @Group("entityReference")
> > >> public void setReference(String reference)
> > >>
> > >> @Alternative("reference")
> > >> @Group("entityReference")
> > >> public void setType(EntityType type)
> > >>
> > >> @Alternative("reference")
> > >> public void setPage(String page)
> > >>
> > >> In the WYSIWYG side, we will only be able to specify either the
> > >> "reference" and the "type" or the "page" parameter.
> > >>
> > >
> > > I think it would make more sense, at least in this case, to have the
> > > alternative as an attribute of the group, because semantically the
> > > "entityReference" group is an alternative to the page parameter. You
> > can't
> > > say that the type parameter alone is an alternative to the page
> > parameter.
> > >
> > > The @Group annotation is clear. No doubt about it. I'm not sure about
> > > the @Alternative annotation. I'm thinking that the "alternative" is also
> > a
> > > group, where only one item from the group can be used, which could be
> > > expressed with an attribute of the @Group annotation.
> >
> > For me the concepts of Groups and Alternatives are separate. For example
> > you could imagine defining a group of properties so that the WYSIWYG would
> > display them together, one under another or with some box border around
> > them.
> >
> >
>
> > Alternatives don’t need to be on groups.
>
>
> I did not say the alternatives must be **on** groups. I said the
> alternatives **are** groups. When you have two alternative parameters then
> those 2 parameters are in an alternative **group**. That's what I said.
> Whether the groups is used just for display or for enforcing exclusive
> usage is something that could be expressed using annotation attributes.

I'm not sure to understand what you mean. Could you give us an example?

>
>
> > You can have alternatives on individual properties or alternatives between
> > 1 property and a group or alternatives between one group and another.
> >
> > Thanks
> > -Vincent
> >
> > [snip]
> >
> >
> >
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Adel Atallah
In reply to this post by Marius Dumitru Florea
On Fri, Nov 9, 2018 at 12:08 PM Marius Dumitru Florea
<[hidden email]> wrote:
>
> Try to view the macro parameters listed as a boolean expression. For the
> include macro we would have:
>
> (page XOR (reference AND type) XOR document) OR section OR context

Wouldn't it be: (page XOR (reference AND type) XOR document) *AND*
section *AND* context ?
I just feel like you can just have 2 types of "operators": one to
exclude (XOR) and the other to include (AND) parameters.

>
> * the parentheses define the parameter groups
> * the boolean operators specify the relation between the members of a group
>
> We then need to express this using Java annotations. In any case, this is a
> **tree** structure (not a flat structure).

What you describe could probably be done with what we proposed but
maybe we can have something more explicit:

public void setReference(String reference)

@Depends("reference")
public void setType(EntityType type)

@Conflict("reference")
public void setPage(String page)

Could that work? We would need to write all the logic behind to build the tree:
1. All parameters are joined by an 'AND' by default => page AND
reference AND type
2. Page and Reference are conflicting => (page XOR reference) AND type
3. Type depends on Reference => (page XOR (reference AND type))

WDYT?

>
> On Fri, Nov 9, 2018 at 12:30 PM Adel Atallah <[hidden email]> wrote:
>
> > On Fri, Nov 9, 2018 at 11:20 AM Marius Dumitru Florea
> > <[hidden email]> wrote:
> > >
> > > On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah <[hidden email]>
> > wrote:
> > >
> > > > Hello everyone,
> > > >
> > > > So what we thought about with Vincent for implementing the "concept of
> > > > aliases or groups" would be to actually have two new annotations that
> > > > we would use on macro properties.
> > > > The first one is a "Group" annotation which is meant to indicate that
> > > > some properties are part of the same group, obviously.
> > > > The second is an "Alternative" annotation which is meant to indicate
> > > > that only one property / group of properties can be used (among the
> > > > ones that are part of the alternative).
> > > > Here is an example:
> > > > We want for the Include macro to be able to specify either:
> > > > the "reference" and "type" parameters
> > > > or
> > > > the "page" parameter
> > > > For that, we will change the IncludeMacroParameters java class like
> > this:
> > > >
> > > > @Alternative("reference")
> > > > @Group("entityReference")
> > > > public void setReference(String reference)
> > > >
> > > > @Alternative("reference")
> > > > @Group("entityReference")
> > > > public void setType(EntityType type)
> > > >
> > > > @Alternative("reference")
> > > > public void setPage(String page)
> > > >
> > > > In the WYSIWYG side, we will only be able to specify either the
> > > > "reference" and the "type" or the "page" parameter.
> > > >
> > >
> > > I think it would make more sense, at least in this case, to have the
> > > alternative as an attribute of the group, because semantically the
> > > "entityReference" group is an alternative to the page parameter. You
> > can't
> > > say that the type parameter alone is an alternative to the page
> > parameter.
> > >
> > > The @Group annotation is clear. No doubt about it. I'm not sure about
> > > the @Alternative annotation. I'm thinking that the "alternative" is also
> > a
> > > group, where only one item from the group can be used, which could be
> > > expressed with an attribute of the @Group annotation.
> >
> > Thanks for the suggestion, but how can it be used? If I retake my previous
> > example, will it be:
> >
> > @Group(name = "entityReference", alternative = "reference")
> > public void setReference(String reference)
> >
> > @Group(name = "entityReference", alternative = "reference")
> > public void setType(EntityType type)
> >
> > @Group(name = "page", alternative = "reference")
> > public void setPage(String page)
> >
> > ?
> > >
> > >
> > > >
> > > > WDYT?
> > > >
> > > > Thanks,
> > > > Adel
> > > >
> > > > On Tue, Sep 25, 2018 at 11:51 AM Marius Dumitru Florea
> > > > <[hidden email]> wrote:
> > > > >
> > > > > On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <[hidden email]>
> > > > wrote:
> > > > >
> > > > > >
> > > > > >
> > > > > > > On 19 Sep 2018, at 14:47, Adel Atallah <[hidden email]>
> > > > wrote:
> > > > > > >
> > > > > > > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <
> > [hidden email]>
> > > > > > wrote:
> > > > > > >>
> > > > > > >>
> > > > > > >>
> > > > > > >>> On 5 Jul 2018, at 12:06, Vincent Massol <[hidden email]>
> > > > wrote:
> > > > > > >>>
> > > > > > >>>
> > > > > > >>>
> > > > > > >>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <
> > > > [hidden email]>
> > > > > > wrote:
> > > > > > >>>>
> > > > > > >>>> Here are more details on the actual use case we need to
> > support:
> > > > > > >>>>
> > > > > > >>>> In include/Display macro either you set:
> > > > > > >>>>
> > > > > > >>>> * "reference" and "type" (which default to DOCUMENT)
> > > > > > >>>> * or you set “page"
> > > > > > >>>
> > > > > > >>> Globally I think we need to add 3 concepts to macro parameter
> > > > > > descriptor:
> > > > > > >>>
> > > > > > >>> 1) The concept of “deprecated” parameter. For example for
> > > > “document”
> > > > > > in the include macro.
> > > > > > >>> 2) The concept of aliases or groups, i.e the ability to list
> > > > > > parameters that are mutually exclusive. Example: reference + type
> > vs
> > > > page
> > > > > > for display/include macros. This would mean that in the Macro
> > Dialog
> > > > UI if
> > > > > > you select one of those the other gets unselected/cleared out (you
> > > > cannot
> > > > > > have mutually exclusive params have values).
> > > > > > >>> 3) The concept of Advanced parameters. For example, we should
> > put
> > > > > > reference + type as advanced parameters so that they are not shown
> > to
> > > > the
> > > > > > user by default (and so that the page parameter is more
> > highlighted).
> > > > Users
> > > > > > would need to click on Advanced to see advanced parameters. I think
> > > > we’re
> > > > > > doing something automatic today (I don’t remember the details) to
> > try
> > > > to
> > > > > > hide some parameters but we should probably review this.
> > > > > > >>>
> > > > > > >>> WDYT?
> > > > > > >>
> > > > > > >> Ping!
> > > > > > >>
> > > > > > >> Do we agree about this? If we do we can then create jira issue
> > > > about it
> > > > > > and take it for implementation.
> > > > > > >
> > > > > > > +1, I can create the jira issue if it's ok.
> > > > > >
> > > > > > Please do :)
> > > > > >
> > > > > >
> > > > >
> > > > > > @Marius: Ok for you?
> > > > > >
> > > > >
> > > > > Yes.
> > > > >
> > > > >
> > > > > >
> > > > > > thanks
> > > > > > -Vincent
> > > > > >
> > > > > > [snip]
> > > > > >
> > > > > >
> > > > > >
> > > >
> >
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Marius Dumitru Florea
On Fri, Nov 9, 2018 at 4:58 PM Adel Atallah <[hidden email]> wrote:

> On Fri, Nov 9, 2018 at 12:08 PM Marius Dumitru Florea
> <[hidden email]> wrote:
> >
> > Try to view the macro parameters listed as a boolean expression. For the
> > include macro we would have:
> >
> > (page XOR (reference AND type) XOR document) OR section OR context
>
>

> Wouldn't it be: (page XOR (reference AND type) XOR document) *AND*
> section *AND* context ?
>

No. AND means (logically) both sides are required. You can specify the
section parameter without specifying the context parameter. So it's
definitely a *logical / boolean* OR between them.

I put AND between reference and type just to show that there might be cases
when two (or more) parameters must be specified together (i.e. either you
specify both or you specify none of them). In our case the type parameter
has a default value so you can specify only the reference. This means it's
actually OR between reference and type in the case of the include macro.


> I just feel like you can just have 2 types of "operators": one to
> exclude (XOR) and the other to include (AND) parameters.
>

I still think there can be 3 operators (if we want to cover everything). As
I said, you may want to express the fact that a parameter is mandatory only
if some other parameter is specified. We can't express this ATM so I guess
we can work only with XOR and OR.


>
> >
> > * the parentheses define the parameter groups
> > * the boolean operators specify the relation between the members of a
> group
> >
> > We then need to express this using Java annotations. In any case, this
> is a
> > **tree** structure (not a flat structure).
>
> What you describe could probably be done with what we proposed but
> maybe we can have something more explicit:
>
> public void setReference(String reference)
>
> @Depends("reference")
> public void setType(EntityType type)
>
> @Conflict("reference")
> public void setPage(String page)
>
> Could that work? We would need to write all the logic behind to build the
> tree:
> 1. All parameters are joined by an 'AND' by default => page AND
> reference AND type
> 2. Page and Reference are conflicting => (page XOR reference) AND type
> 3. Type depends on Reference => (page XOR (reference AND type))
>
> WDYT?
>

I'm not sure how @Depends and @Conflict defines the tree structure in
general. I was rather thinking of something like:

@GroupPath("target[XOR]")
page

@GroupPath("target[XOR]/entityReference")
reference

@GroupPath("target[XOR]/entityReference")
type

@GroupPath("target[XOR]")
document

If we want subgroups then we need to specify a path. The complex part is to
specify the "operator" that should be used within a subgroup.


> >
> > On Fri, Nov 9, 2018 at 12:30 PM Adel Atallah <[hidden email]>
> wrote:
> >
> > > On Fri, Nov 9, 2018 at 11:20 AM Marius Dumitru Florea
> > > <[hidden email]> wrote:
> > > >
> > > > On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah <[hidden email]>
> > > wrote:
> > > >
> > > > > Hello everyone,
> > > > >
> > > > > So what we thought about with Vincent for implementing the
> "concept of
> > > > > aliases or groups" would be to actually have two new annotations
> that
> > > > > we would use on macro properties.
> > > > > The first one is a "Group" annotation which is meant to indicate
> that
> > > > > some properties are part of the same group, obviously.
> > > > > The second is an "Alternative" annotation which is meant to
> indicate
> > > > > that only one property / group of properties can be used (among the
> > > > > ones that are part of the alternative).
> > > > > Here is an example:
> > > > > We want for the Include macro to be able to specify either:
> > > > > the "reference" and "type" parameters
> > > > > or
> > > > > the "page" parameter
> > > > > For that, we will change the IncludeMacroParameters java class like
> > > this:
> > > > >
> > > > > @Alternative("reference")
> > > > > @Group("entityReference")
> > > > > public void setReference(String reference)
> > > > >
> > > > > @Alternative("reference")
> > > > > @Group("entityReference")
> > > > > public void setType(EntityType type)
> > > > >
> > > > > @Alternative("reference")
> > > > > public void setPage(String page)
> > > > >
> > > > > In the WYSIWYG side, we will only be able to specify either the
> > > > > "reference" and the "type" or the "page" parameter.
> > > > >
> > > >
> > > > I think it would make more sense, at least in this case, to have the
> > > > alternative as an attribute of the group, because semantically the
> > > > "entityReference" group is an alternative to the page parameter. You
> > > can't
> > > > say that the type parameter alone is an alternative to the page
> > > parameter.
> > > >
> > > > The @Group annotation is clear. No doubt about it. I'm not sure about
> > > > the @Alternative annotation. I'm thinking that the "alternative" is
> also
> > > a
> > > > group, where only one item from the group can be used, which could be
> > > > expressed with an attribute of the @Group annotation.
> > >
> > > Thanks for the suggestion, but how can it be used? If I retake my
> previous
> > > example, will it be:
> > >
> > > @Group(name = "entityReference", alternative = "reference")
> > > public void setReference(String reference)
> > >
> > > @Group(name = "entityReference", alternative = "reference")
> > > public void setType(EntityType type)
> > >
> > > @Group(name = "page", alternative = "reference")
> > > public void setPage(String page)
> > >
> > > ?
> > > >
> > > >
> > > > >
> > > > > WDYT?
> > > > >
> > > > > Thanks,
> > > > > Adel
> > > > >
> > > > > On Tue, Sep 25, 2018 at 11:51 AM Marius Dumitru Florea
> > > > > <[hidden email]> wrote:
> > > > > >
> > > > > > On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <
> [hidden email]>
> > > > > wrote:
> > > > > >
> > > > > > >
> > > > > > >
> > > > > > > > On 19 Sep 2018, at 14:47, Adel Atallah <
> [hidden email]>
> > > > > wrote:
> > > > > > > >
> > > > > > > > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <
> > > [hidden email]>
> > > > > > > wrote:
> > > > > > > >>
> > > > > > > >>
> > > > > > > >>
> > > > > > > >>> On 5 Jul 2018, at 12:06, Vincent Massol <
> [hidden email]>
> > > > > wrote:
> > > > > > > >>>
> > > > > > > >>>
> > > > > > > >>>
> > > > > > > >>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <
> > > > > [hidden email]>
> > > > > > > wrote:
> > > > > > > >>>>
> > > > > > > >>>> Here are more details on the actual use case we need to
> > > support:
> > > > > > > >>>>
> > > > > > > >>>> In include/Display macro either you set:
> > > > > > > >>>>
> > > > > > > >>>> * "reference" and "type" (which default to DOCUMENT)
> > > > > > > >>>> * or you set “page"
> > > > > > > >>>
> > > > > > > >>> Globally I think we need to add 3 concepts to macro
> parameter
> > > > > > > descriptor:
> > > > > > > >>>
> > > > > > > >>> 1) The concept of “deprecated” parameter. For example for
> > > > > “document”
> > > > > > > in the include macro.
> > > > > > > >>> 2) The concept of aliases or groups, i.e the ability to
> list
> > > > > > > parameters that are mutually exclusive. Example: reference +
> type
> > > vs
> > > > > page
> > > > > > > for display/include macros. This would mean that in the Macro
> > > Dialog
> > > > > UI if
> > > > > > > you select one of those the other gets unselected/cleared out
> (you
> > > > > cannot
> > > > > > > have mutually exclusive params have values).
> > > > > > > >>> 3) The concept of Advanced parameters. For example, we
> should
> > > put
> > > > > > > reference + type as advanced parameters so that they are not
> shown
> > > to
> > > > > the
> > > > > > > user by default (and so that the page parameter is more
> > > highlighted).
> > > > > Users
> > > > > > > would need to click on Advanced to see advanced parameters. I
> think
> > > > > we’re
> > > > > > > doing something automatic today (I don’t remember the details)
> to
> > > try
> > > > > to
> > > > > > > hide some parameters but we should probably review this.
> > > > > > > >>>
> > > > > > > >>> WDYT?
> > > > > > > >>
> > > > > > > >> Ping!
> > > > > > > >>
> > > > > > > >> Do we agree about this? If we do we can then create jira
> issue
> > > > > about it
> > > > > > > and take it for implementation.
> > > > > > > >
> > > > > > > > +1, I can create the jira issue if it's ok.
> > > > > > >
> > > > > > > Please do :)
> > > > > > >
> > > > > > >
> > > > > >
> > > > > > > @Marius: Ok for you?
> > > > > > >
> > > > > >
> > > > > > Yes.
> > > > > >
> > > > > >
> > > > > > >
> > > > > > > thanks
> > > > > > > -Vincent
> > > > > > >
> > > > > > > [snip]
> > > > > > >
> > > > > > >
> > > > > > >
> > > > >
> > >
>
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Adel Atallah
On Fri, Nov 9, 2018 at 5:35 PM Marius Dumitru Florea
<[hidden email]> wrote:

>
> On Fri, Nov 9, 2018 at 4:58 PM Adel Atallah <[hidden email]> wrote:
>
> > On Fri, Nov 9, 2018 at 12:08 PM Marius Dumitru Florea
> > <[hidden email]> wrote:
> > >
> > > Try to view the macro parameters listed as a boolean expression. For the
> > > include macro we would have:
> > >
> > > (page XOR (reference AND type) XOR document) OR section OR context
> >
> >
>
> > Wouldn't it be: (page XOR (reference AND type) XOR document) *AND*
> > section *AND* context ?
> >
>
> No. AND means (logically) both sides are required. You can specify the
> section parameter without specifying the context parameter. So it's
> definitely a *logical / boolean* OR between them.
>
> I put AND between reference and type just to show that there might be cases
> when two (or more) parameters must be specified together (i.e. either you
> specify both or you specify none of them). In our case the type parameter
> has a default value so you can specify only the reference. This means it's
> actually OR between reference and type in the case of the include macro.
>
>
> > I just feel like you can just have 2 types of "operators": one to
> > exclude (XOR) and the other to include (AND) parameters.
> >
>
> I still think there can be 3 operators (if we want to cover everything). As
> I said, you may want to express the fact that a parameter is mandatory only
> if some other parameter is specified. We can't express this ATM so I guess
> we can work only with XOR and OR.
>
>
> >
> > >
> > > * the parentheses define the parameter groups
> > > * the boolean operators specify the relation between the members of a
> > group
> > >
> > > We then need to express this using Java annotations. In any case, this
> > is a
> > > **tree** structure (not a flat structure).
> >
> > What you describe could probably be done with what we proposed but
> > maybe we can have something more explicit:
> >
> > public void setReference(String reference)
> >
> > @Depends("reference")
> > public void setType(EntityType type)
> >
> > @Conflict("reference")
> > public void setPage(String page)
> >
> > Could that work? We would need to write all the logic behind to build the
> > tree:
> > 1. All parameters are joined by an 'AND' by default => page AND
> > reference AND type
> > 2. Page and Reference are conflicting => (page XOR reference) AND type
> > 3. Type depends on Reference => (page XOR (reference AND type))
> >
> > WDYT?
> >
>
> I'm not sure how @Depends and @Conflict defines the tree structure in
> general. I was rather thinking of something like:
>
> @GroupPath("target[XOR]")
> page
>
> @GroupPath("target[XOR]/entityReference")
> reference
>
> @GroupPath("target[XOR]/entityReference")
> type
>
> @GroupPath("target[XOR]")
> document
>
> If we want subgroups then we need to specify a path. The complex part is to
> specify the "operator" that should be used within a subgroup.
>

What we could do is use repeating annotations[1]:

@GroupPath(xor = "group1")
page

@GroupPath(xor = "group1")
@GroupPath(or = "group2", priority = 1)
reference

@GroupPath(xor = "group1")
@GroupPath(or = "group2", priority = 1)
type

@GroupPath(xor = "group1")
document

@GroupPath(and = "group3")
section

@GroupPath(and = "group3")
context

Everything in the "xor group" will be joined with a XOR. Fields will
be joined with an OR by default. The priority, which is by default 0,
defines the order of the "operations" (parenthesis). The previous
example would produce:
(page XOR (reference OR document) XOR document) OR (section AND context)

Maybe it's too complicated to use, WDYT?
Actually we could think of many cases where this would fail like:
@GroupPath(xor = "group")
field1

@GroupPath(and = "group")
field2

[1]: https://docs.oracle.com/javase/tutorial/java/annotations/repeating.html

>
> > >
> > > On Fri, Nov 9, 2018 at 12:30 PM Adel Atallah <[hidden email]>
> > wrote:
> > >
> > > > On Fri, Nov 9, 2018 at 11:20 AM Marius Dumitru Florea
> > > > <[hidden email]> wrote:
> > > > >
> > > > > On Wed, Nov 7, 2018 at 5:34 PM Adel Atallah <[hidden email]>
> > > > wrote:
> > > > >
> > > > > > Hello everyone,
> > > > > >
> > > > > > So what we thought about with Vincent for implementing the
> > "concept of
> > > > > > aliases or groups" would be to actually have two new annotations
> > that
> > > > > > we would use on macro properties.
> > > > > > The first one is a "Group" annotation which is meant to indicate
> > that
> > > > > > some properties are part of the same group, obviously.
> > > > > > The second is an "Alternative" annotation which is meant to
> > indicate
> > > > > > that only one property / group of properties can be used (among the
> > > > > > ones that are part of the alternative).
> > > > > > Here is an example:
> > > > > > We want for the Include macro to be able to specify either:
> > > > > > the "reference" and "type" parameters
> > > > > > or
> > > > > > the "page" parameter
> > > > > > For that, we will change the IncludeMacroParameters java class like
> > > > this:
> > > > > >
> > > > > > @Alternative("reference")
> > > > > > @Group("entityReference")
> > > > > > public void setReference(String reference)
> > > > > >
> > > > > > @Alternative("reference")
> > > > > > @Group("entityReference")
> > > > > > public void setType(EntityType type)
> > > > > >
> > > > > > @Alternative("reference")
> > > > > > public void setPage(String page)
> > > > > >
> > > > > > In the WYSIWYG side, we will only be able to specify either the
> > > > > > "reference" and the "type" or the "page" parameter.
> > > > > >
> > > > >
> > > > > I think it would make more sense, at least in this case, to have the
> > > > > alternative as an attribute of the group, because semantically the
> > > > > "entityReference" group is an alternative to the page parameter. You
> > > > can't
> > > > > say that the type parameter alone is an alternative to the page
> > > > parameter.
> > > > >
> > > > > The @Group annotation is clear. No doubt about it. I'm not sure about
> > > > > the @Alternative annotation. I'm thinking that the "alternative" is
> > also
> > > > a
> > > > > group, where only one item from the group can be used, which could be
> > > > > expressed with an attribute of the @Group annotation.
> > > >
> > > > Thanks for the suggestion, but how can it be used? If I retake my
> > previous
> > > > example, will it be:
> > > >
> > > > @Group(name = "entityReference", alternative = "reference")
> > > > public void setReference(String reference)
> > > >
> > > > @Group(name = "entityReference", alternative = "reference")
> > > > public void setType(EntityType type)
> > > >
> > > > @Group(name = "page", alternative = "reference")
> > > > public void setPage(String page)
> > > >
> > > > ?
> > > > >
> > > > >
> > > > > >
> > > > > > WDYT?
> > > > > >
> > > > > > Thanks,
> > > > > > Adel
> > > > > >
> > > > > > On Tue, Sep 25, 2018 at 11:51 AM Marius Dumitru Florea
> > > > > > <[hidden email]> wrote:
> > > > > > >
> > > > > > > On Wed, Sep 19, 2018 at 4:31 PM Vincent Massol <
> > [hidden email]>
> > > > > > wrote:
> > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > > On 19 Sep 2018, at 14:47, Adel Atallah <
> > [hidden email]>
> > > > > > wrote:
> > > > > > > > >
> > > > > > > > > On Wed, Jul 18, 2018 at 5:00 PM Vincent Massol <
> > > > [hidden email]>
> > > > > > > > wrote:
> > > > > > > > >>
> > > > > > > > >>
> > > > > > > > >>
> > > > > > > > >>> On 5 Jul 2018, at 12:06, Vincent Massol <
> > [hidden email]>
> > > > > > wrote:
> > > > > > > > >>>
> > > > > > > > >>>
> > > > > > > > >>>
> > > > > > > > >>>> On 4 Jul 2018, at 12:07, Thomas Mortagne <
> > > > > > [hidden email]>
> > > > > > > > wrote:
> > > > > > > > >>>>
> > > > > > > > >>>> Here are more details on the actual use case we need to
> > > > support:
> > > > > > > > >>>>
> > > > > > > > >>>> In include/Display macro either you set:
> > > > > > > > >>>>
> > > > > > > > >>>> * "reference" and "type" (which default to DOCUMENT)
> > > > > > > > >>>> * or you set “page"
> > > > > > > > >>>
> > > > > > > > >>> Globally I think we need to add 3 concepts to macro
> > parameter
> > > > > > > > descriptor:
> > > > > > > > >>>
> > > > > > > > >>> 1) The concept of “deprecated” parameter. For example for
> > > > > > “document”
> > > > > > > > in the include macro.
> > > > > > > > >>> 2) The concept of aliases or groups, i.e the ability to
> > list
> > > > > > > > parameters that are mutually exclusive. Example: reference +
> > type
> > > > vs
> > > > > > page
> > > > > > > > for display/include macros. This would mean that in the Macro
> > > > Dialog
> > > > > > UI if
> > > > > > > > you select one of those the other gets unselected/cleared out
> > (you
> > > > > > cannot
> > > > > > > > have mutually exclusive params have values).
> > > > > > > > >>> 3) The concept of Advanced parameters. For example, we
> > should
> > > > put
> > > > > > > > reference + type as advanced parameters so that they are not
> > shown
> > > > to
> > > > > > the
> > > > > > > > user by default (and so that the page parameter is more
> > > > highlighted).
> > > > > > Users
> > > > > > > > would need to click on Advanced to see advanced parameters. I
> > think
> > > > > > we’re
> > > > > > > > doing something automatic today (I don’t remember the details)
> > to
> > > > try
> > > > > > to
> > > > > > > > hide some parameters but we should probably review this.
> > > > > > > > >>>
> > > > > > > > >>> WDYT?
> > > > > > > > >>
> > > > > > > > >> Ping!
> > > > > > > > >>
> > > > > > > > >> Do we agree about this? If we do we can then create jira
> > issue
> > > > > > about it
> > > > > > > > and take it for implementation.
> > > > > > > > >
> > > > > > > > > +1, I can create the jira issue if it's ok.
> > > > > > > >
> > > > > > > > Please do :)
> > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > > > > @Marius: Ok for you?
> > > > > > > >
> > > > > > >
> > > > > > > Yes.
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > > thanks
> > > > > > > > -Vincent
> > > > > > > >
> > > > > > > > [snip]
> > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > >
> > > >
> >
Reply | Threaded
Open this post in threaded view
|

Re: [Need proposal] How to show "conflicting" macro parameters

Adel Atallah
Hello,

I'd like to briefly summarize the situation so that we can make some
progress.

What we have:
* We define "parameters" in a macro by creating a Java Bean, which
provides all the getters and setters of the parameters we want.
* We can use annotations on these getters/setters to define some
behavior or metadata for these parameters (description, mandatory,
deprecated...)

What we want:
* Being able to handle conflicting parameters. For instance when we
deprecate a parameter and add a new one to replace it, we should be
able to either use the deprecated parameter or the new one but not
both.
* We also want to group parameters that are related to each other.

What we proposed:
* Use annotations on the parameters to express the conflict.
* Marius proposed to see the problem as a boolean expression such as:
(page XOR (reference AND type) XOR document) OR section OR context.
This would translate as: the user can use the 'section' and/or
'context' parameters (if they want), can use only one of these
parameters: 'page', ('reference' and 'type') or 'document', where
'reference' and 'type' depend on each other and you can't use one
without the other.
* You can see on previous e-mails the kind of annotations we proposed
to solve the issue.

Thanks,
Adel