Adapted docs to be in sync with vss-tools rework

Signed-off-by: Sebastian Schleemilch <[email protected]>

Author: sschleemilch

docs-gen/content/rule_set/basics.md

@@ -96,7 +96,7 @@ if the meta-data of the moved node hasn't changed.
 * Nodes which are deprecated will be removed from the specification, either in the second minor update or, if earlier, the next major update.
 
 ### Example
-```YAML
+```yaml
 Vehicle.Navigation.CurrentLocation:
   type: branch
   description: The current latitude and longitude of the vehicle.

docs-gen/content/rule_set/branches.md

@@ -9,7 +9,7 @@ signals.
 
 A branch entry example is given below:
 
-```YAML
+```yaml
 Trunk:
   type: branch
   description: All signals related to the rear trunk

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

@@ -10,7 +10,7 @@ It is expected, that any value not mentioned in the array is considered an error
 The datatype of the array elements is the `datatype` defined for the data entry itself.
 For `attributes` it is possible to optionally set a default value.
 
-```YAML
+```yaml
 SteeringWheel.Position:
   datatype: string
   type: attribute
@@ -46,7 +46,7 @@ The actual value of the signal is expected to contain a subset of the values spe
 
 Example:
 
-```YAML
+```yaml
 DogBreeds:
   datatype: string[]
   type: attribute

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

@@ -18,7 +18,7 @@ or else it should be defined as a sensor instead.
 
 Below is an example of a complete attribute describing engine power
 
-```YAML
+```yaml
 MaxPower:
   datatype: uint16
   type: attribute
@@ -31,19 +31,19 @@ It is possible to give default values also for arrays. In this case square brack
 
 Example 1: Empty Array
 
-```YAML
+```yaml
   default: []
 ```
 
 Example 2: Array with 3 elements, first element has value 1, second element value 2, third element value 0
 
-```YAML
+```yaml
   default: [1, 2, 0]
 ```
 
 Full example, array with two elements, first with value2, second with value 3:
 
-```YAML
+```yaml
 SeatPosCount:
   datatype: uint8[]
   type: attribute

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

@@ -37,7 +37,7 @@ definition*, wherein it's specified. By default the size of the array is undefin
 By the optional keyword `arraysize` the size of the array can be specified.
 The following syntax shall be used to declare an array:
 
-```YAML
+```yaml
 # Array of datatype uint32, by default size of the array is undefined
 datatype: uint32[]
 # Optional: specified number of elements in the array
@@ -62,7 +62,7 @@ corresponding data stream.
 A camera can be a good example of it. The Data Entry for the camera
 and the corresponding video stream could look like:
 
-```YAML
+```yaml
 Camera:
   type: branch
   description: Information about the camera and how to connect to the video stream

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

@@ -102,7 +102,7 @@ This is not a problem as it always from context is clear whether a name refers t
 
 This could be a hypothetical content of a VSS datatype file
 
-```
+```yaml
 Types:
   type: branch
 
@@ -123,15 +123,15 @@ Types.DeliveryInfo.Receiver:
 
 This struct definition could then be referenced from the VSS signal tree
 
-```
+```yaml
 Delivery:
   datatype: Types.DeliveryInfo
   type: sensor
 ```
 
 The datatype file may contain sub-branches and `#include`-statements just like regular VSS files
 
-```
+```yaml
 Types:
   type: branch
 
@@ -168,7 +168,7 @@ They may support read of parts of signal, e.g. `DeliveryList.Receiver`
 It is allowed to use a struct type in an array
 
 
-```
+```yaml
 DeliveryList:
   datatype: Types.DeliveryInfo[]
   type: sensor
@@ -178,7 +178,7 @@ DeliveryList:
 By default the array has an arbitrary number of element and may be empty.
 If a fixed size array is wanted the keyword `arraysize` can be used to specify size:
 
-```
+```yaml
 DeliveryList:
   datatype: Types.DeliveryInfo[]
   arraysize: 5
@@ -201,7 +201,7 @@ For array datatypes (like above) VSS implementations may support several mechani
 
 It is allowed to refer to a structure datatype from within a structure
 
-```
+```yaml
 OpenHours:
   type: struct
   description: A struct datatype containing information on open hours
