Vorto mapping review done. Fixes eclipse-vorto#317

Signed-off-by: Guenther Michael (INST/BSV2-TD) <[email protected]>

website/documentation/editors/datatype.md

@@ -55,7 +55,7 @@ You have created a data type (refer to [Creating a new Data Type](#creating-a-ne
 
 **Proceed as follows**
 
-1. In the **Datatype Models** area, click the data type entity you want to edit, e.g., `Color`.  
+1. In the **Datatype Models** area, click the data type entity you want to edit, for example, `Color`.  
    The DSL editor for the file `*_Color_*.type` opens.
 2. In the DSL editor, edit the entity according to your needs.
 

website/documentation/editors/mapping-model.md

@@ -1,63 +1,76 @@
 ---
 layout: documentation
-title: Model Mappings
+title: Defining Model Mappings
 ---
 {% include base.html %}
 
-## Mapping Models
 
-Vorto allows the user to define mapping rules to map Vorto models to other target platform domain models.
+# Defining Model Mappings
 
-The primary purpose of defining Mapping models in Vorto is to directly translate or map datatype/functionblock/information model descriptions from Vorto to any other IoT platforms (For e.g Kura, Eclipse Smarthome). Vorto Mapping models acts as a bridge between Vorto definitions and target platforms/technologies.
+This section details the following topics:
 
-In addition to that, the mapping models provides an option to enhance the Vorto models with additional meta data descriptions targeted for a specific platform. Thereby the code generators can leverage the expanded meta data descriptions customized for their platforms. Vorto helps to  integrate with other IoT platforms through the Mapping models in flexible manner. Here are few possible scenarios where Mapping models can be used. 
+[Model Mapping](#model-mapping)  
 
- - Translate Vorto model definitions to understand other IoT platforms
- - Provide additional metadata in which Vorto models is not able to describe for specific IoT solutions.
- - Provide different mapping models for multiple versions of target platforms (For eg. iOS 7/8) 
+[Defining a Data Type Mapping](./data-type-mapping.html)  
 
+[Defining a Function Block Mapping](./function-block-mapping.html)  
+
+[Defining an Information Model Mapping](./information-model-mapping.html)  
 
-Mapping models can be defined for
-
- - [Datatypes](./data-type-mapping.html)
- - [Function Blocks](./function-block-mapping.html)
- - [Information Models](./information-model-mapping.html)   
 
-The Mapping models contains direct mapping of Vorto grammar descriptions to custom defined `Stereotypes` and `Attributes` specific for that target platform. 
+## Model Mapping
 
-`Stereotypes` are custom defined keyword which is leveraged by target platform generators.
+Vorto allows the user to define mapping rules to map Vorto models to other target platform domain models.
 
-`Attributes` are custom defined key value pairs for a specific Stereotypes which is again leveraged by specific target platform generators.    
+The primary purpose of defining model mappings in Vorto is to directly translate or map datatype/functionblock/information model descriptions from Vorto to any other IoT platforms (for example, Kura, Eclipse Smarthome). Vorto model mapping acts as a bridge between Vorto definitions and target platforms/technologies.
 
-A simple Mapping model definition from Vorto to Philips Hue looks likes below, 
+In addition to that, the model mapping provides an option to enhance the Vorto models with additional metadata descriptions targeted for a specific platform. Thereby the code generators can leverage the expanded metadata descriptions customized for their platforms. Vorto helps to integrate with other IoT platforms through the model mapping in flexible manner. Here are few possible scenarios where model mapping can be used:
 
-	from ColorLight.category to philipshue with {configuration : "devicetype"}
+ - Translate Vorto model definitions to understand other IoT platforms.
+ - Provide additional metadata in case the Vorto model is not able to describe a specific IoT solution.
+ - Provide different model mappings for multiple versions of target platforms (For example, iOS 7/8).
 
-In the above mapping 'philipshue' is a custom defined stereotype and 'configuration' is custom defined attribute and a value 'devicetype' is actual value which is being mapped to Philips Hue definitions. The code generators can make use of these additional metadata which could be targeted for specific IoT solutions or platforms. 
+Model mapping can be defined for the following:
+
+- [Datatypes](./data-type-mapping.html)
+- [Function Blocks](./function-block-mapping.html)
+- [Information Models](./information-model-mapping.html)   
 
+The model mapping contains a direct mapping of Vorto grammar descriptions to custom defined `Stereotypes` and `Attributes` specific for the target platform.
+
+`Stereotypes` are custom defined keywords which are leveraged by target platform generators.
+
+`Attributes` are custom defined key value pairs for a specific stereotype which is again leveraged by specific target platform generators.
+
+A simple model mapping statement from Vorto to Philips Hue looks likes below
+
+	...
+	from ColorLight.category to philipshue with {configuration : "devicetype"}
+	...
 
+In the above mapping `philipshue` is a custom defined stereotype, `configuration` is a custom defined attribute and the value `devicetype` is the actual value which is being mapped to Philips Hue definitions. The code generators can make use of these additional metadata which could be targeted for specific IoT solutions or platforms.
 
-To demonstrate the potential for Mapping models, let us define a mapping model to enhance Alexa commands for AWS genertor.
+To demonstrate the potential for model mapping, let us define a model mapping to enhance *Alexa* commands for the *AWS genertor*.
 
-Lets take a simple example of `ColorLight` functionblock definition, 
+The following two examples definitions are given:
 
+`ColorLight` functionblock definition
 
 	namespace com.mycompany.fb
 	version 1.0.0
 	displayname "ColorLight"
 	description "Function block model for ColorLight"
 	category demo	
 	functionblock ColorLight {
-		status{ 
+		status{
 			mandatory brightness as int
 		}
 		operations{
-			setBrightness(level as int)		
+			setBrightness(level as int)
 		}
 	}
 
-
-and with `ColorLightSystem` information model definition, 	
+`ColorLightSystem` information model definition
 
 	namespace com.mycompany.informationmodels
 	version 1.0.0
@@ -74,14 +87,15 @@ and with `ColorLightSystem` information model definition,
 		}
 	}
 
-By invoking AWS generator without any mapping models from Vorto Repository, it generates the following Alexa voice command vocabulary in `colorlightsystemUtterances.txt` file. These  voice commands are provided as a input to AWS service to set the appropriate brightness level to any device. The details of how the AWS services control the actual devices are beyond the scope of this documentation. 
-	
+By invoking the *AWS Generator* without any model mapping from Vorto Repository, it generates the following *Alexa* voice command vocabulary in the `colorlightsystemUtterances.txt` file.
+
 	setBrightness {level}
-	
+
 	brightness get brightness status
-
 
-Lets define a mapping model `ColorLightMapping` to enhance the Alexa voice commands vocabulary for the `ColorLight` functionblock. Thereby more voice commands are recognized by AWS services to control the actual devices.
+These voice commands are provided as an input to the AWS service to set the appropriate brightness level to any device. The details of how the AWS services control the actual devices are beyond the scope of this documentation.
+
+Now we define a model mapping `ColorLightMapping` to enhance the *Alexa* voice commands vocabulary for the `ColorLight` functionblock. Thereby, more voice commands are recognized by AWS services to control the actual devices.
 
 	namespace examples.mappings.aws
 	version 1.0.0
@@ -90,37 +104,34 @@ Lets define a mapping model `ColorLightMapping` to enhance the Alexa voice comma
 	using com.mycompany.fb.ColorLight;1.0.0
 	functionblockmapping ColorLightMapping {
 		targetplatform aws
-		from ColorLight.operation.setBrightness to alexa with {command: "set brightness to {level} ; increase brightness to {level} ; decrease brightness to {level}"}		
-	}	
-
+		from ColorLight.operation.setBrightness to alexa with {command: "set brightness to {level} ; increase brightness to {level} ; decrease brightness to {level}"}
+	}
 
-In the above mapping, the Alexa voice command is enhanced by additional command with `increase` and `decrease` to control the `ColorLight`.  Here `alexa` is a custom defined `Stereotype` keyword which AWS code generator interprets and makes use of the additional values defined in the mapping model. Again `command` is a custom defined `Attribute` keyword which is AWS code generator can understand. 
+In the above mapping, the *Alexa* voice command is enhanced by  additional commands with `increase` and `decrease` to control the `ColorLight`. Here, `alexa` is a custom defined `Stereotypes` keyword which the *AWS Generator* interprets and makes use of the additional values defined in the model mapping. Again, `command` is a custom defined `Attribute` keyword which the *AWS generator* can understand. 
 
 
-Once this mapping model `ColorLightMapping` is shared using Vorto Repository Web UI page as below
+Once this model mapping `ColorLightMapping` is defined, it can be shared using the Vorto Repository Web interface page:
 
- ![Share Mapping Model]({{base}}/img/documentation/vorto_share_mapping_model.png). 
+![Share Model Mapping]({{base}}/img/documentation/vorto_share_mapping_model.png)
 
 <table class="table table-bordered">
 	<tbody>
  <tr>
    <td><i class="fa fa-info-circle info-note"></i></td>
-    <td>Note: Currently mapping models are shared only through Vorto repository Web UI.</td>
+    <td>Note: Currently, model mappings are shared only through the Vorto Repository Web interafce.</td>
   </tr></tbody>
 </table>  
 
 
-With this mapping model, when the AWS generator is invoked, it generates the following `colorlightsystemUtterances.txt`
+With this model mapping the *AWS Generator* generates the file `colorlightsystemUtterances.txt` with the following content:
 
 	setBrightness set brightness to {level} 
 	setBrightness  increase brightness to {level} 
 	setBrightness  decrease brightness to {level}
 
 	brightness get brightness status   
 
-Here the Vorto mapping model descriptions greatly enhances the capabilities of any platform, in this case it is AWS Alexa platform.
-
-
+As you can see, the Vorto model mapping definition greatly enhances the capabilities of any platform, in this case the AWS Alexa platform.
 
 <div class="thumb1">
 <a title="Defining a new Mapping" data-rel="prettyPhoto" href="https://youtu.be/C5c5tTFwG0U&width=1500&height=1000" rel="prettyPhoto" >

website/documentation/vorto-repository/web-interface/overview.md

@@ -19,8 +19,8 @@ You can do the following:
 
 You can access the Vorto Repository by the following ways:
 
-* [The Vorto Repository Web interface]({{base}}/documentation/vorto-repository/web-interface/login-register.html)
-* [The Eclipse Vorto integration]({{base}}/documentation/vorto-repository/eclipse-vorto-integration/setting-preferences-eclipse.html)
+* [The Vorto Repository Web Interface]({{base}}/documentation/vorto-repository/web-interface/login-register.html)
+* [The Eclipse Vorto Integration]({{base}}/documentation/vorto-repository/eclipse-vorto-integration/setting-preferences-eclipse.html)
 * [The Vorto CLI Tool]({{base}}/documentation/vorto-repository/cli-tool/cli-tool.html)
 
 For searching and downloading information Models as well as for information on available code generators you can use the Vorto Repository without an Vorto Repository account.