[527109] Update documentation

Bug: 527109
Change-Id: I93f1417a60f1819d776a2a94e74d2c1907be3054
Signed-off-by: Pierre Guilet <pierre.guilet@obeo.fr>

7 files changed, 240 insertions, 6 deletions

diff --git a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/Diagrams.html b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/Diagrams.html
index bdd4ce08de..296b2ccda9 100644
--- a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/Diagrams.html
+++ b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/Diagrams.html
@@ -24,6 +24,11 @@
 							</li>
 							<li>
 								<a href="#ManagingDiagrams">Managing Diagrams</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#RulersGrid">Rulers &amp; Grid</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#Movingthediagram">Moving the diagram</a>
@@ -33,21 +38,67 @@
 							</li>
 							<li>
 								<a href="#Resizingelements">Resizing elements</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#Compartments">Compartments</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#Movingelements">Moving elements</a>
 							</li>
 							<li>
 								<a href="#Manageedges">Manage edges</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#Snapbackedgelabels">Snap back edge labels</a>
+									</li>
+									<li>
+										<a href="#Movebendpoints">Move bend-points</a>
+									</li>
+									<li>
+										<a href="#RemoveBendpoints">Remove Bend-points</a>
+									</li>
+									<li>
+										<a href="#straighten_an_edge">Straighten edges</a>
+									</li>
+									<li>
+										<a href="#move_edge_group">Move edge group</a>
+									</li>
+									<li>
+										<a href="#edge_label_attachment">Display attachment link between edge and its labels</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#distribute">Distribute elements</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#Firstandlastshapes">First and last shapes</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#reset_origin">Reset Diagram or Container Origin</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#Specificcases">Specific cases</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#Hidingelements">Hiding elements</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#Hidinglabels">Hiding labels</a>
+									</li>
+									<li>
+										<a href="#HidingiconsoflabelsonShapesorConnectors">Hiding icons of labels on Shapes or Connectors</a>
+									</li>
+									<li>
+										<a href="#Collapsingcompartments">Collapsing compartments</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#Validatingthemodel">Validating the model</a>
@@ -63,27 +114,87 @@
 							</li>
 							<li>
 								<a href="#PortshiftingPortDragandDrop">Port shifting - Port Drag and Drop</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#Selectionhandles">Selection handles</a>
+									</li>
+									<li>
+										<a href="#Portshiftinganddraganddrop">Port shifting and 'drag and drop'</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#copy_paste_format">Copy/paste of format</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#PasteLayout">Paste Layout</a>
+									</li>
+									<li>
+										<a href="#PasteStyle">Paste Style</a>
+									</li>
+									<li>
+										<a href="#PasteFormat">Paste Format</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#diagram_element_pinning">Diagram element pinning</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#Introduction">Introduction</a>
+									</li>
+									<li>
+										<a href="#Pinunpinactions">Pin/unpin actions</a>
+									</li>
+									<li>
+										<a href="#Configuration">Configuration</a>
+									</li>
+									<li>
+										<a href="#PinUnpinonNotes">Pin/Unpin on Notes</a>
+									</li>
+									<li>
+										<a href="#PinUnpinelementsusingatreeviewer">Pin/Unpin elements using a tree viewer</a>
+									</li>
+								</ol>
 							</li>
 							<li>
-								<a href="#Layoutingmodearrangeyourdiagramswithoutmodifyingsemanticmodels">Layouting mode: arrange your diagrams without modifying semantic models</a>
+								<a href="#Editmodes">Edit modes</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#Standardmode">Standard mode</a>
+									</li>
+									<li>
+										<a href="#Layoutingmodearrangeyourdiagramswithoutmodifyingsemanticmodels">Layouting mode: arrange your diagrams without modifying semantic models</a>
+									</li>
+									<li>
+										<a href="#Showhidemodechangediagramelementvisibilitywithoutmodifyingsemanticmodels">Show/hide mode: change diagram element visibility without modifying semantic models</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#synchronized_diagram">Synchronized/Unsynchronized diagram</a>
 							</li>
 							<li>
 								<a href="#UsingRegularExpressionstoFindDiagramElements">Using Regular Expressions to Find Diagram Elements</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#Rules">Rules</a>