@@ -245,17 +245,16 @@ The order of declaration/definition shall not matter.
 As signals and datatypes are defined in different trees this is a topic only for struct definitions referring to other struct definitions.
 A hypothetical example is shown below. An item in the struct `DeliveryInfo` can refer to the struct `OpenHours` even if that struct
 is defined further down in the same file.
-If using `-vt < file>` multiple times all files except the first will be treated similar to overlays.
+If using `--types <file>` multiple times all files except the first will be treated similar to overlays.
 This means that is allowed to define `A.B.C` in multiple files, but then subsequent (re-)definitions will overwrite
-what has been defined previously.
+what has been defined previously. Note that if type files want to use structs from other files that the dependent
+files are specified first. Therefore the order of given type files matters.
 
-```
+```yaml
 DeliveryInfo:
   type: struct
   description: A struct datatype containing info for each delivery
 
-...
-
 DeliveryInfo.Open:
   datatype: OpenHours
   type: property
@@ -264,9 +263,6 @@ DeliveryInfo.Open:
 OpenHours:
   type: struct
   description: A struct datatype containing information on open hours
-
-...
-
 ```
 
 ## Inline Struct

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

@@ -9,7 +9,7 @@ weight: 20
 It is in VSS possible for signals to specify a unit of measurement from a list of predefined data units.
 For most signals in the VSS standard catalog, a data unit has been selected. A typical example is `Vehicle.Speed`, as shown below.
 
-```
+```yaml
 Vehicle.Speed:
   datatype: float
   type: sensor
@@ -26,6 +26,7 @@ as `km/h` (with float as datatype). A user interface or API may show or request
 and a transport protocol may send speed in another unit, possibly also involving scaling and offset.
 But in protocols not explicitly specifying data units (like [VISS](https://raw.githack.com/w3c/automotive/gh-pages/spec/VISSv2_Core.html))
 it is expected that `Vehicle.Speed` is sent and received as `km/h` (without scaling or offset).
+However since units define possible `allowed-datatypes` the given `datatype` has to match the allowed ones.
 
 VSS does not offer any syntax for defining alternative units for a specific signal.
 The VSS project has specified for all units a corresponding quantity e.g. `velocity` for `km/h`.
@@ -36,7 +37,7 @@ the quantity `velocity`, it is not specified how they relate to each other.
 In some cases it is natural to omit the data unit. This concerns typically signals where datatype `string` is used,
 but also signals where the value just represents a number (dimensionless quantities), like in the example below:
 
-```
+```yaml
 Vehicle.Cabin.DoorCount:
   datatype: uint8
   type: attribute
@@ -51,7 +52,7 @@ In some cases, the definition on how to calculate the signal value is obvious, l
 below. It is likely that all VSS users will calculate fuel level in the same way, i.e. the meaning of a fuel level of 50%
 is well agreed, the liters of fuel in the tank is exactly 50% of nominal capacity.
 
-```
+```yaml
 Vehicle.Powertrain.FuelSystem.Level:
   datatype: uint8
   type: sensor
@@ -69,7 +70,7 @@ Some vehicles might monitor actual wear, others might estimate it based on vehic
 This is in VSS called a logical range, a VSS user knows what range to use but are free to define the formula for calculating the value.
 Values from different vehicles (of different make/model) can not always be compared, as the formula used for calculation may differ.
 
-```
+```yaml
 Vehicle.Powertrain.Transmission.ClutchWear:
   datatype: uint8
   type: sensor
@@ -81,8 +82,8 @@ Vehicle.Powertrain.Transmission.ClutchWear:
 ## Supported Data Units in VSS Standard Catalog
 
 The VSS syntax does not in itself specify what units can be used, the unit attribute as declared for signals in *.vspec files is optional and can contain an arbitrary string value.
-[VSS-Tools](https://github.com/COVESA/vss-tools) however require that all units used are defined,
-and at is also a requirement for signals in the VSS standard catalog.
+[VSS-Tools](https://github.com/COVESA/vss-tools) however require that all units used are defined
+and therefore is also a requirement for signals in the VSS standard catalog.
 Units are defined by including them in a unit file with syntax as described below.
 One or more unit files can be specified by the `-u` parameter and, if not given, the tools search for a file `units.yaml`
 in the same directory as the root *.vspec file.
@@ -129,7 +130,7 @@ using different units but defined with the same quantity.
 
 Example:
 
-```
+```yaml
 m:
   definition: Length measured in meters
   unit: meter
@@ -158,8 +159,7 @@ The `deprecation` keyword can be used to indicate that a specific unit may be re
 Tooling shall preferably give a warning if a signal uses a deprecated unit or the unit used belongs to a deprecated quantity.
 The reason should preferably list when and why the unit is deprecated, a hypothetical example is given below:
 
-```
-
+```yaml
   inch:
     definition: Distance measured in inches
     unit: inch
@@ -171,29 +171,14 @@ The reason should preferably list when and why the unit is deprecated, a hypothe
     quantity: distance
 ```
 
