[516669] Update the Release Notes and documentation for rep lazy loading

* The developer documentation is updated

Bug: 516669
Change-Id: I26b7358d24c5e23dcbd3cb13d556d52bc1c8fb01
Signed-off-by: Florian Barbin <florian.barbin@obeo.fr>

8 files changed, 234 insertions, 84 deletions

diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
index 903d10b14b..70e4b9041f 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
@@ -160,13 +160,104 @@
 				<code>DRepresentationDescriptor.repPath</code> has been changed to have 
 				<code>uid</code> as fragment.
 			</li>
-		</ul>
-		<ul>
 			<li><span class="label label-success">Added</span> A migration has been added to fix diagram with edge bend-points corrupted (see 
 				<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=519044">bugzilla #519044</a> for more details). The corresponding version, stored in attribute version of viewpoint:DAnalysis of the aird file, is 
 				<em>12.1.0.201708031200</em>.
 			</li>
 		</ul>
+		<h4 id="Representationslazyloadingexperimental.">Representations lazy loading (experimental).</h4>
+		<p>A new mode (currently experimental) is available to load representations on demand and not during session opening. This feature implies to serialize Sirius representations in separate resources. This mode can be activated by setting the system property 
+			<code>createLocalRepresentationInSeparateResource</code> at true. For more detail, see the developer documentation: 
+			<a href="./developer/representations_lazy_loading.html">Representations lazy loading (experimental)</a>.
+		</p>
+		<h4 id="Changesinorg.eclipse.sirius">Changes in 
+			<code>org.eclipse.sirius</code>
+		</h4>
+		<ul>
+			<li><span class="label label-success">Added</span> 
+				<code>org.eclipse.sirius.viewpoint.DRepresentationDescriptor.isLoadedRepresentation()</code> has been added to know if the representation linked with this {@link DRepresentationDescriptor} is loaded. By default, all representations are held in the same resource than the DRepresentationDescriptor, in that case the method will always return true.
+			</li>
+			<li><span class="label label-success">Added</span> 
+				<code>org.eclipse.sirius.business.api.session.danalysis.DAnalysisSession.allAnalyses()</code> has been added in the interface to reflect the already existing 
+				<code>org.eclipse.sirius.business.internal.session.danalysis.DAnalysisSessionImpl.allAnalyses()</code> implementation.
+			</li>
+			<li><span class="label label-success">Added</span> 
+				<code>org.eclipse.sirius.business.api.dialect.DialectManager.getLoadedRepresentations(EObject, Session)</code> has been added to get all loaded representations in the given session with the given EObject as target.
+			</li>
+			<li><span class="label label-success">Added</span> 
+				<code>org.eclipse.sirius.business.api.dialect.DialectServices.getAllLoadedRepresentations(Session)</code> has been added to get all loaded representations in the given session.
+			</li>
+			<li><span class="label label-success">Added</span> 
+				<code>org.eclipse.sirius.business.api.helper.SiriusUtil.REPRESENTATIONS_FOLDER_NAME</code> constant has been added. This is the default folder where representations file (*.srm) are located if the system property &#8220;createLocalRepresentationInSeparateResource&#8221; is set at true.
+			</li>
+			<li><span class="label label-success">Added</span> 
+				<code>org.eclipse.sirius.tools.api.command.ui.UICallBack.shouldDeleteRepresentation(Set&lt;DRepresentationDescriptor&gt;)</code> has been added to be called when the user interface should prompt for a choice about the representation deletion.
+			</li>
+			<li><span class="label label-danger">Removed</span> 
+				<code>org.eclipse.sirius.business.api.dialect.DialectServices.getRepresentationDescriptors(EObject, Session)</code> has been moved to 
+				<code>org.eclipse.sirius.business.api.dialect.DialectManager</code>.
+			</li>
+			<li><span class="label label-danger">Removed</span> 
+				<code>org.eclipse.sirius.business.api.dialect.DialectServices.getAllRepresentationDescriptors(Session)</code> has been moved to 
+				<code>org.eclipse.sirius.business.api.dialect.DialectManager</code>.
+			</li>
+			<li><span class="label label-danger">Removed</span> 
+				<code>org.eclipse.sirius.business.api.dialect.DialectServices.getRepresentationDescriptors(RepresentationDescription, Session)</code> has been moved to 
+				<code>org.eclipse.sirius.business.api.dialect.DialectManager</code>.
+			</li>
+			<li><span class="label label-danger">Removed</span> The implementations of 
+				<code>getRepresentationDescriptors(EObject, Session)</code>, 
+				<code>getAllRepresentationDescriptors(Session)</code> and 
+				<code>getRepresentationDescriptors(RepresentationDescription, Session)</code> have been removed from 
+				<code>AbstractRepresentationDialectServices</code>. They are implemented in 
+				<code>DialectManagerImpl</code>.
+			</li>
+			<li><span class="label label-danger">Removed</span> 
+				<code>org.eclipse.sirius.business.api.dialect.DialectServices.getRepresentations(EObject, Session)</code> has been moved to 
+				<code>org.eclipse.sirius.business.api.dialect.DialectManager</code>
+			</li>
+			<li><span class="label label-danger">Removed</span> 
+				<code>org.eclipse.sirius.business.api.dialect.DialectServices.getAllRepresentations(Session)</code> has been moved to 
+				<code>org.eclipse.sirius.business.api.dialect.DialectManager</code>
+			</li>
+			<li><span class="label label-danger">Removed</span> 
+				<code>org.eclipse.sirius.business.api.dialect.DialectServices.getRepresentations(RepresentationDescription, Session)</code> has been moved to 
+				<code>org.eclipse.sirius.business.api.dialect.DialectManager</code>
+			</li>
+			<li><span class="label label-danger">Removed</span> The implementations of 
+				<code>getRepresentations(EObject, Session)</code>, 
+				<code>getAllRepresentations(Session)</code> and 
+				<code>getRepresentations(RepresentationDescription, Session)</code> have been removed from 
+				<code>AbstractRepresentationDialectServices</code>. They are implemented in 
+				<code>DialectManagerImpl</code>.
+			</li>
+		</ul>
+		<h4 id="Changesinorg.eclipse.sirius.common">Changes in 
+			<code>org.eclipse.sirius.common</code>
+		</h4>
+		<ul>
+			<li><span class="label label-success">Added</span> 
+				<code>org.eclipse.sirius.common.tools.api.util.LazyCrossReferencer.setEObjectToBeIgnored(Predicate&lt;EObject&gt;)</code> has  been added to filter inverse references to prevent some references resolution.
+			</li>
+			<li><span class="label label-info">Modified</span> 
+				<code>org.eclipse.sirius.common.tools.api.util.WorkspaceUtil.getFilesFromWorkspace(Collection&lt;IProject&gt;, String)</code> signature has been modified in 
+				<code>getFilesFromWorkspace(Collection&lt;IContainer&gt;, String)</code> to be more generic.
+			</li>
+		</ul>
+		<h4 id="Changesinorg.eclipse.sirius.ui">Changes in 
+			<code>org.eclipse.sirius.ui</code>
+		</h4>
+		<ul>
+			<li><span class="label label-success">Added</span> 
+				<code>org.eclipse.sirius.ui.tools.api.command.AbstractSWTCallback.shouldDeleteRepresentation(Set&lt;DRepresentationDescriptor&gt;)</code> default implementation has been added to prompt the confirm dialog.
+			</li>
+			<li><span class="label label-success">Added</span> 
+				<code>org.eclipse.sirius.ui.business.api.session.SessionEditorInput.SessionEditorInput(URI, URI, String, Session)</code> has been added to provide the 
+				<code>DRepresentationDescriptor</code> URI to retrieve the 
+				<code>DRepresentation</code> from the 
+				<code>DRepresentationDescriptor.getRepresentation()</code> method instead of performing a direct load.
+			</li>
+		</ul>
 		<h2 id="sirius5.0.1">Changes in Sirius 5.0.1</h2>
 		<p>Sirius 5.0.1 is a maintenance release with only bugfixes and small tweaks to the UI of 
 			<a href="user/general/Aird_Editor.html">the aird editor</a>.
@@ -260,7 +351,7 @@
 		<p>See 
 			<a href="i18n_changes.html#sirius50">this document</a> for the complete list of message keys added or removed in Sirius 5.0.
 		</p>
-		<h4 id="Changesinorg.eclipse.sirius.common">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius.common2">Changes in 
 			<code>org.eclipse.sirius.common</code> 
 		</h4>
 		<ul>
@@ -284,7 +375,7 @@
 				<code>org.eclipse.emf.edit.ui.celleditor.FeatureEditorDialog</code> equivalent provided by EMF directly instead.
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius2">Changes in 
 			<code>org.eclipse.sirius</code> 
 		</h4>
 		<ul>
@@ -418,7 +509,7 @@
 				<code>RepresentationElementIdentifier</code>) have been removed.
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius.ui">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius.ui2">Changes in 
 			<code>org.eclipse.sirius.ui</code>
 		</h4>
 		<ul>
