Update user guide, developer guide and sample use case.

User guide:
- update outdated screenshots, update outdated speech
- add speech and screenshots for new user interface
- add handling conflicts section
- add graphical comparison section
- add uml specialization section
Developer guide:
- add extension filter and group section
Sample use case:
- update outdated screenshots, update outdated speech

Change-Id: I2c685dba11b8d20640c2756c6990e33fcb14151a

61 files changed, 526 insertions, 182 deletions

diff --git a/plugins/org.eclipse.emf.compare.doc/plugin.xml b/plugins/org.eclipse.emf.compare.doc/plugin.xml
index ead3f38ab..034b0ea6d 100644
--- a/plugins/org.eclipse.emf.compare.doc/plugin.xml
+++ b/plugins/org.eclipse.emf.compare.doc/plugin.xml
@@ -1,4 +1,5 @@
-<?xml version='1.0' encoding='UTF-8' ?><?eclipse version="3.2"?>
+<?xml version='1.0' encoding='UTF-8' ?>
+<?eclipse version="3.2"?>
 
 <plugin>
 </plugin>
\ No newline at end of file
diff --git a/plugins/org.eclipse.emf.compare.doc/src/developer/developer-guide.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/developer/developer-guide.mediawiki
index 1c7ad01e4..a921460df 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/developer/developer-guide.mediawiki
+++ b/plugins/org.eclipse.emf.compare.doc/src/developer/developer-guide.mediawiki
@@ -4,13 +4,13 @@
 
 === Comparison Process ===
 
-[[Image:images/EMF_Compare_Process_Full.png|thumb|center|800px]]
+[[Image:./../images/EMF_Compare_Process_Full.png|thumb|center|800px]]
 
 This is the overview of the comparison process as a whole. Each of the six phases of the comparison process of EMF Compare are briefly defined on the [[./../overview/Overview.html|Overview]], and a much more in-depth explanation will be given below, in our explanations of the [[./Default%20Behavior%20and%20Extensibility.html|default behavior]] of EMF Compare.
 
 === Project Architecture ===
 
-[[Image:images/EMF_Compare_2_Architecture.png|center]]
+[[Image:./../images/EMF_Compare_2_Architecture.png|center]]
 
 EMF Compare is built on top of the Eclipse platform. We depend on the Eclipse Modeling Framework (EMF), the Eclipse Compare framework and, finally, Eclipse Team, the framework upon which the repository providers (EGit, CVS, Subversive...) are built.
 
@@ -32,8 +32,8 @@ A ''Match'' element is how we represent that the ''n'' compared versions have el
 ! align="center" | Master
 ! align="center" | Borrowables
 |-
-| [[Image:images/v1.png|center]]
-| [[Image:images/v2.png|center]]
+| [[Image:./../images/v1.png|center]]
+| [[Image:./../images/v2.png|center]]
 |}
 
 Comparing these two models, we'll have a Comparison model containing three matches:
@@ -458,7 +458,189 @@ PENDING how to provide custom mergers, override existing ones?
 
 === User Interface ===
 
-PENDING customize display of custom differences, add custom menu entries, add groups, add filters, add export options, provide custom content viewer
+==== Add your own filter ====
+
+You can provide your own filters by adding an extension of type ''org.eclipse.emf.compare.rcp.ui.filters'' to your plugin.
+
+[[Image:./../images/EMF_Compare_Developer_New_Extension_Filter.png|center]]
+
+This extension has three fields:
+* class: a class that implements ''org.eclipse.emf.compare.rcp.ui.internal.structuremergeviewer.filters.IDifferenceFilter''
+* label: the label that will be displayed in the UI.
+* activeByDefault: true if you want your filter be active by default, false otherwise.
+
+The ''org.eclipse.emf.compare.rcp.ui.internal.structuremergeviewer.filters.IDifferenceFilter'''s contract is:
+
+<source lang="java">
+/**
+ * Instances of this class will be used by EMF Compare in order to provide difference filter facilities to the
+ * structural differences view.
+ * @since 3.0
+ */
+public interface IDifferenceFilter {
+
+	/**
+	 * Returns the predicate that will filter out objects in the structural differences view when this filter
+	 * will be selected.
+	 * 
+	 * @return the predicate that will filter out objects in the structural differences view when this filter
+	 *         will be selected.
+	 */
+	Predicate<? super EObject> getPredicateWhenSelected();
+
+	/**
+	 * Returns the predicate that will filter out objects in the structural differences view when this filter
+	 * will be unselected.
+	 * 
+	 * @return the predicate that will filter out objects in the structural differences view when this filter
+	 *         will be unselected.
+	 */
+	Predicate<? super EObject> getPredicateWhenUnselected();
+
+	/**
+	 * A human-readable label for this filter. This will be displayed in the EMF Compare UI.
+	 * 
+	 * @return The label for this filter.
+	 */
+	String getLabel();
+
+	/**
+	 * Set the label for this filter. This will be displayed in the EMF Compare UI.
+	 * 
+	 * @param label
+	 *            A human-readable label for this filter.
+	 */
+	void setLabel(String label);
+
+	/**
+	 * Returns the initial activation state that the filter should have.
+	 * 
+	 * @return The initial activation state that the filter should have.
+	 */
+	boolean defaultSelected();
+
+	/**
+	 * Set the initial activation state that the filter should have.
+	 * 
+	 * @param defaultSelected
+	 *            The initial activation state that the filter should have (true if the filter should be
+	 *            active by default).
+	 */
+	void setDefaultSelected(boolean defaultSelected);
+
+	/**
+	 * Returns the activation condition based on the scope and comparison objects.
+	 * 
+	 * @param scope
+	 *            The scope on which the filter will be applied.
+	 * @param comparison
+	 *            The comparison which is to be displayed in the structural view.
+	 * @return The activation condition based on the scope and comparison objects.
+	 */
+	boolean isEnabled(IComparisonScope scope, Comparison comparison);
+}
+</source>
+
+A default abstract implementation named ''org.eclipse.emf.compare.rcp.ui.internal.structuremergeviewer.filters.impl.AbstractDifferenceFilter'' is available in the ''org.eclipse.emf.compare.rcp.ui'' plugin. With this abstract implementation, all you have to do is to subclass it and implements the ''getPredicateWhenSelected()'' method.
+
+==== Add your own group ====
+
+[[Image:./../images/EMF_Compare_Developer_New_Extension_Group.png|center]]
+
+This extension has three fields:
+* class: a class that implements ''org.eclipse.emf.compare.rcp.ui.internal.structuremergeviewer.groups.IDifferenceGroupProvider''
+* label: the label that will be displayed in the UI.
+* activeByDefault: true if you want your filter be active by default, false otherwise.
+
+The ''org.eclipse.emf.compare.rcp.ui.internal.structuremergeviewer.groups.IDifferenceGroupProvider'''s contract is:
+
+<source lang="java">
+/**
+ * Instances of this class will be used by EMF Compare in order to provide difference grouping facilities to
+ * the structural differences view.
+ * @since 3.0
+ */
+public interface IDifferenceGroupProvider extends Adapter {
+
+	/**
+	 * This will be called internally by the grouping actions in order to determine how the differences should
+	 * be grouped in the structural view.
+	 * 
+	 * @param comparison
+	 *            The comparison which is to be displayed in the structural view. By default, its containment
+	 *            tree will be displayed.
+	 * @return The collection of difference groups that are to be displayed in the structural viewer. An empty
+	 *         group will not be displayed at all. If {@code null}, we'll fall back to the default behavior.
+	 */
+	Collection<? extends IDifferenceGroup> getGroups(Comparison comparison);
+
+	/**
+	 * A human-readable label for this group. This will be displayed in the EMF Compare UI.
+	 * 
+	 * @return The label for this group.
+	 */
+	String getLabel();
+
+	/**
+	 * Set the label for this group. This will be displayed in the EMF Compare UI.
+	 * 
+	 * @param label
+	 *            A human-readable label for this group.
+	 */
+	void setLabel(String label);
+
+	/**
+	 * Returns the initial activation state that the group should have.
+	 * 
+	 * @return The initial activation state that the group should have.
+	 */
+	boolean defaultSelected();
+
+	/**
+	 * Set the initial activation state that the group should have.
+	 * 
+	 * @param defaultSelected
+	 *            The initial activation state that the group should have (true if the group should be active
+	 *            by default).
+	 */
+	void setDefaultSelected(boolean defaultSelected);
+
+	/**
+	 * Returns the activation condition based on the scope and comparison objects.
+	 * 
+	 * @param scope
+	 *            The scope on which the group provider will be applied.
+	 * @param comparison
+	 *            The comparison which is to be displayed in the structural view.
+	 * @return The activation condition based on the scope and comparison objects.
+	 */
+	boolean isEnabled(IComparisonScope scope, Comparison comparison);
+
+	/**
+	 * Dispose this difference group provider.
+	 */
+	void dispose();
+	
+	/**
+	 * Returns all {@link TreeNode}s that are wrapping the given {@code eObject}. It internally use a cross
+	 * reference adapter.
+	 * 
+	 * @param eObject
+	 *            the object from which we want inverse reference.
+	 * @return all {@link TreeNode}s targeting the given {@code eObject} through
+	 *         {@link TreePackage.Literals#TREE_NODE__DATA}.
+	 */
+	List<TreeNode> getTreeNodes(EObject eObject);
+}
+</source>
+
+A default abstract implementation named ''org.eclipse.emf.compare.rcp.ui.internal.structuremergeviewer.groups.impl.AbstractDifferenceGroupProvider'' is available in the ''org.eclipse.emf.compare.rcp.ui'' plugin. With this abstract implementation, all you have to do is to subclass it and implements the ''getGroups()'' method.
+
+For example, the ''By Kind'' group provider has 4 groups: Additions, Deletions, Changes and Moves.
+
+A defaul implementation named ''org.eclipse.emf.compare.rcp.ui.internal.structuremergeviewer.groups.BasicDifferenceGroupImpl'' is available in the ''org.eclipse.emf.compare.rcp.ui'' plugin. With this default implementation, all you have to do is to subclass it and overrides the ''getChildren()'' method.
+
+PENDING customize display of custom differences, add custom menu entries, add export options, provide custom content viewer
 
 == Using The Compare APIs ==
 