-
-The unit syntax has recently been changed. To simplify transition to the new syntax it is recommended that
-tooling also supports unit files using the old syntax described below.
-
-```
-units:
-  [
-    <vss-unit-identifier>: # Typically unit abbreviation, like km/h or mm, but
-      label: <string> # Replaced with "unit"
-      description: <string> # Replaced with "definition"
-      quantity: <string>
-  ]*
-```
-
 ## Quantity file syntax
 
-Defining quantities is recommended, but currently optional for backward compatibility reasons.
+Defining of quantities is required.
 If tooling supports quantity files it can verify that all units provided in unit files
 use defined quantities.
 For the VSS standard catalog it is required that matching quantities have been defined for all units.
 
 ```
-
   [
     <vss-quantity-identifier>: # Identifier preferably taken from a standard, like ISO 80000
       definition: <string>
@@ -226,9 +211,7 @@ As this unit is not commonly used and not described in any standards, it might b
 That is however only informative, as it a custom unit a downstream implementation supporting unit conversion may not support automatic conversion
 of furlong to other units.
 
-
-
-```
+```yaml
 units:
   furlong:
     definition: Length measured in furlong, 1 furlong equals 201.1680 m

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

@@ -11,7 +11,7 @@ Actuators are used to control the desired value of a property. Some properties i
 A data entry for a sensor or actuator defines its members. A data
 entry example is given below:
 
-```YAML
+```yaml
 Speed:
   type: sensor
   description: The vehicle speed.

docs-gen/content/rule_set/includes.md

@@ -6,7 +6,7 @@ weight: 6
 
 An include directive in a vspec file will read the file it refers to and the
 contents of that file will be inserted into the current buffer in place of the
-include directive.  The included file will, in its turn, be scanned for
+include directive. The included file will, in its turn, be scanned for
 include directives to be replaced, effectively forming a tree of included
 files.
 
@@ -21,6 +21,8 @@ The include directive has the following format:
     #include <filename> [prefix]
 
 The ```<filename>``` part specifies the path, relative to the file with the ```#include``` directive, to the vspec file to replace the directive with.
+Additionally, include paths to search for the file can be added when using `vss-tools` using the `-I/--include-dirs`.
+The order of include paths to be searched is first the relative path of the vspec specifying the include and then given include paths in the given order.
 
 The optional ```[prefix]``` specifies a branch name to be
 prepended to all signal entries in the included file. This allows a vspec file

docs-gen/content/rule_set/instances.md

@@ -55,7 +55,7 @@ example for details.
 
 The example from above in the specification:
 
-```YAML
+```yaml
 # Cabin.vspec
 Door:
   type: branch
@@ -73,7 +73,7 @@ Door.SomeSignal:
 ```
 
 
-```yml
+```yaml
 # SingleDoor.vspec
 
 #
@@ -103,7 +103,7 @@ instance definitions, then the last found definition will be used.
 As an example, if three row of doors are needed, then the default VSS instance definition
 can be overridden by redefining the Door branch as shown in the example below.
 
-```YAML
+```yaml
 #Redefinition changing number of rows from 2 to 3
 #The redefinition must appear "after" the original definition
 Vehicle.Cabin.Door:
@@ -126,7 +126,7 @@ and that offers heating for both windshields. But that is not the case for all v
 it is not even certain that all vehicles have two windshields. This sections gives recommendations on how
 to use VSS for a vehicle if the VSS specification does not offer an exact match of the capabilities of the vehicle.
 
-```YAML
+```yaml
 Windshield:
   type: branch
   instances: ["Front", "Rear"]
@@ -159,7 +159,7 @@ of the following methods are recommended:
 - Redefine the branch. If a vehicle for example does not have a rear windshield
 then append a redefinition at the end of the VSS:
 
-```YAML
+```yaml
 Vehicle.Body.Windshield:
   type: branch
   instances: ["Front"]