+									</li>
+									<li>
+										<a href="#Examples">Examples</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#quick_outline">Quick Outline</a>
 							</li>
 							<li>
 								<a href="#styleCustomizations">Style customizations </a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#routingStylePref">Customize edge routing style from preferences</a>
+									</li>
+								</ol>
 							</li>
 						</ol>
 					</li>
@@ -95,9 +206,34 @@
 							</li>
 							<li>
 								<a href="#Palette">Palette</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#ManagingThePalette">Managing The Palette</a>
+									</li>
+									<li>
+										<a href="#standardToolId">Standard Tools</a>
+									</li>
+									<li>
+										<a href="#PaletteContents">Palette Contents</a>
+									</li>
+									<li>
+										<a href="#UsingTheToolsFromThePalette">Using The Tools From The Palette</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#ref_tabbar">Tab-bar</a>
+								<ol style="list-style: disc;">
+									<li>
+										<a href="#ref_tabbar_diagram">Tab-bar Actions Available on Diagram</a>
+									</li>
+									<li>
+										<a href="#ref_tabbar_element">Tab-bar Actions Available on Diagram Elements</a>
+									</li>
+									<li>
+										<a href="#ref_tabbar_4x">Tab-bar in Eclipse 4.2 and 4.3</a>
+									</li>
+								</ol>
 							</li>
 							<li>
 								<a href="#PropertiesView">Properties View</a>
@@ -885,7 +1021,19 @@
 		<p>	
 			<img border="0" src="images/diagram_editor_pin_toolbar_activated.png"/>
 		</p>
-		<h3 id="Layoutingmodearrangeyourdiagramswithoutmodifyingsemanticmodels">Layouting mode: arrange your diagrams without modifying semantic models</h3>
+		<h3 id="Editmodes">Edit modes</h3>
+		<p>Different diagram edit modes are available. Each mode focus on a specific way of editing diagrams. Modes are accessible from a dropdown menu in the tabbar when no diagram element is selected:
+			<br/>
+			<img border="0" src="images/editModesDropdown.png"/>
+		</p>
+		<h4 id="Standardmode">Standard mode</h4>
+		<p>This is the default mode used to create diagrams and populate them. In this mode, there is no restriction regarding available tools and semantic changes.
+			<br/>To go back to this mode after changing it, you just have to select it from the tabbar:
+		</p>
+		<p>
+			<img border="0" src="images/standardModeActivation.png"/>
+		</p>
+		<h4 id="Layoutingmodearrangeyourdiagramswithoutmodifyingsemanticmodels">Layouting mode: arrange your diagrams without modifying semantic models</h4>
 		<p>When you only want to do layout operations (e.g. arrange a diagram by moving nodes or edges), you may modify the semantic models without paying attention. For example, when organizing bordered nodes, you may change the container of the semantic element, without wanting do so.</p>
 		<p>When this mode is enabled, the following operations are changed:</p>
 		<ul>
@@ -897,11 +1045,14 @@
 			<strong>Layout Mode is not a &#8220;read-only&#8221; mode and does not guarantee that the semantic model is not modified when it is enabled.</strong>
 		</p>
 		<p>
-			<strong>Layouting mode</strong> can be activated/disabled on a diagram through the tab bar (when there is no selected element) : 
+			<strong>Layouting mode</strong> can be activated on a diagram through the tab bar (when there is no selected element) : 
 		</p>
 		<p>
 			<img border="0" src="images/layouting_mode_tabbar_activate.png"/>
 		</p>
+		<p>To deactivate the mode you just have to select the 
+			<em>Standard mode</em>.
+		</p>
 		<p>The diagram&#8217;s status line then indicates that the diagram is currently in 
 			<em>Layouting mode</em> : 
 		</p>
@@ -916,6 +1067,45 @@
 		<p>When a diagram is closed, the 
 			<em>Layouting mode</em> is automatically disabled.
 		</p>