@@ -600,13 +782,13 @@ Let's use a complex example as reference. Consider the three following models:
 |-
 ! colspan="2" align="center" | Origin
 |-
-| colspan="2" align="center" | [[Image:images/EMF_Compare_Origin_Model.png|center]]
+| colspan="2" align="center" | [[Image:./../images/EMF_Compare_Origin_Model.png|center]]
 |-
 ! align="center" | Left
 ! align="center" | Right
 |-
-| [[Image:images/EMF_Compare_Use_Compare_Master.png|center]]
-| [[Image:images/EMF_Compare_Use_Compare_5.png|center]]
+| [[Image:./../images/EMF_Compare_Use_Compare_Master.png|center]]
+| [[Image:./../images/EMF_Compare_Use_Compare_5.png|center]]
 |}
 
 ==== All differences ====
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/CompareUI.png b/plugins/org.eclipse.emf.compare.doc/src/images/CompareUI.png
deleted file mode 100644
index 846a52457..000000000
--- a/plugins/org.eclipse.emf.compare.doc/src/images/CompareUI.png
+++ /dev/null
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/Diag_comp_diff.png b/plugins/org.eclipse.emf.compare.doc/src/images/Diag_comp_diff.png
deleted file mode 100644
index 5e4a2dddd..000000000
--- a/plugins/org.eclipse.emf.compare.doc/src/images/Diag_comp_diff.png
+++ /dev/null
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Developer_New_Extension_Filter.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Developer_New_Extension_Filter.png
new file mode 100644
index 000000000..17d2ff0e7
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Developer_New_Extension_Filter.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Developer_New_Extension_Group.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Developer_New_Extension_Group.png
new file mode 100644
index 000000000..a14da7a9f
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Developer_New_Extension_Group.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Graphical_AddClassA.PNG b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Graphical_AddClassA.PNG
new file mode 100644
index 000000000..77920e5c5
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Graphical_AddClassA.PNG
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Graphical_Nested_Phantom.GIF b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Graphical_Nested_Phantom.GIF
new file mode 100644
index 000000000..36db9382c
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Graphical_Nested_Phantom.GIF
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Graphical_Phantom.GIF b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Graphical_Phantom.GIF
new file mode 100644
index 000000000..575e30a98
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Graphical_Phantom.GIF
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Choice.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Choice.png
index a17fcbeb6..8c35077d7 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Choice.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Choice.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Default.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Default.png
index 3e78a5bbe..76989cec8 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Default.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Default.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Kind.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Kind.png
index 512f7a7a0..891024bdd 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Kind.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Kind.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Resource.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Resource.png
new file mode 100644
index 000000000..18b81de71
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Resource.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Side.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Side.png
index 301b942c6..0c5ee944f 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Side.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Side.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Handling_Conflict_1.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Handling_Conflict_1.png
new file mode 100644
index 000000000..d752b5b53
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Handling_Conflict_1.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Handling_Conflict_2.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Handling_Conflict_2.png
new file mode 100644
index 000000000..96ae6ac00
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Handling_Conflict_2.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge.png
index 6179809ca..5484fa0f9 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge_Book_Ancestor.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge_Book_Ancestor.png
index d2d62cc20..b4b6411cc 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge_Book_Ancestor.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge_Book_Ancestor.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merged.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merged.png
index e760a5041..367b505d3 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merged.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merged.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Select_Common_Ancestor.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Select_Common_Ancestor.png
new file mode 100644
index 000000000..42e7ac7c7
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Select_Common_Ancestor.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Text_Compare.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Text_Compare.png
index fe6cfe76c..a3a8d436b 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Text_Compare.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Text_Compare.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Association.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Association.png
new file mode 100644
index 000000000..e4d3dc86c
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Association.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Association_2.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Association_2.png
new file mode 100644
index 000000000..1d0cb02d1
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Association_2.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Association_3.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Association_3.png
new file mode 100644
index 000000000..5b7ab8d56
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Association_3.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Filter.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Filter.png
new file mode 100644
index 000000000..492e89407
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_UML_Filter.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_2.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_2.png
index 782b2b389..aac3a20c5 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_2.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_2.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_3.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_3.png
index 46b685086..37ff7ca0d 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_3.png
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_3.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_User_Interface.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_User_Interface.png
new file mode 100644
index 000000000..649b5eb4a
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_User_Interface.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_User_Interface_Toolbar.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_User_Interface_Toolbar.png
new file mode 100644
index 000000000..d5dd36ca1
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_User_Interface_Toolbar.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_User_Interface_Toolbar_With_Read_Only_Side.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_User_Interface_Toolbar_With_Read_Only_Side.png
new file mode 100644
index 000000000..7407ea9bc
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_User_Interface_Toolbar_With_Read_Only_Side.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_With_Each_Other.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_With_Each_Other.png
new file mode 100644
index 000000000..b07f57933
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_With_Each_Other.png
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/accept_all_changes.gif b/plugins/org.eclipse.emf.compare.doc/src/images/accept_all_changes.gif
new file mode 100644
index 000000000..d316c1e48
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/accept_all_changes.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/accept_change.gif b/plugins/org.eclipse.emf.compare.doc/src/images/accept_change.gif
new file mode 100644
index 000000000..2a98334f2
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/accept_change.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/add_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/add_ov.gif
new file mode 100644
index 000000000..c123a2b13
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/add_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/chg_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/chg_ov.gif
new file mode 100644
index 000000000..2b1b8d677
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/chg_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/confadd_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/confadd_ov.gif
new file mode 100644
index 000000000..d9b1a7d1c
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/confadd_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/confchg_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/confchg_ov.gif
new file mode 100644
index 000000000..f2a643a83
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/confchg_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/confdel_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/confdel_ov.gif
new file mode 100644
index 000000000..8af03a023
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/confdel_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/confr_add_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/confr_add_ov.gif
new file mode 100644
index 000000000..e7932dc29
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/confr_add_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/confr_chg_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/confr_chg_ov.gif
new file mode 100644
index 000000000..84b1e95d1
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/confr_chg_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/confr_del_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/confr_del_ov.gif
new file mode 100644
index 000000000..58b76b364
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/confr_del_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/del_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/del_ov.gif
new file mode 100644
index 000000000..ef0207c62
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/del_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/merged_left_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/merged_left_ov.gif
new file mode 100644
index 000000000..3e9bc69ba
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/merged_left_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/merged_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/merged_ov.gif
new file mode 100644
index 000000000..d946dc9c1
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/merged_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/merged_right_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/merged_right_ov.gif
new file mode 100644
index 000000000..58af52093
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/merged_right_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/pconfadd_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/pconfadd_ov.gif
new file mode 100644
index 000000000..aaea1d99c
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/pconfadd_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/pconfchg_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/pconfchg_ov.gif
new file mode 100644
index 000000000..d229c2fc5
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/pconfchg_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/pconfdel_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/pconfdel_ov.gif
new file mode 100644
index 000000000..659725a48
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/pconfdel_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/pconfr_add_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/pconfr_add_ov.gif
new file mode 100644
index 000000000..572901f0f
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/pconfr_add_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/pconfr_chg_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/pconfr_chg_ov.gif
new file mode 100644
index 000000000..c82c1edcf
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/pconfr_chg_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/pconfr_del_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/pconfr_del_ov.gif
new file mode 100644
index 000000000..82a62931e
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/pconfr_del_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/r_inadd_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/r_inadd_ov.gif
new file mode 100644
index 000000000..0ac0cea9e
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/r_inadd_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/r_inchg_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/r_inchg_ov.gif
new file mode 100644
index 000000000..c330c0c9f
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/r_inchg_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/r_indel_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/r_indel_ov.gif
new file mode 100644
index 000000000..5acab6778
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/r_indel_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/r_outadd_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/r_outadd_ov.gif
new file mode 100644
index 000000000..69607651f
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/r_outadd_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/r_outchg_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/r_outchg_ov.gif
new file mode 100644
index 000000000..17ba1af4f
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/r_outchg_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/r_outdel_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/r_outdel_ov.gif
new file mode 100644
index 000000000..ef6b8b745
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/r_outdel_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/images/removed_ov.gif b/plugins/org.eclipse.emf.compare.doc/src/images/removed_ov.gif
new file mode 100644
index 000000000..03f6227f9
--- /dev/null
+++ b/plugins/org.eclipse.emf.compare.doc/src/images/removed_ov.gif
diff --git a/plugins/org.eclipse.emf.compare.doc/src/resources/custom.css b/plugins/org.eclipse.emf.compare.doc/src/resources/custom.css
index 7bc3b38d1..f04391cec 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/resources/custom.css
+++ b/plugins/org.eclipse.emf.compare.doc/src/resources/custom.css
@@ -36,6 +36,11 @@ img {
 	margin-bottom: 2em;
 	display: block;
 }