@@ -987,7 +1078,7 @@ SWTBotUtils.waitAllUiEvents();
 				</ul>
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius2">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius3">Changes in 
 			<code>org.eclipse.sirius</code>
 		</h4>
 		<ul>
@@ -1092,7 +1183,7 @@ SWTBotUtils.waitAllUiEvents();
 				<code>updateModelsReferences(DAnalysis, Iterator&lt;DSemanticDecorator&gt;)</code> because it is more suited to the client needs.
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius.ui2">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius.ui3">Changes in 
 			<code>org.eclipse.sirius.ui</code>
 		</h4>
 		<ul>
@@ -1429,7 +1520,7 @@ SWTBotUtils.waitAllUiEvents();
 				<a href="developer/extensions-provide_custom_bundled_image_shape.html">developer documentation</a> for more details.
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius3">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius4">Changes in 
 			<code>org.eclipse.sirius</code>
 		</h4>
 		<ul>
@@ -1524,7 +1615,7 @@ SWTBotUtils.waitAllUiEvents();
 				<code>MetamodelDescriptorProvider</code>. 
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius.common2">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius.common3">Changes in 
 			<code>org.eclipse.sirius.common</code>
 		</h4>
 		<ul>
@@ -1586,7 +1677,7 @@ SWTBotUtils.waitAllUiEvents();
 				<code>org.eclipse.sirius.diagram.description.filter.impl.VariableFilterImpl.resetVariables()</code>.
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius.ui3">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius.ui4">Changes in 
 			<code>org.eclipse.sirius.ui</code>
 		</h4>
 		<ul>