+		<h4 id="Showhidemodechangediagramelementvisibilitywithoutmodifyingsemanticmodels">Show/hide mode: change diagram element visibility without modifying semantic models</h4>
+		<p>This mode allows to visualize all diagram elements either visible or invisible because of a filter or a previous hiding action execution on the element. Invisible elements will be shown with transparency:</p>
+		<p>
+			<img border="0" src="images/show_hide_mode_example.png"/>
+		</p>
+		<p>This mode also allows to change visibility of diagram elements.
+			<br/>Indeed, when you double click on a visible diagram element, it will hide it like the &#8220;hide&#8221; menu action. And if not visible, it will show it like the &#8220;show&#8221; menu action. 
+			<br/>Additional features of the double click are the following:
+		</p>
+		<ul>
+			<li>If the diagram element to make visible is contained by other invisible elements, then all its parent elements will be made visible.</li>
+			<li>If the diagram element to make visible has children, these children will be made visible if they are not hidden. Otherwise they will be displayed with transparency.</li>
+			<li>A double click on an edge to show will also show its source and target.</li>
+			<li>If a diagram element is invisible because a filter hiding is activated, then you will be asked if you want to deactivate this filter to make it visible after a double click on it.</li>
+			<li>If a diagram element is invisible because the layer showing it is not activated, then you will be asked if you want to activate this layer to make it visible after a double click on it.</li>
+		</ul>
+		<p>It is easy to do semantics changes whereas you only want to change diagram element visibility.
+			<br/>So when this mode is enabled, the following operations are changed:
+		</p>
+		<ul>
+			<li>direct edit is disabled on all elements;</li>
+			<li>moving elements by dragging them can be used to change their position, but will never trigger a drag and drop operation;</li>
+			<li>moving the extremity of an edge to adjust its connection point (to the source or target element) is possible, but will never trigger a reconnection operation.</li>
+		</ul>
+		<p>Note that other operations which can change the semantic model are still possible. Only the operations listed above, which are easy to misuse, are disabled/modified. 
+			<strong>Show/Hide mode is not a &#8220;read-only&#8221; mode and does not guarantee that the semantic model is not modified when it is enabled.</strong>
+		</p>
+		<p>
+			<strong>Show/Hide mode</strong> can be activated on a diagram through the tabbar (when there is no selected element) : 
+		</p>
+		<p>
+			<img border="0" src="images/show_hide_mode_tabbar_activate.png"/>
+		</p>
+		<p>To deactivate the mode you just have to select the 
+			<em>Standard mode</em>.
+		</p>
+		<p>When a diagram is closed, the 
+			<em>Show/Hide mode</em> is automatically disabled.
+		</p>
 		<h3 id="synchronized_diagram">Synchronized/Unsynchronized diagram</h3>
 		<p>The contextual menu on the background of the diagram provides an action to toggle between 
 			<i>Synchronized</i> / 
diff --git a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/Diagrams.textile b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/Diagrams.textile
index a635321f22..db3047362a 100644
--- a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/Diagrams.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/Diagrams.textile
@@ -2,7 +2,7 @@ h1. Diagram Editors
 
 This document explains how to use diagram editors/modelers supported by Sirius which allow to view and manipulate data in a graphical way.
 
