[516902] Improve the documentation of the Properties view

Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=516902
Change-Id: I4ddd75982f3fbaa3714e401fdec4b44b86ecb67e
Signed-off-by: Stéphane Bégaudeau <stephane.begaudeau@obeo.fr>

3 files changed, 33 insertions, 7 deletions

diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/properties/Properties_View_Description.html b/plugins/org.eclipse.sirius.doc/doc/specifier/properties/Properties_View_Description.html
index 176ad9b71a..673de23d7f 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/properties/Properties_View_Description.html
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/properties/Properties_View_Description.html
@@ -162,6 +162,22 @@
 		<p>Note that if you have the (optional) support for Sirius-defined properties views correctly installed but do not specify anything inside your VSMs, Sirius will apply default generic rules to provide a canonical properties view for your model elements. As soon as you specify your own configuration, as described in this document, the default rules will be ignored in favor of yours. See 
 			<a href="#default_rules">below</a> for how both approaches can be combined.
 		</p>
+		<p>You can create a 
+			<em>Properties View</em> description under the root element of an odesign thanks to three specific menu items.
+		</p>
+		<p>
+			<img border="0" src="images/new-properties.png"/>
+		</p>
+		<ul>
+			<li>The first menu is used to create a blank 
+				<em>Properties View</em> description. With this menu, you will start your 
+				<em>Property View</em> definition from scratch.
+			</li>
+			<li>The second menu can copy the default rules directly inside of the odesign. While powerful, those default rules can be quite complex for new users.</li>
+			<li>The third menu can create a new 
+				<em>Properties View</em> which will extends the default rules. Using this mechanism, you can leverage all the default rules and you have the ability to easily add new rules.
+			</li>
+		</ul>
 		<h2 id="properties_view_description">Properties View Description</h2>
 		<p>Properties view are configured by creating a 
 			<em>Properties View Description</em> element (directly under the top-level 
@@ -201,7 +217,9 @@
 				</a>, which represent named sections inside a page/tab which contain the actual widgets;
 			</li>
 			<li>
-				<a href="#overrides">_Overrides</a>, which allows to override part of an existing properties view description. 
+				<a href="#overrides">
+					<em>Overrides</em>
+				</a>, which allows to override part of an existing properties view description. 
 			</li>
 		</ul>
 		<p>It is recommended that the 
@@ -1578,10 +1596,10 @@
 			</li>
 		</ul>
 		<p>The 
-			<code>Extend</code> tab is used to specify:
+			<code>Override</code> tab is used to specify:
 		</p>
-		<p id="extends">
-			<strong>Extends.</strong> Is used to specify the overridden element thanks to a combo box it is possible to select an existing element. In the tree editor, the inheritance is visible as the element is named as following : 
+		<p id="override">
+			<strong>Override.</strong> Is used to specify the overridden element thanks to a combo box it is possible to select an existing element. In the tree editor, the inheritance is visible as the element is named as following : 
 			<em>Page A</em> 
 			<strong>extends</strong> 
 			<em>Page B</em>. Pay attention, the current specification editor allows to select the currently defined element, this will lead to an infinite loop at runtime. 
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/properties/Properties_View_Description.textile b/plugins/org.eclipse.sirius.doc/doc/specifier/properties/Properties_View_Description.textile
index 0f27e62372..7490a76322 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/properties/Properties_View_Description.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/properties/Properties_View_Description.textile
@@ -14,6 +14,14 @@ Sirius properties view are enabled whenever the selected element is part of an o
 
 Note that if you have the (optional) support for Sirius-defined properties views correctly installed but do not specify anything inside your VSMs, Sirius will apply default generic rules to provide a canonical properties view for your model elements. As soon as you specify your own configuration, as described in this document, the default rules will be ignored in favor of yours. See "below":#default_rules for how both approaches can be combined.
 
+You can create a _Properties View_ description under the root element of an odesign thanks to three specific menu items.
+
+!images/new-properties.png!
+
+* The first menu is used to create a blank _Properties View_ description. With this menu, you will start your _Property View_ definition from scratch.
+* The second menu can copy the default rules directly inside of the odesign. While powerful, those default rules can be quite complex for new users.
+* The third menu can create a new _Properties View_ which will extends the default rules. Using this mechanism, you can leverage all the default rules and you have the ability to easily add new rules.
+
 h2(#properties_view_description). Properties View Description
 
 Properties view are configured by creating a _Properties View Description_ element (directly under the top-level "_Group_":../general/Specifying_Viewpoints.html#vsm_organization element of the VSM) and its sub-elements (which describe the widgets, the actions, the layout, etc.).
@@ -26,7 +34,7 @@ Inside a _Properties View Description_ element, you can create:
 Inside a _Category_ element, you can create:
 * "_Pages_":#pages, which correspond to "tabs";
 * "_Groups_":#groups, which represent named sections inside a page/tab which contain the actual widgets;
-* "_Overrides":#overrides, which allows to override part of an existing properties view description. 
+* "_Overrides_":#overrides, which allows to override part of an existing properties view description. 
 
 It is recommended that the _Properties View Description_ be explicitly associated with the meta-model(s) of the semantic elements it will represent. You can add referenced meta-models from different sources in the _Metamodels_ property section of the _Properties View Description_. Sirius will work even without this association, but setting it explicitly will give you better feedback when validating your "_VSM_":../../Glossary.html#VSM.
 
@@ -610,9 +618,9 @@ A page override can extend another page defined somewhere else (in another "cate
 * dynamic mapping override: a _Dynamic Mapping Override_ is a dynamic mapping and so defines the same features as a "dynamic mapping":#dynamic_mappings,
 * widget override: a _Widget Override_ is a widget and so defines the same features as a "widget":#widgets.
 
-The @Extend@ tab is used to specify:
+The @Override@ tab is used to specify:
 
-p(#extends). *Extends.* Is used to specify the overridden element thanks to a combo box it is possible to select an existing element. In the tree editor, the inheritance is visible as the element is named as following : _Page A_ *extends* _Page B_. Pay attention, the current specification editor allows to select the currently defined element, this will lead to an infinite loop at runtime. 
+p(#override). *Override.* Is used to specify the overridden element thanks to a combo box it is possible to select an existing element. In the tree editor, the inheritance is visible as the element is named as following : _Page A_ *extends* _Page B_. Pay attention, the current specification editor allows to select the currently defined element, this will lead to an infinite loop at runtime. 
 By default, the values of the @General@ tab fields are set with the values coming from the overridden element if these fields are not set in the extending element. If one of these attributes is edited in the extending element, then it *overrides* the inherited value. The same behavior is applied for mono valued containment elements. For example, if a _Group A_ defines a _Style A_ and extends a _Group B_ with a _Style B_, the style used to render the _Group A_ is the one defined under the _Group A_, i.e _Style A_ and not the one of the _Group B_.
 If the specifier defines in the extending page @General@ tab:
 * @Label Expression@, @Domain Class@, @Semantic Candidate Expression@ or @Precondition Expression@, these values will *override* the values defined in the extended description. It is worth noting that the expressions are evaluated in the context of the currently extending element, exactly as if you have defined the expressions from the @General@ tab. 
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/properties/images/new-properties.png b/plugins/org.eclipse.sirius.doc/doc/specifier/properties/images/new-properties.png
new file mode 100644
index 0000000000..8fae193b6f
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/properties/images/new-properties.png