Update documentation

Clarifies string/float/double.
Reformat recommendatations to state that they also are rules for VSS catalog
Remove enum recommendation

Fixes COVESA#705
Fixes COVESA#706
Partially solves COVESA#700
Fixes COVESA#662

Signed-off-by: Erik Jaegervall <[email protected]>

docs-gen/content/rule_set/basics.md

@@ -24,16 +24,18 @@ as some implementations may treat VSS identifiers as case insensitive.
 
 ## Addressing Nodes
 
+VSS supports only a single tree, that means that all signals must belong to the same root.
+In the VSS standard catalog the root branch is called `Vehicle`, so all signals
+must be part of the `Vehicle` tree.
+
 Tree nodes are addressed, left-to-right, from the root of the tree
 toward the node itself. Each element in the name is delimited with
-a period ("."). The element hops from the root to the leaf is called ```path```.
+a period ("."). The element hops from the root to the leaf is called ```path```
 
 For example, the dimming status of the rearview mirror in the cabin is addressed:
 
-
     Vehicle.Cabin.RearviewMirror.Dimmed
 
-
 If there are an array of elements, such as door rows 1-3, they will be
 addressed with an index branch:
 
@@ -109,17 +111,25 @@ The VSS specification must adhere to YAML syntax. To keep the standardized VSS s
 
 ### Naming Conventions
 
-The recommended naming convention for node elements is to use camel case notation starting with a capital letter. It is recommended to use only
-`A-Z`, `a-z` and `0-9` in node names. For boolean signals it is recommended to start the name with `Is`.
+Node names in VSS must follow the restrictions specified in [Yaml](https://yaml.org/spec/1.2.2/#chapter-5-character-productions) i.e. must only use the printable subset of the Unicode character set.
+
+Tools and Generators supporting VSS may however put additional restrictions on which characters that are allowed. For maximum portability, node names in the VSS standard catalog must fulfill the following rules
+
+* Node names in the VSS standard catalog shall use camel case notation starting with a capital letter.
+* Node names in the VSS standard catalog shall use only `A-Z`, `a-z` and `0-9` in node names.
+* Boolean signals must start with `Is`.
+* Full path of node names must be unique also when using case insensitive comparison.
+  It is for example not allowed to have both `Vehicle.Abc` and `Vehicle.ABC` in the standard catalog
+  even if that is valid VSS as VSS is case sensitive.
 
 Examples:
 
 ```
-SomeBranch.AnotherBranch.MySignalName
 Vehicle.Cabin.Door.Row1.Left.IsLocked
+SomeOtherTree.AnotherBranch.MySignalName
 ```
 Naming convention for string literals can be found in the [chapter](/vehicle_signal_specification/rule_set/data_entry/allowed/)for specifying allowed values.
 
 ### Line Length
 
-It is recommended that line length for files in this repository ( e.g. `*.vspec` and `*.md` files) shall not exceed 120 characters. This is not a strict limit, it is e.g. not recommended to split long URLs present in files over multiple lines.
+It is recommended that line length for files in this repository ( e.g. `*.vspec` and `*.md` files) shall not exceed 120 characters. This is not a strict limit, it is e.g. not recommended to split long URLs over multiple lines.

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

@@ -27,17 +27,17 @@ in a list.  Only values can be assigned to the data entry, which are
 specified in this list.
 
 The `datatype` specifier gives the datatype of the individual elements of the `allowed`
-list. In general `allowed:` is valid for all datatypes, including integer- and float-based datatypes, unless othwerise specified.
+list. In general `allowed:` is valid for all datatypes, including integer- and float-based datatypes, unless otherwise specified.
 
 ## Recommendation on String values
 
-For string values used for `default` and `allowed` statements it is recommended to start with `A-Z`
-and then use only `A-Z`, `0-9` and underscore (`_`).
-It is recommended to use single quotes (`'`) as tooling otherwise might handle literals like `OFF` as boolean values with unexpected result.
+String values used for `default` and `allowed` statements may contain characters from the printable subset of the Unicode character set.
+If using [COVESA VSS-tools](https://github.com/COVESA/vss-tools) it is recommended to use single quotes (`'`) around values as tooling otherwise might handle literals like `OFF` as boolean values with unexpected result.
 It is recommended not to specify a dedicated value corresponding to "unknown" or "undefined" unless there is a relevant use-case for that particular signal.
 The background is that a signal with an array of allowed values shall be handled just as any other signal.
 If e.g. the value of current speed or vehicle weight is unknown, then the vehicle shall not publish the corresponding signal.
-Similarly, for the example above, if the steering wheel position is unknown then `SteeringWheel.Position`shall not be published.
+Similarly, for the example above, if the steering wheel position is unknown then
+`SteeringWheel.Position` shall not be published.
 
 ## Allowed values for array datatypes
 

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

@@ -20,9 +20,14 @@ int32      | signed 32-bit integer      | -2147483648 | 2147483647
 uint64     | unsigned 64-bit integer    | 0    | 2^64 - 1
 int64      | signed 64-bit integer      | -2^63 | 2^63 - 1
 boolean    | boolean value              | 0/false | 1/true
-float      | floating point number      | -3.4e -38 | 3.4e 38
-double     | double precision floating point number | -1.7e -300 | 1.7e 300
-string     | character string           | n/a  | n/a
+float      | IEEE 754-2008 binary32 floating point number | -3.40e 38 | 3.40e 38
+double     | IEEE 754-2008 binary64 floating point number | -1.80e 308 | 1.80e 308
+string     | character string (unicode)          | n/a  | n/a
+
+## Strings
+
+Strings in VSS supports the unicode character set. Actual encoding like UTF-8 or UTF-16 is not
+specified by VSS, that is to up to the Protocol/API/SDK implementing VSS support to decide.
 
 ## Arrays
 
@@ -57,6 +62,8 @@ The time and date format shall be as shown below, where the sub-second data and
 YYYY-MM-DDTHH:MM:SS.ssssssZ
 ```
 
+VSS also supports the unit `unix-time` that can be used together with datatype `uint32`/`uint64`/`int64`to indicate that the signal value correspond to number of non-leap seconds which have passed since 00:00:00 UTC on Thursday, 1 January 1970.
+
 ## Data Streams
 
 Data Entries, which describe sensors offering binary streams