-{toc:style=disc|minLevel=2|maxLevel=3}
+{toc:style=disc|minLevel=2|maxLevel=4}
 
 h2(#introduction). Introduction
 
@@ -610,8 +610,20 @@ You can also use "RegularExpressions":#UsingRegularExpressionstoFindDiagramEleme
 To see more easily if one or more graphical elements are pinned, the icon in the toolbar change, showing a "checked" if an element is pinned.
 
 	!images/diagram_editor_pin_toolbar_activated.png!
+	
+h3. Edit modes
+
+Different diagram edit modes are available. Each mode focus on a specific way of editing diagrams. Modes are accessible from a dropdown menu in the tabbar when no diagram element is selected:
+!images/editModesDropdown.png!
+
+h4. Standard mode
+
+This is the default mode used to create diagrams and populate them. In this mode, there is no restriction regarding available tools and semantic changes.
+To go back to this mode after changing it, you just have to select it from the tabbar:
+
+!images/standardModeActivation.png!
 
-h3. Layouting mode: arrange your diagrams without modifying semantic models
+h4. Layouting mode: arrange your diagrams without modifying semantic models
 
 When you only want to do layout operations (e.g. arrange a diagram by moving nodes or edges), you may modify the semantic models without paying attention. For example, when organizing bordered nodes, you may change the container of the semantic element, without wanting do so.
 
@@ -621,10 +633,12 @@ When this mode is enabled, the following operations are changed:
 * moving the extremity of an edge to adjust its connection point (to the source or target element) is possible, but will never trigger a reconnection operation.
 Note that other operations which can change the semantic model are still possible. Only the operations listed above, which are easy to misuse, are disabled/modified. *Layout Mode is not a "read-only" mode and does not guarantee that the semantic model is not modified when it is enabled.*
 
-*Layouting mode* can be activated/disabled on a diagram through the tab bar (when there is no selected element) : 
+*Layouting mode* can be activated on a diagram through the tab bar (when there is no selected element) : 
 
 !images/layouting_mode_tabbar_activate.png!
 
+To deactivate the mode you just have to select the _Standard mode_.
+
 The diagram's status line then indicates that the diagram is currently in _Layouting mode_ : 
 
 !images/layoutingMode_forbidden_dnd.png!
@@ -633,6 +647,36 @@ In this example, as _Layouting mode_ is activated, reconnecting the Edge from _A
 
 When a diagram is closed, the _Layouting mode_ is automatically disabled.
 
+h4. Show/hide mode: change diagram element visibility without modifying semantic models
+
+This mode allows to visualize all diagram elements either visible or invisible because of a filter or a previous hiding action execution on the element. Invisible elements will be shown with transparency:
+ 
+!images/show_hide_mode_example.png!
+ 
+This mode also allows to change visibility of diagram elements.
+Indeed, when you double click on a visible diagram element, it will hide it like the "hide" menu action. And if not visible, it will show it like the "show" menu action. 
+Additional features of the double click are the following:
+* If the diagram element to make visible is contained by other invisible elements, then all its parent elements will be made visible.
+* If the diagram element to make visible has children, these children will be made visible if they are not hidden. Otherwise they will be displayed with transparency.
+* A double click on an edge to show will also show its source and target.
+* If a diagram element is invisible because a filter hiding is activated, then you will be asked if you want to deactivate this filter to make it visible after a double click on it.
+* If a diagram element is invisible because the layer showing it is not activated, then you will be asked if you want to activate this layer to make it visible after a double click on it.
+ 
+It is easy to do semantics changes whereas you only want to change diagram element visibility.
+So when this mode is enabled, the following operations are changed:
+* direct edit is disabled on all elements;
+* moving elements by dragging them can be used to change their position, but will never trigger a drag and drop operation;
+* moving the extremity of an edge to adjust its connection point (to the source or target element) is possible, but will never trigger a reconnection operation.
+Note that other operations which can change the semantic model are still possible. Only the operations listed above, which are easy to misuse, are disabled/modified. *Show/Hide mode is not a "read-only" mode and does not guarantee that the semantic model is not modified when it is enabled.*
+
+*Show/Hide mode* can be activated on a diagram through the tabbar (when there is no selected element) : 
+
+!images/show_hide_mode_tabbar_activate.png!
+
+To deactivate the mode you just have to select the _Standard mode_.
+
+When a diagram is closed, the _Show/Hide mode_ is automatically disabled.
+
 h3(#synchronized_diagram). Synchronized/Unsynchronized diagram
 
 The contextual menu on the background of the diagram provides an action to toggle between __Synchronized__ / __Unsynchronized__ modes.
diff --git a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/editModesDropdown.png b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/editModesDropdown.png
new file mode 100644
index 0000000000..3c908fb984
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/editModesDropdown.png
diff --git a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/layouting_mode_tabbar_activate.png b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/layouting_mode_tabbar_activate.png
index c6e83309e4..289b1d0f99 100644
--- a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/layouting_mode_tabbar_activate.png
+++ b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/layouting_mode_tabbar_activate.png
diff --git a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/show_hide_mode_example.png b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/show_hide_mode_example.png
new file mode 100644
index 0000000000..6af8db638b
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/show_hide_mode_example.png
diff --git a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/show_hide_mode_tabbar_activate.png b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/show_hide_mode_tabbar_activate.png
new file mode 100644
index 0000000000..1c72621214
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/show_hide_mode_tabbar_activate.png
diff --git a/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/standardModeActivation.png b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/standardModeActivation.png
new file mode 100644
index 0000000000..6d227b23f4
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/user/diagrams/images/standardModeActivation.png