@@ -1734,7 +1825,7 @@ SWTBotUtils.waitAllUiEvents();
 				<code>org.eclipse.sirius.ext.gmf.runtime.diagram.ui.tools.MoveInDiagramDragTracker</code> has been added to declare states used by all DragTrackers which manage move in diagram using mouse middle click.
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius.ui4">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius.ui5">Changes in 
 			<code>org.eclipse.sirius.ui</code>
 		</h4>
 		<ul>
@@ -2117,7 +2208,7 @@ SWTBotUtils.waitAllUiEvents();
 				</ul>
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius.common3">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius.common4">Changes in 
 			<code>org.eclipse.sirius.common</code>
 		</h4>
 		<ul>
@@ -2147,7 +2238,7 @@ SWTBotUtils.waitAllUiEvents();
 				<code>org.eclipse.sirius.common.tools.api.contentassist.ContentProposalBuilder</code> used to build the content proposals with their various parameters more easily.
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius4">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius5">Changes in 
 			<code>org.eclipse.sirius</code>
 		</h4>
 		<ul>
@@ -2186,7 +2277,7 @@ SWTBotUtils.waitAllUiEvents();
 				<code>org.eclipse.sirius.tools.api.command.IUndoableCommand</code> interface removed because it is useless since undo/redo is managed by EMF Transaction.
 			</li>
 		</ul>
-		<h4 id="Changesinorg.eclipse.sirius.ui5">Changes in 
+		<h4 id="Changesinorg.eclipse.sirius.ui6">Changes in 
 			<code>org.eclipse.sirius.ui</code>
 		</h4>
 		<ul>
diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
index e411c3f424..2f537e8e84 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
@@ -27,9 +27,39 @@ h4. Migrations
 * <span class="label label-success">Added</span> A migration has been added to fix diagram with edge labels corrupted (see "bugzilla #518870":https://bugs.eclipse.org/bugs/show_bug.cgi?id=518870 for more details). The corresponding version, stored in attribute version of viewpoint:DAnalysis of the aird file, is _12.1.0.201706291600_.
 * <span class="label label-success">Added</span> A new class @org.eclipse.sirius.ext.gmf.runtime.gef.ui.figures.SiriusDefaultSizeNodeFigure@ has been added in plugin @org.eclipse.sirius.ext.gmf.runtime@. The goal of the class is to workaround a "GMF bug":https://bugs.eclipse.org/bugs/show_bug.cgi?id=519250. So if you have created class which inherits from @org.eclipse.gmf.runtime.gef.ui.figures.DefaultSizeNodeFigure@, you must now use the new @SiriusDefaultSizeNodeFigure@ instead.
 * <span class="label label-success">Added</span> A migration has been added to add an @uid@ to all instances of type DRepresentation.This @uid@ is used to reference the DRepresentation from the DRepresentationDescriptor. @DRepresentationDescriptor.repPath@ has been changed to have @uid@ as fragment.
-
 * <span class="label label-success">Added</span> A migration has been added to fix diagram with edge bend-points corrupted (see "bugzilla #519044":https://bugs.eclipse.org/bugs/show_bug.cgi?id=519044 for more details). The corresponding version, stored in attribute version of viewpoint:DAnalysis of the aird file, is _12.1.0.201708031200_.
 
+h4. Representations lazy loading (experimental).
+
+A new mode (currently experimental) is available to load representations on demand and not during session opening. This feature implies to serialize Sirius representations in separate resources. This mode can be activated by setting the system property @createLocalRepresentationInSeparateResource@ at true. For more detail, see the developer documentation: "Representations lazy loading (experimental)":./developer/representations_lazy_loading.html.
+
+h4. Changes in @org.eclipse.sirius@
+
+* <span class="label label-success">Added</span> @org.eclipse.sirius.viewpoint.DRepresentationDescriptor.isLoadedRepresentation()@ has been added to know if the representation linked with this {@link DRepresentationDescriptor} is loaded. By default, all representations are held in the same resource than the DRepresentationDescriptor, in that case the method will always return true.
+* <span class="label label-success">Added</span> @org.eclipse.sirius.business.api.session.danalysis.DAnalysisSession.allAnalyses()@ has been added in the interface to reflect the already existing @org.eclipse.sirius.business.internal.session.danalysis.DAnalysisSessionImpl.allAnalyses()@ implementation.
+* <span class="label label-success">Added</span> @org.eclipse.sirius.business.api.dialect.DialectManager.getLoadedRepresentations(EObject, Session)@ has been added to get all loaded representations in the given session with the given EObject as target.
+* <span class="label label-success">Added</span> @org.eclipse.sirius.business.api.dialect.DialectServices.getAllLoadedRepresentations(Session)@ has been added to get all loaded representations in the given session.
+* <span class="label label-success">Added</span> @org.eclipse.sirius.business.api.helper.SiriusUtil.REPRESENTATIONS_FOLDER_NAME@ constant has been added. This is the default folder where representations file (*.srm) are located if the system property "createLocalRepresentationInSeparateResource" is set at true.
+* <span class="label label-success">Added</span> @org.eclipse.sirius.tools.api.command.ui.UICallBack.shouldDeleteRepresentation(Set<DRepresentationDescriptor>)@ has been added to be called when the user interface should prompt for a choice about the representation deletion.
+* <span class="label label-danger">Removed</span> @org.eclipse.sirius.business.api.dialect.DialectServices.getRepresentationDescriptors(EObject, Session)@ has been moved to @org.eclipse.sirius.business.api.dialect.DialectManager@.
+* <span class="label label-danger">Removed</span> @org.eclipse.sirius.business.api.dialect.DialectServices.getAllRepresentationDescriptors(Session)@ has been moved to @org.eclipse.sirius.business.api.dialect.DialectManager@.
+* <span class="label label-danger">Removed</span> @org.eclipse.sirius.business.api.dialect.DialectServices.getRepresentationDescriptors(RepresentationDescription, Session)@ has been moved to @org.eclipse.sirius.business.api.dialect.DialectManager@.
+* <span class="label label-danger">Removed</span> The implementations of @getRepresentationDescriptors(EObject, Session)@, @getAllRepresentationDescriptors(Session)@ and @getRepresentationDescriptors(RepresentationDescription, Session)@ have been removed from @AbstractRepresentationDialectServices@. They are implemented in @DialectManagerImpl@.
+* <span class="label label-danger">Removed</span> @org.eclipse.sirius.business.api.dialect.DialectServices.getRepresentations(EObject, Session)@ has been moved to @org.eclipse.sirius.business.api.dialect.DialectManager@
+* <span class="label label-danger">Removed</span> @org.eclipse.sirius.business.api.dialect.DialectServices.getAllRepresentations(Session)@ has been moved to @org.eclipse.sirius.business.api.dialect.DialectManager@
+* <span class="label label-danger">Removed</span> @org.eclipse.sirius.business.api.dialect.DialectServices.getRepresentations(RepresentationDescription, Session)@ has been moved to @org.eclipse.sirius.business.api.dialect.DialectManager@
+* <span class="label label-danger">Removed</span> The implementations of @getRepresentations(EObject, Session)@, @getAllRepresentations(Session)@ and @getRepresentations(RepresentationDescription, Session)@ have been removed from @AbstractRepresentationDialectServices@. They are implemented in @DialectManagerImpl@.
+
+h4. Changes in @org.eclipse.sirius.common@
+
+* <span class="label label-success">Added</span> @org.eclipse.sirius.common.tools.api.util.LazyCrossReferencer.setEObjectToBeIgnored(Predicate<EObject>)@ has  been added to filter inverse references to prevent some references resolution.
+* <span class="label label-info">Modified</span> @org.eclipse.sirius.common.tools.api.util.WorkspaceUtil.getFilesFromWorkspace(Collection<IProject>, String)@ signature has been modified in @getFilesFromWorkspace(Collection<IContainer>, String)@ to be more generic.
+
+h4. Changes in @org.eclipse.sirius.ui@
+
+* <span class="label label-success">Added</span> @org.eclipse.sirius.ui.tools.api.command.AbstractSWTCallback.shouldDeleteRepresentation(Set<DRepresentationDescriptor>)@ default implementation has been added to prompt the confirm dialog.
+* <span class="label label-success">Added</span> @org.eclipse.sirius.ui.business.api.session.SessionEditorInput.SessionEditorInput(URI, URI, String, Session)@ has been added to provide the @DRepresentationDescriptor@ URI to retrieve the @DRepresentation@ from the @DRepresentationDescriptor.getRepresentation()@ method instead of performing a direct load.
+
 h2(#sirius5.0.1). Changes in Sirius 5.0.1
 
 Sirius 5.0.1 is a maintenance release with only bugfixes and small tweaks to the UI of "the aird editor":user/general/Aird_Editor.html.
diff --git a/plugins/org.eclipse.sirius.doc/doc/developer/Sirius Developer Manual.html b/plugins/org.eclipse.sirius.doc/doc/developer/Sirius Developer Manual.html
index 0348d7708e..ac60f1a4e5 100644
--- a/plugins/org.eclipse.sirius.doc/doc/developer/Sirius Developer Manual.html
+++ b/plugins/org.eclipse.sirius.doc/doc/developer/Sirius Developer Manual.html
@@ -91,8 +91,8 @@
 						</a>
 					</li>
 					<li>
-						<a href="extensions-provide_representation_location_rule.html">
-							<strong>Provide representation location rule (experimental)</strong>
+						<a href="representations_lazy_loading.html">
+							<strong>Representations lazy loading (experimental)</strong>
 						</a>
 					</li>
 				</ul>
diff --git a/plugins/org.eclipse.sirius.doc/doc/developer/Sirius Developer Manual.textile b/plugins/org.eclipse.sirius.doc/doc/developer/Sirius Developer Manual.textile
index 9b8f9856e6..f4f50d4a45 100644
--- a/plugins/org.eclipse.sirius.doc/doc/developer/Sirius Developer Manual.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/developer/Sirius Developer Manual.textile
@@ -17,6 +17,6 @@ This document gives an overview of the internals of the _Sirius_ platform, and d
 ** "*Provide custom bundled image shape*":extensions-provide_custom_bundled_image_shape.html
 ** "*Provide custom widget for the properties view and dialogs*":extensions-properties_provide_custom_widget.html
 ** "*Provide custom model operation*":extensions-provide_custom_model_operation.html
-** "*Provide representation location rule (experimental)*":extensions-provide_representation_location_rule.html
+** "*Representations lazy loading (experimental)*":representations_lazy_loading.html
 * The Sirius platform publishs a set of API, and the next sections describe some which require particular attention:
 ** "*SiriusCrossReferenceAdapter*":siriusCrossReferenceAdapter.html
diff --git a/plugins/org.eclipse.sirius.doc/doc/developer/extensions-provide_representation_location_rule.html b/plugins/org.eclipse.sirius.doc/doc/developer/extensions-provide_representation_location_rule.html
deleted file mode 100644
index 07eea412b5..0000000000
--- a/plugins/org.eclipse.sirius.doc/doc/developer/extensions-provide_representation_location_rule.html
+++ /dev/null
@@ -1,45 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-	<head>
-		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
-		<title>extensions-provide_representation_location_rule</title>
-		<link type="text/css" rel="stylesheet" href="../resources/bootstrap.css"/>
-		<link type="text/css" rel="stylesheet" href="../resources/custom.css"/>
-	</head>
-	<body>
-		<h1 id="SiriusProviderepresentationlocationruleexperimental">Sirius &#8211; Provide representation location rule (experimental)</h1>
-		<h2 id="Goals">Goals</h2>
-		<p>An experimental mode to serialize representations in different files is available with the system property 
-			<code>createRepresentationInSeparateResource=true</code>. That means all new representations will be saved, by default, in a separate file with *.srm extension.
-			<br/>Developer may need to override this rule by choosing to add one or several representations in a specific resource.
-		</p>
-		<h2 id="Overridetherepresentationlocationrule.">Override the representation location rule.</h2>
-		<h3 id="TheDRepresentationLocationRuleinterface">The 
-			<code>DRepresentationLocationRule</code> interface
-		</h3>
-		<ul>
-			<li>
-				<code>boolean provides(DRepresentation representation, Resource dViewResource)</code>: Indicates if this 
-				<code>DRepresentationLocationRule</code> provides a custom URI for this kind of representation and the resource that holds the 
-				<code>DView</code>. If not and if there is no other 
-				<code>DRepresentationLocationRule</code> that provides, Sirius fall back to the default implementation.
-			</li>
-		</ul>
-		<ul>
-			<li>
-				<code>URI getResourceURI(DRepresentation representation, Resource dViewResource)</code>: Provides the new URI for the given representation.
-			</li>
-		</ul>
-		<ul>
-			<li>
-				<code>Boolean isARepresentationResource(String fileExtension)</code>: Indicates if the given file extension is considered as a representation file. This extension point allows to define its own extension to hold representations. The developer still needs to register the Resource Factory to 
-				<code>org.eclipse.emf.ecore.extension_parser</code> extension point.
-			</li>
-		</ul>
-		<h3 id="ProvideyourDRepresentationLocationRuleusingtheorg.eclipse.sirius.dRepresentationLocationRuleextensionpoint">Provide your 
-			<code>DRepresentationLocationRule</code> using the 
-			<code>org.eclipse.sirius.dRepresentationLocationRule</code> extension point
-		</h3>
-		<p>Please refer to this extension point documentation for more details.</p>
-	</body>
-</html>
\ No newline at end of file
diff --git a/plugins/org.eclipse.sirius.doc/doc/developer/extensions-provide_representation_location_rule.textile b/plugins/org.eclipse.sirius.doc/doc/developer/extensions-provide_representation_location_rule.textile
deleted file mode 100644
index acbdb5fda3..0000000000
--- a/plugins/org.eclipse.sirius.doc/doc/developer/extensions-provide_representation_location_rule.textile
+++ /dev/null
@@ -1,21 +0,0 @@
-h1. Sirius - Provide representation location rule (experimental)
-
-h2. Goals
-
-An experimental mode to serialize representations in different files is available with the system property @createRepresentationInSeparateResource=true@. That means all new representations will be saved, by default, in a separate file with *.srm extension.
-Developer may need to override this rule by choosing to add one or several representations in a specific resource.
-
-h2. Override the representation location rule.
-
-h3. The @DRepresentationLocationRule@ interface
-
-* @boolean provides(DRepresentation representation, Resource dViewResource)@: Indicates if this @DRepresentationLocationRule@ provides a custom URI for this kind of representation and the resource that holds the @DView@. If not and if there is no other @DRepresentationLocationRule@ that provides, Sirius fall back to the default implementation.
-
-* @URI getResourceURI(DRepresentation representation, Resource dViewResource)@: Provides the new URI for the given representation.
-    
-* @Boolean isARepresentationResource(String fileExtension)@: Indicates if the given file extension is considered as a representation file. This extension point allows to define its own extension to hold representations. The developer still needs to register the Resource Factory to @org.eclipse.emf.ecore.extension_parser@ extension point.
-
-h3. Provide your @DRepresentationLocationRule@ using the @org.eclipse.sirius.dRepresentationLocationRule@ extension point
-
-Please refer to this extension point documentation for more details.
-
diff --git a/plugins/org.eclipse.sirius.doc/doc/developer/representations_lazy_loading.html b/plugins/org.eclipse.sirius.doc/doc/developer/representations_lazy_loading.html
new file mode 100644
index 0000000000..b9321c2336
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/developer/representations_lazy_loading.html
@@ -0,0 +1,62 @@
+<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+	<head>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+		<title>representations_lazy_loading</title>
+		<link type="text/css" rel="stylesheet" href="../resources/bootstrap.css"/>
+		<link type="text/css" rel="stylesheet" href="../resources/custom.css"/>
+	</head>
+	<body>
+		<h1 id="SiriusRepresentationslazyloadingexperimental">Sirius &#8211; Representations lazy loading (experimental)</h1>
+		<h2 id="Overview">Overview</h2>
+		<p>An experimental mode allows to have the representation lazy loading. This mode is available with the system property 
+			<code>createLocalRepresentationInSeparateResource=true</code>.
+		</p>
+		<p>There is two main changes to keep in mind with this mode:</p>
+		<ul>
+			<li>The representations are (by default) serialized in separate *.srm files in a .representation folder. This folder is created at the same location than the *.aird file.</li>
+			<li>The representations are loaded on demand. That means the session opening does not load the representations. They will be loaded as soon as Sirius needs it to perform the functionality. For example: open an editor, copy, rename or delete a representation, export a diagram as image etc. From a developer point of view, the representation is loaded when 
+				<code>DRepresentationDescriptor.getRepresentation()</code> is called.
+			</li>
+		</ul>
+		<h2 id="Impacts">Impacts</h2>
+		<p>The Sirius API used to retrieve 
+			<code>DRepresentation</code>, such as the 
+			<code>DialectManager</code>, keep the same behavior: the representation will be loaded where necessary. New API (see the release note for more details) has been added to retrieve only loaded representations.
+		</p>
+		<p>
+			<strong>Warning</strong>, if some of your features depend on the Sirius crossReferencer, it may not return the same result than before. It works on the scope of only what is loaded in the session. Before, all the models was loaded whereas now some representations will not be. 
+			<code>ECrossReferenceAdapter.getInverseReferences(EObject )</code> or 
+			<code>ECrossReferenceAdapter.getInverseReferences(EObject , boolean)</code> will not provide potential inverse references that would be in not loaded representation. The typical case is getting DRepresentationElement referencing a semantic element as DSemanticDecorator.target.
+		</p>
+		<h2 id="Overridetherepresentationlocationrule.">Override the representation location rule.</h2>
+		<p>By default Sirius creates an *.srm file per representation. Developer may need to override this rule by choosing to add one or several representations in a specific resource.</p>
+		<h3 id="TheDRepresentationLocationRuleinterface">The 
+			<code>DRepresentationLocationRule</code> interface
+		</h3>
+		<ul>
+			<li>
+				<code>boolean provides(DRepresentation representation, Resource dViewResource)</code>: Indicates if this 
+				<code>DRepresentationLocationRule</code> provides a custom URI for this kind of representation and the resource that holds the 
+				<code>DView</code>. If not and if there is no other 
+				<code>DRepresentationLocationRule</code> that provides, Sirius fall back to the default implementation.
+			</li>
+		</ul>
+		<ul>
+			<li>
+				<code>URI getResourceURI(DRepresentation representation, Resource dViewResource)</code>: Provides the new URI for the given representation.
+			</li>
+		</ul>
+		<ul>
+			<li>
+				<code>Boolean isARepresentationResource(String fileExtension)</code>: Indicates if the given file extension is considered as a representation file. This extension point allows to define its own extension to hold representations. The developer still needs to register the Resource Factory to 
+				<code>org.eclipse.emf.ecore.extension_parser</code> extension point.
+			</li>
+		</ul>
+		<h3 id="ProvideyourDRepresentationLocationRuleusingtheorg.eclipse.sirius.dRepresentationLocationRuleextensionpoint">Provide your 
+			<code>DRepresentationLocationRule</code> using the 
+			<code>org.eclipse.sirius.dRepresentationLocationRule</code> extension point
+		</h3>
+		<p>Please refer to this extension point documentation for more details.</p>
+	</body>
+</html>
\ No newline at end of file
diff --git a/plugins/org.eclipse.sirius.doc/doc/developer/representations_lazy_loading.textile b/plugins/org.eclipse.sirius.doc/doc/developer/representations_lazy_loading.textile
new file mode 100644
index 0000000000..9d7290be32
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/developer/representations_lazy_loading.textile
@@ -0,0 +1,33 @@
+h1. Sirius - Representations lazy loading (experimental)
+
+h2. Overview
+
+An experimental mode allows to have the representation lazy loading. This mode is available with the system property @createLocalRepresentationInSeparateResource=true@.
+
+There is two main changes to keep in mind with this mode:
+* The representations are (by default) serialized in separate *.srm files in a .representation folder. This folder is created at the same location than the *.aird file.
+* The representations are loaded on demand. That means the session opening does not load the representations. They will be loaded as soon as Sirius needs it to perform the functionality. For example: open an editor, copy, rename or delete a representation, export a diagram as image etc. From a developer point of view, the representation is loaded when @DRepresentationDescriptor.getRepresentation()@ is called.
+
+h2. Impacts
+
+The Sirius API used to retrieve @DRepresentation@, such as the @DialectManager@, keep the same behavior: the representation will be loaded where necessary. New API (see the release note for more details) has been added to retrieve only loaded representations.
+
+*Warning*, if some of your features depend on the Sirius crossReferencer, it may not return the same result than before. It works on the scope of only what is loaded in the session. Before, all the models was loaded whereas now some representations will not be. @ECrossReferenceAdapter.getInverseReferences(EObject )@ or @ECrossReferenceAdapter.getInverseReferences(EObject , boolean)@ will not provide potential inverse references that would be in not loaded representation. The typical case is getting DRepresentationElement referencing a semantic element as DSemanticDecorator.target.
+
+
+h2. Override the representation location rule.
+
+By default Sirius creates an *.srm file per representation. Developer may need to override this rule by choosing to add one or several representations in a specific resource.
+
+h3. The @DRepresentationLocationRule@ interface
+
+* @boolean provides(DRepresentation representation, Resource dViewResource)@: Indicates if this @DRepresentationLocationRule@ provides a custom URI for this kind of representation and the resource that holds the @DView@. If not and if there is no other @DRepresentationLocationRule@ that provides, Sirius fall back to the default implementation.
+
+* @URI getResourceURI(DRepresentation representation, Resource dViewResource)@: Provides the new URI for the given representation.
+    
+* @Boolean isARepresentationResource(String fileExtension)@: Indicates if the given file extension is considered as a representation file. This extension point allows to define its own extension to hold representations. The developer still needs to register the Resource Factory to @org.eclipse.emf.ecore.extension_parser@ extension point.
+
+h3. Provide your @DRepresentationLocationRule@ using the @org.eclipse.sirius.dRepresentationLocationRule@ extension point
+
+Please refer to this extension point documentation for more details.
+