+li img {
+	box-shadow: none;
+	display: inline;
+	margin: 0 auto;
+}
 pre {
 	left:50px;
 	width:90%;
diff --git a/plugins/org.eclipse.emf.compare.doc/src/user/sample-use-case.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/user/sample-use-case.mediawiki
index 3ba7a571c..08d674f9f 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/user/sample-use-case.mediawiki
+++ b/plugins/org.eclipse.emf.compare.doc/src/user/sample-use-case.mediawiki
@@ -1,124 +1,124 @@
-= Sample use case =
-
-With the following, we'll follow the life cycle of a metamodel describing a very basic library as it evolves separately in different branches. This will allow us to give more concrete examples of how EMF Compare can be used, and how it can help you.
-
-== Creating a model ==
-
-For this test, we'll suppose that you are trying to use EMF Compare on UML models shared under git. This will not go in details about UML and Git. We'll assume that you know how to manipulate an UML model, create or clone a git repository, share a project under it and use standard Git operations.
-
-The name of our sample project will be "library". It contains a single folder "model" containing two models :
-* library_Types.uml will contain our primitive types,
-* library.uml will contain our actual model.
-
-The two models will be commited to our git clone. The whole thing looks like this :
-
-[[Image:../images/EMF_Compare_Use_Setup.png]]
-
-The model itself is a very simple library. Graphically speaking :
-
-[[Image:../images/EMF_Compare_Use_Model.png]]
-
-Now that this initial model file has been committed, we'd like to improve it a little. For example :
-* Add an ''alias'' property to the ''Writer'' class,
-* Add a new ''History'' Category,
-* Rename the ''pages'' property of ''Book'' into ''length''.
-
-Our model now looks like this :
-
-[[Image:../images/EMF_Compare_Use_Model_Changed.png]]
-
-But how do we know exactly what changed? Let's compare this with the file from the Git Index :
-
-[[Image:../images/EMF_Compare_Use_Compare_1.png]]
-
-This will open a comparison editor that initially looks like the following :
-
-[[Image:../images/EMF_Compare_Use_Compare_2.png]]
-
-There are three main areas of interest in this editor.
-# Displays a structured list of the differences detected between the current version of the model and the version that lies in the Git Index.
-# This will react to the selections in (1) and display the ''left'' side of this comparison. As a rule of thumb, the ''left'' is the ''local'' version of the model. In this example, ''left'' will then be the version we have modified in our workspace. This is originally empty, more on this section in the example just below.
-# As above, this will react to selections in (1), but this time it will display the ''right'' side of the comparison. This is generally the ''remote'' version of the model; the version to which we've compared ours. In this case, this will represent the version of the model as it is in the Git Index. This is originally empty, more on this section in the example just below.
-
-As stated above, (2) and (3) are initially empty. These two panels are there to display more information about the differences detected between our models. Let's select one of the differences displayed in (1) :
-
-[[Image:../images/EMF_Compare_Use_Compare_3.png]]
-
-# We've selected the difference corresponding to the addition of attribute '''alias''' in the class '''Writer'''. A double-click on this difference updated our two panes below.
-# '''alias''' has been added to the properties of Class '''Writer'''. In the model, this corresponds to a change to the reference ''ownedAttributes'' of the ''Writer'' Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context.
-# This displays all values of the reference outlined in (2) as they are in the ''left'' model. This is where we see the new value, '''alias''' outlined.
-# As for (2), this will display the context of the selected difference. The same reference will usually be displayed in both (2) and (4).
-# This panel displays all values of the reference outlined in (4) as they are in the ''right'' model. In here, we see the location of '''alias''' outlined as an empty space. This rectangle is where the new value will be added if we merge it... Though in this case, it is not possible to merge towards the ''right'' : it is a version located on a repository and is thus non-editable.
-
-This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes.
-
-== Branching ==
-
-Now, we'd like to create a new feature for our library : we'd like clients to be able to borrow our books. We'll branch our repository in order to create this new feature and name this new branch ''borrowables'' :
-
-[[Image:../images/EMF_Compare_Use_Compare_4.png]]
-
-Starting right away, we add the necessary new concepts to our model to represent the possibility of lending books. We "may" later need to have more than books to be lendable, so let's make a ''Borrowable'' interface to hold this concept. We'll also need a ''Person'' class, as well as a new data type to represent the person's birth date :
-
-[[Image:../images/EMF_Compare_Use_Compare_5.png]]
-
-In a tree viewer, our models now look like (highlighted in red, the concepts we added with this step) :
-
-[[Image:../images/EMF_Compare_Use_Compare_6.png]]
-
-However, while we are working on our ''borrowables'' branch, the ''master'' branch may still evolve : other people on the project might be adding new concepts of their own, or we could be switching to the main branch for a high priority fix ourselves. Let's imagine that two features have been added since we branched our repository. First, someone needed to have the library hold not only Books, but also Magazines. Second, we needed the publication date of our Books and magazines to be recorded.
-
-The first of these two commits will add the following concepts to our ''master'' branch's model :
-
-[[Image:../images/EMF_Compare_Use_Compare_7.png]]
-
-While the second only adds a primitive type and a property :
-
-[[Image:../images/EMF_Compare_Use_Compare_8.png]]
-
-== Merge ==
-
-If you have followed to this point, we now have two diverging branches, ''master'' and ''borrowables'' which both hold a different version of our ''library.uml'' model. Here is how these two models look like at this point :
-
-{| border="1" cellpadding="5" cellspacing="0" align="center"
-|-
-! align="center" | Master
-! align="center" | Borrowables
-|-
-| [[Image:../images/EMF_Compare_Use_Compare_Master.png|center]]
-| [[Image:../images/EMF_Compare_Use_Compare_5.png|center]]
-|}
-
-Before we continue working on our Borrowables branch, we'd like to retrieve all modifications that have been pushed to master. With the "Borrowables" branch checked out, we'll use the ''Compare With > Branch, Tag or Reference'' action :
-
-[[Image:../images/EMF_Compare_Use_Compare_With_Master_1.png|center]]
-
-and compare with master :
-
-[[Image:../images/EMF_Compare_Use_Compare_With_Master_2.png|center]]
-
-This shows us all differences between our local copy and the master branch that were made since the 'branching' point.
-
-[[Image:../images/EMF_Compare_Merge.png|center]]
-
-Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. '''Regular''' elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are '''incoming''' differences, decorated with a blue arrow ([[Image:../images/EMF_Compare_Incoming_Change.gif]]) or a derived icon, and '''outgoing''' differences decorated with a green arrow ([[Image:../images/EMF_Compare_Outgoing_Change.gif]]) or a derived icon.
-
- * '''Incoming''' differences are changes that were made in the remote branch (here, ''master'') since the branching point (common ancestor).
- * '''Outgoing''' differences are changes taht were made in the local copy (here, the ''borrowables'' branch) since the branching point.
-
-There are no conflicts here, since UML uses computed identifiers (XMI ID) for the model elements. Thus, what looks like a conflict (the "Date" type that's been added on both branch in the types packages) is actually two distinct differences.
-
-The interface also lets you display the common ancestor of both models through the [[Image:../images/EMF_Compare_Ancestor.gif]] icon. For example, if we select the '''Book''' class, we can see how it looks like on all three versions :
-
-[[Image:../images/EMF_Compare_Merge_Book_Ancestor.png|center]]
-
-You can navigate through the differences using the appropriate actions, either the previous ([[Image:../images/EMF_Compare_Prev_Diff.gif]]) or the next ([[Image:../images/EMF_Compare_Next_Diff.gif]]) difference.
-
-The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through [[Image:../images/EMF_Compare_Copy_All.gif]] or merge them one after the other through [[Image:../images/EMF_Compare_Copy.gif]].
-
-Merging '''all''' differences is not what we seek : we want to keep the changes we made locally, not revert them to the state they had before the branching point (which is their current state on ''master'', the right side). We will then select all ''incoming'' differences one after the other and merge them one by one. This gives us our merged model :
-
-[[Image:../images/EMF_Compare_Merged.png|center]]
-
-Notice that ''merged'' differences are displayed in ''italics'' and have a distinct icon. All that's left is to save, our model now contains both our local changes and the changes that were made on master.
-
+= Sample use case =

+

+With the following, we'll follow the life cycle of a metamodel describing a very basic library as it evolves separately in different branches. This will allow us to give more concrete examples of how EMF Compare can be used, and how it can help you.

+

+== Creating a model ==

+

+For this test, we'll suppose that you are trying to use EMF Compare on UML models shared under git. This will not go in details about UML and Git. We'll assume that you know how to manipulate an UML model, create or clone a git repository, share a project under it and use standard Git operations.

+

+The name of our sample project will be "library". It contains a single folder "model" containing two models :

+* library_Types.uml will contain our primitive types,

+* library.uml will contain our actual model.

+

+The two models will be commited to our git clone. The whole thing looks like this :

+

+[[Image:../images/EMF_Compare_Use_Setup.png]]

+

+The model itself is a very simple library. Graphically speaking :

+

+[[Image:../images/EMF_Compare_Use_Model.png]]

+

+Now that this initial model file has been committed, we'd like to improve it a little. For example :

+* Add an ''alias'' property to the ''Writer'' class,

+* Add a new ''History'' Category,

+* Rename the ''pages'' property of ''Book'' into ''length''.

+

+Our model now looks like this :

+

+[[Image:../images/EMF_Compare_Use_Model_Changed.png]]

+

+But how do we know exactly what changed? Let's compare this with the file from the Git Index :

+

+[[Image:../images/EMF_Compare_Use_Compare_1.png]]

+

+This will open a comparison editor that initially looks like the following :

+

+[[Image:../images/EMF_Compare_Use_Compare_2.png]]

+

+There are three main areas of interest in this editor.

+# Displays a structured list of the differences detected between the current version of the model and the version that lies in the Git Index.

+# This will react to the selections in (1) and display the ''left'' side of this comparison. As a rule of thumb, the ''left'' is the ''local'' version of the model. In this example, ''left'' will then be the version we have modified in our workspace. This is originally filled with the first difference that is selected in the top panel (1), more on this section in the example just below.

+# As above, this will react to selections in (1), but this time it will display the ''right'' side of the comparison. This is generally the ''remote'' version of the model; the version to which we've compared ours. In this case, this will represent the version of the model as it is in the Git Index. This is originally empty, more on this section in the example just below.

+

+As stated above, (2) and (3) are initially filled with the values of the difference selected in the top panel (1). These two panels are there to display more information about the differences detected between our models. Let's select another difference displayed in (1) :

+

+[[Image:../images/EMF_Compare_Use_Compare_3.png]]

+

+# We've selected the difference corresponding to the addition of attribute '''alias''' in the class '''Writer'''. A double-click on this difference updated our two panes below.

+# '''alias''' has been added to the properties of Class '''Writer'''. In the model, this corresponds to a change to the reference ''ownedAttributes'' of the ''Writer'' Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context.

+# This displays all values of the reference outlined in (2) as they are in the ''left'' model. This is where we see the new value, '''alias''' outlined.

+# As for (2), this will display the context of the selected difference. The same reference will usually be displayed in both (2) and (4).

+# This panel displays all values of the reference outlined in (4) as they are in the ''right'' model. In here, we see the location of '''alias''' outlined as an empty space. This rectangle is where the new value will be added if we merge it... Though in this case, it is not possible to merge towards the ''right'' : it is a version located on a repository and is thus non-editable.

+

+This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes.

+

+== Branching ==

+

+Now, we'd like to create a new feature for our library : we'd like clients to be able to borrow our books. We'll branch our repository in order to create this new feature and name this new branch ''borrowables'' :

+

+[[Image:../images/EMF_Compare_Use_Compare_4.png]]

+

+Starting right away, we add the necessary new concepts to our model to represent the possibility of lending books. We "may" later need to have more than books to be lendable, so let's make a ''Borrowable'' interface to hold this concept. We'll also need a ''Person'' class, as well as a new data type to represent the person's birth date :

+

+[[Image:../images/EMF_Compare_Use_Compare_5.png]]

+

+In a tree viewer, our models now look like (highlighted in red, the concepts we added with this step) :

+

+[[Image:../images/EMF_Compare_Use_Compare_6.png]]

+

+However, while we are working on our ''borrowables'' branch, the ''master'' branch may still evolve : other people on the project might be adding new concepts of their own, or we could be switching to the main branch for a high priority fix ourselves. Let's imagine that two features have been added since we branched our repository. First, someone needed to have the library hold not only Books, but also Magazines. Second, we needed the publication date of our Books and magazines to be recorded.

+

+The first of these two commits will add the following concepts to our ''master'' branch's model :

+

+[[Image:../images/EMF_Compare_Use_Compare_7.png]]

+

+While the second only adds a primitive type and a property :

+

+[[Image:../images/EMF_Compare_Use_Compare_8.png]]

+

+== Merge ==

+

+If you have followed to this point, we now have two diverging branches, ''master'' and ''borrowables'' which both hold a different version of our ''library.uml'' model. Here is how these two models look like at this point :

+

+{| border="1" cellpadding="5" cellspacing="0" align="center"

+|-

+! align="center" | Master

+! align="center" | Borrowables

+|-

+| [[Image:../images/EMF_Compare_Use_Compare_Master.png|center]]

+| [[Image:../images/EMF_Compare_Use_Compare_5.png|center]]

+|}

+

+Before we continue working on our Borrowables branch, we'd like to retrieve all modifications that have been pushed to master. With the "Borrowables" branch checked out, we'll use the ''Compare With > Branch, Tag or Reference'' action :

+

+[[Image:../images/EMF_Compare_Use_Compare_With_Master_1.png|center]]

+

+and compare with master :

+

+[[Image:../images/EMF_Compare_Use_Compare_With_Master_2.png|center]]

+

+This shows us all differences between our local copy and the master branch that were made since the 'branching' point.

+

+[[Image:../images/EMF_Compare_Merge.png|center]]

+

+Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. '''Regular''' elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are '''incoming''' differences, decorated with a blue arrow ([[Image:../images/EMF_Compare_Incoming_Change.gif]]) or a derived icon, and '''outgoing''' differences decorated with a green arrow ([[Image:../images/EMF_Compare_Outgoing_Change.gif]]) or a derived icon.

+

+ * '''Incoming''' differences are changes that were made in the remote branch (here, ''master'') since the branching point (common ancestor).

+ * '''Outgoing''' differences are changes taht were made in the local copy (here, the ''borrowables'' branch) since the branching point.

+

+There are no conflicts here, since UML uses computed identifiers (XMI ID) for the model elements. Thus, what looks like a conflict (the "Date" type that's been added on both branch in the types packages) is actually two distinct differences.

+

+The interface also lets you display the common ancestor of both models through the [[Image:../images/EMF_Compare_Ancestor.gif]] icon. For example, if we select the '''Book''' class, we can see how it looks like on all three versions :

+

+[[Image:../images/EMF_Compare_Merge_Book_Ancestor.png|center]]

+

+You can navigate through the differences using the appropriate actions, either the previous ([[Image:../images/EMF_Compare_Prev_Diff.gif]]) or the next ([[Image:../images/EMF_Compare_Next_Diff.gif]]) difference.

+

+The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through [[Image:../images/EMF_Compare_Copy_All.gif]] or merge them one after the other through [[Image:../images/EMF_Compare_Copy.gif]].

+

+Merging '''all''' differences is not what we seek : we want to keep the changes we made locally, not revert them to the state they had before the branching point (which is their current state on ''master'', the right side). We will then select all ''incoming'' differences one after the other and merge them one by one. This gives us our merged model :

+

+[[Image:../images/EMF_Compare_Merged.png|center]]

+

+Notice that ''merged'' differences are displayed in ''italics'' and have a distinct icon. All that's left is to save, our model now contains both our local changes and the changes that were made on master.

+

diff --git a/plugins/org.eclipse.emf.compare.doc/src/user/user-guide.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/user/user-guide.mediawiki
index 0e9cb577d..d8cdde54d 100644
--- a/plugins/org.eclipse.emf.compare.doc/src/user/user-guide.mediawiki
+++ b/plugins/org.eclipse.emf.compare.doc/src/user/user-guide.mediawiki
@@ -8,7 +8,7 @@
 
 Using the bundled Eclipse marketplace client you can install EMF Compare in one click. Just type "emf compare", click on search, and then on install. 
 
-[[Image:images/Marketplace.png]] 
+[[Image:./../images/Marketplace.png]] 
 
 '''Update Site'''
 
@@ -111,25 +111,110 @@ An empty cell indicates that the compatibility hasn't been tested for a particul
 
 The main points of interest are highlighted in the following picture :
 
-[[Image:images/CompareUI.png|center|EMF Compare's basic user interface]]
+[[Image:./../images/EMF_Compare_User_Interface.png|center|EMF Compare's basic user interface]]
 
 # Overview of the differences detected between the given two (or three) models.
 # First version of the compared models.
 # Second version of the compared models.
 # This button will only be visible in the case of three-way comparisons (for example, comparing with a remote repository). It will make a third version of the compared model (the common ancestor of the two others) visible in the interface.
-# This button will allow you to group differences together in the structural view. For example, grouping all "Additions" or "Deletions" together.
-# This button will allow you to filter some differences out of the view according to a set predicate. For example, filtering out all "Additions" or "Moves".
-# Allows you to merge all non conflicting differences (left to right, or right to left) at once.
+# When you select a difference in the top panel, the consequences of the merge of this difference are highlighted in green and red. 
+#* The consequences highlighted in <span style="color:green">green</span>  are the differences that will be merge with the selected difference.
+#* The consequences highlighted in <span style="color:red">red</span>  are the differences that will be not "mergeable" after the merge of the selected difference.
+#* A click on a <span style="color:green">green</span> or <span style="color:red">red</span> rectangle in the right gutter will lead you to the concerned consequence.
+
+==== Toolbar ====
+
+The toolbar displays the current status of the comparison and allows you to act on differences.
+
+[[Image:./../images/EMF_Compare_User_Interface_Toolbar.png|center|EMF Compare's user interface toolbar]]
+
+# Gives the number of differences still to be merged, and the number of differences filtered from the view.
+# Allows to change the direction of consequences that are highlighted in green and red in the top panel. You can either display the consequences of a merge from left to right or right to left.
 # Allows you to merge the single, currently selected difference in a given direction (left to right, or right to left).
+# Allows you to merge all non conflicting differences (left to right, or right to left) at once.
 # Allows you to navigate through the detected differences.
+# Allows to expand/collapse all differences in the top panel.
+# This button will allow you to group differences together in the structural view. For example, grouping all "Additions" or "Deletions" together.
+# This button will allow you to filter some differences out of the view according to a set predicate. For example, filtering out all "Additions" or "Moves".
+# Allows to save the comparison model.
+
+When you compare models with one in a read-only mode, some of actions proposed by the toolbar are slightly different. Indeed, if you compare a model with the local history, or you compare a model with a remote model stored in a repository, the latter is in a read-only mode. You will not able to merge differences to this read-only model. You will only accept or reject changes for your local model.
+
+[[Image:./../images/EMF_Compare_User_Interface_Toolbar_With_Read_Only_Side.png|center|EMF Compare's user interface toolbar]]
+
+# Allows to change the kind of consequences that are highlighted in green and red in the top panel. You can either display the consequences of accepting/rejecting the selected change.
+# Allows you to accept the single, currently selected change.
+# Allows you to reject the single, currently selected change.
+# Allows you to accept all non conflicting changes at once.
+# Allows you to reject all non conflicting changes at once.
+
+==== Signification of icons associated with differences ====
+
+When you run a comparison involving two models (a 2-way comparison), the icons associated with differences are:
+
+* [[Image:./../images/add_ov.gif|Addition]] represent an addition in the left side model of the comparison.
+* [[Image:./../images/del_ov.gif|Deletion]] represent a deletion in the left side model of the comparison.
+* [[Image:./../images/chg_ov.gif|Change]] represent a change (set/unset/move) in the left side model of the comparison.
+
+When you run a comparison involving three models (a 3-way comparison), the icons associated with differences are:
+
+*[[Image:./../images/r_inchg_ov.gif|Incoming change]] incoming differences are changes that were made in the right-side/remote model since common ancestor.
+*[[Image:./../images/r_outchg_ov.gif|Outgoing change]] outgoing differences are changes that were made in the left-side/local model since common ancestor.
+*[[Image:./../images/r_inadd_ov.gif|Incoming addition]] represent an incoming addition difference.
+*[[Image:./../images/r_indel_ov.gif|Incoming deletion]] represent an incoming deletion difference.
+*[[Image:./../images/r_outadd_ov.gif|Outgoing addition]] represent an outgoing addition difference.
+*[[Image:./../images/r_outdel_ov.gif|Outgoing deletion]] represent an outgoing deletion difference.
+*[[Image:./../images/confr_chg_ov.gif|Incoming conflict]] incoming conflict differences are changes that were made in the right-side/remote model since common ancestor, and are in conflict with the left-side/local model.
+*[[Image:./../images/confchg_ov.gif|Outgoing conflict]] outgoing conflict differences are changes that were made in the right-side/remote model since common ancestor, and are in conflict with the right-side/remote model.
+*[[Image:./../images/confr_add_ov.gif|Incoming conflict addition]] represent an incoming addition conflict.
+*[[Image:./../images/confr_del_ov.gif|Incoming conflict deletion]] represent an incoming deletion conflict.
+*[[Image:./../images/confadd_ov.gif|Outgoing conflict addition]] represent an outgoing addition conflict.
+*[[Image:./../images/confdel_ov.gif|Outgoing conflict deletion]] represent an outgoing deletion conflict.
+*[[Image:./../images/pconfr_chg_ov.gif|Incoming pseudo conflict]] incoming pseudo conflict differences are changes that were made in the right-side/remote model since common ancestor, and are in pseudo conflict with the left-side/local model.
+*[[Image:./../images/pconfchg_ov.gif|Outgoing pseudo conflict]] outgoing pseudo conflict differences are changes that were made in the right-side/remote model since common ancestor, and are in pseudo conflict with the right-side/remote model.
+*[[Image:./../images/pconfr_add_ov.gif|Incoming pseudo conflict addition]] represent an incoming pseudo conflict addition.
+*[[Image:./../images/pconfr_del_ov.gif|Incoming pseudo conflict deletion]] represent an incoming pseudo conflict deletion.
+*[[Image:./../images/pconfadd_ov.gif|Outgoing pseudo conflict addition]] represent an outgoing pseudo conflict addition.
+*[[Image:./../images/pconfdel_ov.gif|Outgoing pseudo conflict deletion]] represent an outgoing pseudo conflict deletion.
 
-=== Usage ===
+==== After merge ====
 
-Once installed, you can compare your files (locally or from any Version Control System) as usual using the '''compare with''' menu.
+The ''merged'' differences are displayed in <span style="color:gray">gray</span> and have a distinct icon.
 
-[[Image:images/EMFC_Compare_With.png|center]]
+*[[Image:./../images/merged_left_ov.gif|Merged difference from right to left]] represent a difference that has been merged from right to left.
+*[[Image:./../images/merged_right_ov.gif|Merged difference from left to right]] represent a difference that has been merged from left to right.
 
-The following displays the important part of a model life cycle with regards to the comparison. The full life cycle can be followed on [[./Sample%20Use%20Case.html| Sample Use Case]]
+When you compare models with one in a read-only mode, the icons are:
+
+*[[Image:./../images/merged_ov.gif|Accepted change]] represent a change that has been accepted.
+*[[Image:./../images/removed_ov.gif|Rejected change]] represent a change that has been rejected.
+
+
+== Launch Comparison ==
+
+Once installed, you can compare your files (locally or from any Version Control System) as usual using the '''Compare With''' menu.
+
+=== Compare with local models ===
+
+==== Compare with each other ====
+
+You can compare two or three models by selecting them and then using the '''Compare With > Each Other''' menu:
+
+[[Image:./../images/EMF_Compare_With_Each_Other.png|center]]
+
+If you run a 3-way comparison (with 3 models), you have to select the ancestor of the comparison:
+
+[[Image:./../images/EMF_Compare_Select_Common_Ancestor.png|center]]
+
+==== Compare with local history ====
+
+You can also compare your local model with one of its previous version available in the local history. For that, use the '''Compare With > Local History''' menu:
+
+[[Image:./../images/EMFC_Compare_With.png|center]]
+
+=== Compare with remote models ===
+
+The following displays the important part of a model life cycle with regards to the comparison. The full life cycle can be followed on [[./sample-use-case.html| Sample Use Case]]
 
 ==== Compare with latest ====
 
@@ -141,27 +226,28 @@ The name of our sample project will be "library". It contains a single folder "m
 
 The model itself is a very simple library. Graphically speaking :
 
-[[Image:images/EMF_Compare_Use_Model.png]]
+[[Image:./../images/EMF_Compare_Use_Model.png]]
 
 We commit this initial file as the original model. We then slightly modify it so that it now looks like :
 
-[[Image:images/EMF_Compare_Use_Model_Changed.png]]
+[[Image:./../images/EMF_Compare_Use_Model_Changed.png]]
 
 But how do we know exactly what changed? Let's compare this with the file from the Git Index :
 
-[[Image:images/EMF_Compare_Use_Compare_1.png]]
+[[Image:./../images/EMF_Compare_Use_Compare_1.png]]
 
-This will open a comparison editor that initially displays empty panels on its bottom half. Let's select one of the differences displayed on its top half :
+This will open a comparison editor. Let's select one of the differences displayed on its top half :
 
-[[Image:images/EMF_Compare_Use_Compare_3.png]]
+[[Image:./../images/EMF_Compare_Use_Compare_3.png]]
 
 # We've selected the difference corresponding to the addition of attribute '''alias''' in the class '''Writer'''. A double-click on this difference updated our two panes below.
 # '''alias''' has been added to the properties of Class '''Writer'''. In the model, this corresponds to a change to the reference ''ownedAttributes'' of the ''Writer'' Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context.
 # This displays all values of the reference outlined in (2) as they are in the ''left'' model. This is where we see the new value, '''alias''' outlined.
 # As for (2), this will display the context of the selected difference. The same reference will usually be displayed in both (2) and (4).
-# This panel displays all values of the reference outlined in (4) as they are in the ''right'' model. In here, we see the location of '''alias''' outlined as an empty space. This rectangle is where the new value will be added if we merge it... Though in this case, it is not possible to merge towards the ''right'' : it is a version located on a repository and is thus non-editable.
+# This panel displays all values of the reference outlined in (4) as they are in the ''right'' model. In here, we see the location of '''alias''' outlined as an empty space. This rectangle is where the new value will be added if we merge it. 
+In this case, it is possible to merge towards the ''right'' : the ''index'' version of the model is editable, like any other file in the index. If we merge this difference towards the ''right'', then it will exist an ''unstaged'' version of the model, and a ''staged'' version of the model, that will include the merged difference.
 
-This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes on the ''master'' branch.
+But this comparison with index is mainly useful in order to determine exactly what changed in our version. Let's commit our changes on the ''master'' branch.
 
 ==== Compare two differing branches ====
 
@@ -172,66 +258,65 @@ After that, our model can evolve, and evolve separately in multiple branches. Le
 ! align="center" | Master
 ! align="center" | Borrowables
 |-
-| [[Image:images/EMF_Compare_Use_Compare_Master.png|center]]
-| [[Image:images/EMF_Compare_Use_Compare_5.png|center]]
+| [[Image:./../images/EMF_Compare_Use_Compare_Master.png|center]]
+| [[Image:./../images/EMF_Compare_Use_Compare_5.png|center]]
 |}
 
 Before we continue working on our Borrowables branch, we'd like to retrieve all modifications that have been pushed to master. With the "Borrowables" branch checked out, we'll use the ''Compare With > Branch, Tag or Reference'' action :
 
-[[Image:images/EMF_Compare_Use_Compare_With_Master_1.png|center]]
+[[Image:./../images/EMF_Compare_Use_Compare_With_Master_1.png|center]]
 
 and compare with master :
 
-[[Image:images/EMF_Compare_Use_Compare_With_Master_2.png|center]]
+[[Image:./../images/EMF_Compare_Use_Compare_With_Master_2.png|center]]
 
 This shows us all differences between our local copy and the master branch that were made since the 'branching' point.
 
-[[Image:images/EMF_Compare_Merge.png|center]]
+[[Image:./../images/EMF_Compare_Merge.png|center]]
 
-Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. '''Regular''' elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are '''incoming''' differences, decorated with a blue arrow ([[Image:images/EMF_Compare_Incoming_Change.gif]]) or a derived icon, and '''outgoing''' differences decorated with a green arrow ([[Image:images/EMF_Compare_Outgoing_Change.gif]]) or a derived icon.
+Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. '''Regular''' elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are '''incoming''' differences, decorated with a blue arrow ([[Image:./../images/EMF_Compare_Incoming_Change.gif]]) or a derived icon, and '''outgoing''' differences decorated with a gray arrow ([[Image:./../images/EMF_Compare_Outgoing_Change.gif]]) or a derived icon.
 
 '''Incoming''' differences are changes that were made in the remote branch (here, ''master'') since the branching point (common ancestor).
 '''Outgoing''' differences are changes taht were made in the local copy (here, the ''borrowables'' branch) since the branching point.
 
 There are no conflicts here, since UML uses computed identifiers (XMI ID) for the model elements. Thus, what looks like a conflict (the "Date" type that's been added on both branch in the types packages) is actually two distinct differences.
 
-The interface also lets you display the common ancestor of both models through the [[Image:images/EMF_Compare_Ancestor.gif]] icon. For example, if we select the '''Book''' class, we can see how it looks like on all three versions :
+The interface also lets you display the common ancestor of both models through the [[Image:./../images/EMF_Compare_Ancestor.gif]] icon. For example, if we select the '''Book''' class, we can see how it looks like on all three versions :
 
-[[Image:images/EMF_Compare_Merge_Book_Ancestor.png|center]]
+[[Image:./../images/EMF_Compare_Merge_Book_Ancestor.png|center]]
 
-You can navigate through the differences using the appropriate actions, either the previous ([[Image:images/EMF_Compare_Prev_Diff.gif]]) or the next ([[Image:images/EMF_Compare_Next_Diff.gif]]) difference.
+You can navigate through the differences using the appropriate actions, either the previous ([[Image:./../images/EMF_Compare_Prev_Diff.gif]]) or the next ([[Image:./../images/EMF_Compare_Next_Diff.gif]]) difference.
 
-The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through [[Image:images/EMF_Compare_Copy_All.gif]] or merge them one after the other through [[Image:images/EMF_Compare_Copy.gif]].
+The remaining two actions are those that actually interest us here we can either accept all non-conflicting differences to the local copy through [[Image:./../images/accept_all_changes.gif]] or accept them one after the other through [[Image:./../images/accept_change.gif]].
 
-Merging '''all''' differences is not what we seek : we want to keep the changes we made locally, not revert them to the state they had before the branching point (which is their current state on ''master'', the right side). We will then select all ''incoming'' differences one after the other and merge them one by one. This gives us our merged model :
+Accept '''all''' differences is not what we seek : we want to keep the changes we made locally, not revert them to the state they had before the branching point (which is their current state on ''master'', the right side). We will then select all ''incoming'' differences (under the ''Right side'' node) one after the other and merge them one by one. This gives us our merged model :
 
-[[Image:images/EMF_Compare_Merged.png|center]]
-
-Notice that ''merged'' differences are displayed in ''italics'' and have a distinct icon. All that's left is to save, our model now contains both our local changes and the changes that were made on master.
+[[Image:./../images/EMF_Compare_Merged.png|center]]
 
 == Features ==
 
-=== Handling Conflicts  ===
-
-PENDING
-
 === Grouping Differences  ===
 
 This feature allows you to group differences together in the structural view according to a set predicate. By default, EMF Compare provides three distinct grouping strategies :
 
-[[Image:images/EMF_Compare_Groups_Choice.png]]
+[[Image:./../images/EMF_Compare_Groups_Choice.png]]
 
 ; Default : Do not try and group differences together, display them as they were detected.
 
-[[Image:images/EMF_Compare_Groups_Default.png]]
+[[Image:./../images/EMF_Compare_Groups_Default.png]]
 
 ; By Kind : Group differences by their kind (''additions'', ''deletions'', ''moves'', ''changes'').
 
-[[Image:images/EMF_Compare_Groups_Kind.png]]
+[[Image:./../images/EMF_Compare_Groups_Kind.png]]
+
+; By Side : Group differences according to their side: left or right and a special group regrouping differences in conflicts with other differences together. This grouping strategy is display by default in case of a 3-way comparison.
+
+[[Image:./../images/EMF_Compare_Groups_Side.png]]
 
-; By Side : Group differences according to their side: left or right and a special group regrouping differences in conflicts with other differences together.
+; By Resource : Group differences according to their resource: useful when more than two resources involved in comparison and/or resources are split into fragments. 
+
+[[Image:./../images/EMF_Compare_Groups_Resource.png]]
 
-[[Image:images/EMF_Compare_Groups_Side.png]]
 
 PENDING UPDATE, this is a demo displaying EMF Compare 1.3
 [http://www.eclipse.org/emf/compare/doc/features/videos/Groups/groups.htm Demo]
@@ -242,9 +327,9 @@ PENDING : New grouping strategies can be provided to EMF Compare through extensi
 
 This features allows you to filter differences out of the structural view according to a set predicate. By default, EMF Compare provides five distinct filters :
 
-[[Image:images/EMF_Compare_Filters_Choice.png]]
+[[Image:./../images/EMF_Compare_Filters_Choice.png]]
 
-; Pseudo conflicts differences : Filter out all pseudo conflicts differences(only in 3-way comparison). Enabled by default.
+; Pseudo conflicts differences : Filter out all pseudo conflicts differences (only in case of a 3-way comparison). Enabled by default.
 ; Identical elements : Filter out all identical elements (elements with no differences). Enabled by default.
 ; Empty Resource Mappings : Filter out all resource mappings with no differences from the view. Enabled by default.
 ; Cascading differences : Filter out all differences that are contained under differences (except when in conflict). Enabled by default.
@@ -254,44 +339,115 @@ PENDING UPDATE, this is a demo displaying EMF Compare 1.3
 
 PENDING : New filters can be provided to EMF Compare through extension points.
 
+=== Handling Conflicts  ===
+
+When a 3-way comparison has conflicts, all differences involved in the same conflict are grouped under a Confict node.
+
+In the following case, the Employee Green has his manager reference in conflict. The left side of the comparison shows that the manager of the Employee Green is the employee Smith while the right side side shows that the manager is the Employee Johnson.
+The consequences of a merge from right to left of the selected difference are displayed.
+
+When the left side difference ''Employee Smith [ manager changed ]'' is selected in the top panel, the right side difference ''Employee Johnson [ manager changed ]'' is highlighted in red, that means if the the left side difference ''Employee Smith [ manager changed ]'' is merged from right to left, then it will be impossible to merge the right side difference ''Employee Johnson [ manager changed ]'' from left to right.
+
+[[Image:./../images/EMF_Compare_Handling_Conflict_1.png]]
+
+After the merge of the left side difference from right to left ''Employee Smith [ manager changed ]'', the right side difference ''Employee Johnson [ manager changed ]'' is not "mergeable" from left to right anymore, it has been merged from right to left automatically.
+
+[[Image:./../images/EMF_Compare_Handling_Conflict_2.png]]
+
 === Text Attribute Comparison  ===
 
-Differences made into ''String''-typed attributes can be compared and merged directly as text from the compare interface through a simple right-click on the difference.
+In case of differences made on ''String''-typed attributes, specifics actions are available in the top-right of the content viewer panel.
 
-[[Image:images/EMF_Compare_Text_Compare.png]]
+[[Image:./../images/EMF_Compare_Text_Compare.png]]
+
+# Allows to merge all changes of the current difference.
+# Allows to merge the current change.
+# Allows to move to the next/previous textual difference (in case of multi-valuated ''String''-typed attributes).
+# Allows to move to next/previous change in the current textual difference.
 
 PENDING UPDATE, this demo displays EMF Compare 1.3
 [http://www.eclipse.org/emf/compare/doc/features/videos/Text%20compare/textCompare.htm Demo]
 
 === Graphical Comparison  ===
 
-PENDING UPDATE
+EMF compare provides the ability to compare models with Papyrus graphical modeler (GMF Diagrams). To get the graphical comparison, the ''EMF Compare Papyrus integration'' feature and Papyrus have to be installed.
+The graphical comparison will be launched if you compare diagrams files (.di), or if you compare models that have diagrams associated in the same folder.
+In the same way as the semantic model comparison, the graphical model comparison uses the same color coding, to distinguish <span style="color:blue">incoming</span> and <span style="color:gray">outgoing</span> changes, and <span style="color:red">conflicts</span>. To put in relief the graphical differences, some decorators are used:
+*On one hand, to focus on the impacted objects, identifying them with markers. These markers are simple transparent rectangles which are set down above the concerned objects and are lightly larger.
+*On the other hand, through phantoms (place-holders), to locate either the place where objects were deleted or the target location where objects should be added after merging.
+The color of the concerned decorators are highlighted on selection of the difference.
+
+In the following example, a 3-way comparison is run with UML class diagrams. We can see that a Shape associated to a semantic uml class named A has been added on the left side of the comparison. After selected the difference in top panel, we can see the concerned elements in down panels. In the left part, the Shape A is highlighted in gray because it is an incoming change. In the right part, a phantom is drawn at the place the Shape should be after merging from right to left.
+
+[[Image:./../images/EMF_Compare_Graphical_AddClassA.png]]
 
-Since the 1.2 release EMF compare provides the ability to compare models with graphical modelers. 
+About phantoms (place-holders):
+
+To ease their readability, in some cases, their context have to be displayed:
+*If they are nested in an other phantom (e.g. due to a delete of the parent object), this last contextual one is displayed at the same time as the main phantom concerned by the current selected change.
+*If they are edges connected to deleted nodes or edges, these last contextual ones are displayed at the same time as the main edge phantom.
+*The color of the contextual phantoms (dependencies) is not highlighted.
+They are drawn as:
+*A simple rectangle for nodes, at the same origin location (and size).
+*A simple line (with the same bend points) for edges, at the same location.
+*A simple line for nodes as element of containment list. For this case, the same LCS computation will be used to locate in the list, at the good index.
+*Particular cases: If the location of the contextual phantoms was changed, the new location of the main phantom is computed.
+**A node place-holder, related to a delete of a node, embedded in a node where the location changed.
+**An edge place-holder between nodes where the location changed. In this case, the display of the line is drawn again.
+
+
+Here is an example of nested phantom:
+* the first capture represent an addition of a lifeline in sequence diagram.
+
+[[Image:./../images/EMF_Compare_Graphical_Phantom.gif]]
+
+* the second capture represent an addition of an execution inside the lifeline. We can see the phantom of the execution element, which is highlighted and the phantom of the lifeline parent, which is not highlighted. 
+
+[[Image:./../images/EMF_Compare_Graphical_Nested_Phantom.gif]]
 
 Have a look on the following demos :
 
+PENDING update videos
+
 [[http://www.eclipse.org/emf/compare/doc/features/videos/EcoreTools-v2/EMFCompareEcoreTools.html | Demo : Comparing Ecore files with diagrams]] 
 
 [[http://www.eclipse.org/emf/compare/doc/features/videos/Papyrus/EMFComparePapyrus.html | Demo : Comparing UML files with diagrams]] 
 
-[[Image:images/Diag_comp_diff.png]]
-
 === Logical Model  ===
 
 EMF Compare does not act simply on the selected files, but on their whole logical model (a given model can be split through multiple files through EMF ''control'' action). Thanks to that, if you try and compare a model file that reference other model files, the comparison will still be able to take these "other" files into account. For example, if you try and compare a ''genmodel'' file (that depends on its underlying ''ecore'' file) :
 
-[[Image:images/EMF_Compare_Logical_Compare_Action.png]]
+[[Image:./../images/EMF_Compare_Logical_Compare_Action.png]]
 
 EMF Compare will actually consider both files when comparing :
 
-[[Image:images/EMF_Compare_Logical_Compare_Result.png]]
+[[Image:./../images/EMF_Compare_Logical_Compare_Result.png]]
 
 PENDING UPDATE
 [http://www.eclipse.org/emf/compare/doc/features/videos/LogicalModels/LogicalModels.html Demo]
 
 === UML Specialization  ===
 
+A specific work has been done with EMF Compare for UML. It consists in an additionnal filter named '''UML refined elements'''. This filter is active by default when a comparison involves UML resources.
+
+[[Image:./../images/EMF_Compare_UML_Filter.png]]
+
+The filter groups UML consistant differences together in one difference. For example, a UML association is modeled by an association element and several sub-elements:
+
+[[Image:./../images/EMF_Compare_UML_Association.png]]
+
+If EMF Compare detects a change on an element of type association, it will group all changes on the sub-elements of the assocation to the association difference.
+The goal of this filter is to ease the merge of differences. Indeed, all you have to do is to merge the association difference and it will merge all the sub-differences with it.
+
+Here is the comparison of two UML model, one with an association (the left side), another whithout (the right side). The '''UML refined elements''' filter has been deactivated:
+
+[[Image:./../images/EMF_Compare_UML_Association_2.png]]
+
+We can see a lot of differences. 
+The same comparison with the '''UML refined elements''' filter activated:
+
+[[Image:./../images/EMF_Compare_UML_Association_3.png]]
+
 PENDING
 
 [[http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm | Demo : Specific support to encapsulate profiles and stereotypes diffs]]