For discussion: Add support for definition

docs-gen/content/rule_set/branches.md

@@ -31,6 +31,9 @@ opposed to a signal entry). This is the default, in case ```type``` is omitted.
 Describes the meaning and content of the branch.
 Recommended to start with a capital letter and end with a dot (`.`).
 
+<!-- We cannot really give a definition of a "branch", can we? -->
+<!-- So keep "description" but keep it optional? -->
+
 **```comment ```**  *[optional]* `since version 3.0`
 A comment can be used to provide additional informal information on a branch.
 This could include background information on the rationale for the branch,

docs-gen/content/rule_set/data_entry/allowed.md

@@ -20,8 +20,6 @@ SteeringWheel.Position:
 
 ```
 
-If `allowed` is set, `min` or `max` cannot be defined.
-
 The `allowed` element is an array of values, all of which must be specified
 in a list.  Only values can be assigned to the data entry, which are
 specified in this list.

docs-gen/content/rule_set/data_entry/attributes.md

@@ -4,8 +4,9 @@ date: 2019-08-04T12:37:31+02:00
 weight: 40
 ---
 
-An attribute is an entity that has a default value, specified by
-its ```default``` member.
+An attribute is an entity that has a default value, specified by its ```default``` member.
+All other members are the same as for [sensors and actuators](/vehicle_signal_specification/rule_set/data_entry/sensor_actuator/).
+
 The standard Vehicle Signal Specification does not include default values for all attributes.
 If a default value has not been specified then the OEM must define a default value matching the actual vehicle.
 If the standard defines a default value but it does not fit the actual vehicle,

docs-gen/content/rule_set/data_entry/sensor_actuator.md

@@ -14,17 +14,32 @@ entry example is given below:
 ```YAML
 Speed:
   type: sensor
-  description: The vehicle speed.
+  definition: Vehicle speed relative to the X-axis of the intermediate axis system as defined by ISO 8855 section 2.13.
+  description: Vehicle speed relative to road surface. Positive if vehicle is moving forward, negative if vehicle is moving backward.
   comment: For engine speed see Vehicle.Powertrain.CombustionEngine.Engine.Speed.
   datatype: float
   unit: km/h
   min: 0
   max: 300
+  allowed: ...
 ```
 
-**```Drivetrain.Transmission.Speed```**
-Defines the dot-notated name of the data entry. Please note that
-all parental branches included in the name must be defined as well.
+**```<signal name>```**
+Defines (parts of) the name of the data entry.
+The full name/path of a VSS signal, considering parent branches, must be unique,
+but the name specified in the **.vspec* file do not necessarily need to be unique.
+
+The VSS **.vspec* format supports [#include](/vehicle_signal_specification/rule_set/includes/) directives.
+When including a **.vspec* file it is possible to define a branch prefix that shall be used on entries in the
+included file. If the definition above exists in a signal included like:
+
+```YAML
+#include Vehicle/Vehicle.vspec Vehicle
+```
+
+... then the full name of the signal using VSS dot-notation will be `Vehicle.Speed`
+
+*Note: VSS implementations does not necessarily need to use VSS dot-notation to reference signals, they can use alternative mechanisms to uniquely reference signals!*
 
 **```type```**
 Defines the type of the node. This can be `branch`,
@@ -35,11 +50,25 @@ The string value of the type specifies the scalar type of the data entry
 value. See [data type](/vehicle_signal_specification/rule_set/data_entry/data_types/) chapter for a list of available types.
 
 **```description```**
-Describes the meaning and content of the signal.
-The `description`shall together with other mandatory members like `datatype` and `unit` provide sufficient information
+The description is less formal and provides any kind of information that helps humans to conceptualize the entry.
+The `description` member shall together with other mandatory members like `datatype` and `unit` provide sufficient information
 to understand what the signal contains and how signal values shall be constructed or interpreted.
 Recommended to start with a capital letter and end with a dot (`.`).
 
+<!--
+In general VSS community seems to favor definition over description, and ther is limited interest in supporting both.
+Changing to definition (only) would however require significant effort as content of descriptions needs to be reviewed/refactored
+Proposed first step is to open up for definitions.
+When (if ever) the majority of signals have definition it can be discussed if we shall make definition mandatory
+and deprecate description.
+-->
+
+**```definition```** *[optional]* `since version 5.0`
+The definition is a formal specification of the signal that includes necessary and sufficient conditions.
+It's the king of specification you find in a dictionary. To state the obvious, that provides unambiguous semantics.
+It is recommended that all new signals added to VSS standard catalog shall contain definition.
+Recommended to start with a capital letter and end with a dot (`.`).
+
 **```comment ```**  *[optional]* `since version 3.0`
 A comment can be used to provide additional informal information on a signal.
 This could include background information on the rationale for the signal design,
@@ -50,15 +79,15 @@ Recommended to start with a capital letter and end with a dot (`.`).
 The minimum value, within the interval of the given ```type```, that the
 data entry can be assigned.
 If omitted, the minimum value will be the "Min" value for the given type.
-Cannot be specified if ```allowed``` is defined for the same data entry.
 
 **```max```** *[optional]*
 The maximum value, within the interval of the given ```type```, that the
 data entry can be assigned.
 If omitted, the maximum value will be the "Max" value for the given type.
-Cannot be specified if ```allowed``` is defined for the same data entry.
 
 **```unit```** *[optional]*
 The unit of measurement that the data entry has. See [Data Unit Types](/vehicle_signal_specification/rule_set/data_entry/data_unit_types/)
-chapter for a list of available unit types. This
-cannot be specified if ```allowed``` is defined as the signal type.
+chapter for a list of available unit types.
+
+**```allowed```** *[optional]*
+List of values allowed for this signal. See [Allowed](/vehicle_signal_specification/rule_set/data_entry/allowed/).

docs-gen/content/rule_set/includes.md

@@ -29,11 +29,13 @@ own branch to attach the included file to.
 
 An example of an include directive is:
 
-    #include doors.vpsec chassis.doors
+    #include doors.vspec Chassis.Doors
 
 The ```door.vspec``` section specifies the file to include.
 
-The ```chassis.doors``` section specifies that all signal entries in ```door.vspec``` should have their names prefixed with ```chassis.doors```.
+The ```Chassis.Doors``` section specifies that all signal entries in ```door.vspec``` should have their names prefixed with ```Chassis.Doors```.
+If there is a chain of include-files then all previous prefixes will be iherited.
+This means that the full prefix may be something like `Vehicle.Chassis.Doors`.
 
 If an included vspec file has branch or signal specifications that have
 already been defined prior to the included file, the new specifications in the