Hi again,

After discovering http://jira.xwiki.org/browse/XWIKI-7301 and after discussing this more with Ludovic, Denis and Thomas, here's what we propose:

For 3.2.1 and 3.3.1: - revert behavior of include as it was before 3.0 (i.e. 1 year ago) i.e. have include with context = current be the default and no relative resolution of links/images - Big warning in release notes about the change and explain that in 3.4+ there's a new "display" macro for the context=new use case (see below)

For 3.4: - revert behavior of include as it was before 3.0 (i.e. 1 year ago) i.e. have include with context = current be the default and no relative resolution of links/images - new display macro (equivalent to include context = new) - Big warning in release notes about the change - deprecate the "context" param in include macro - deprecate the "document" param in include macro and add "reference" + "type" (with default type being documents) - also use "reference" and "type" params in new "display" macro

Future: - possibly add a resolve=current|source parameter in the include macro in the future if we find a valid use case for it

The idea is to release 3.2.1, 3.3.1 ASAP so that user move back to the old behavior ASAP.

Here's my +1

We need to find a volunteer to implement this ASAP. If anyone has some time for this please step forward :)

I suggest Thomas since he followed this issue

Thanks -Vincent

PS: We discussed the idea of a backward compatibility param but we decided against since it would think complex and not help that much in the end.

On Oct 7, 2011, at 2:16 PM, Vincent Massol wrote:

context=current and resolve=current (ie links resolve on the including document)

resolve=source for the include macro. Once again the context param has nothing to do with how links/images are resolved. And again the writer of a page isn't necessarily the same as the person who's going to include your page.

and resolve=source (the default we have now and which we need to not break people)

"reference" parameter + a new "type" parameter (I forgot that one in my first email). The "type" parameter represents the Entity Reference Type.

links/attachments when they're included using the {{include}} macro (they're now resolved against the included document instead of the including document).

where you'd want the links to be resolved against the including document. Here's a use case: you have a sheet document that references an image called image.png and you want that the including document provides it (like an Abstract in Java! ;)).

*execute* the passed reference in its own context (it'll do what {{include context="new"…}} was doing before). It'll be located in the new display module.

possible values = "current" | "source", with a default value of "source". resolve=source means that the links/attachments are resolved against the source (ie the document being included). Using resolve=current means that you want the links/attachments resolved against the including document.

parameter of the include macro in favor of a more generic "reference" parameter, which will allow the macro to include other types of entities (such as an object property for ex).