Add a PARSING documentation (#1823)

- Add a PARSING.md doc in the user doc
- Add links to it all over the doc
- Fix a few doc issues
- Fix #1572

_config.yml

@@ -134,39 +134,46 @@ defaults:
 
   -
     scope:
-      path: "doc/user/COLOR_MAPS.md"
+      path: "doc/user/PARSING.md"
     values:
       parent: User Documentation
       nav_order: 8
 
   -
     scope:
-      path: "doc/user/FINAL_SHADER.md"
+      path: "doc/user/COLOR_MAPS.md"
     values:
       parent: User Documentation
       nav_order: 9
 
   -
     scope:
-      path: "doc/user/DESKTOP_INTEGRATION.md"
+      path: "doc/user/FINAL_SHADER.md"
     values:
       parent: User Documentation
       nav_order: 10
 
   -
     scope:
-      path: "doc/user/PLUGINS.md"
+      path: "doc/user/DESKTOP_INTEGRATION.md"
     values:
       parent: User Documentation
       nav_order: 11
 
+  -
+    scope:
+      path: "doc/user/PLUGINS.md"
+    values:
+      parent: User Documentation
+      nav_order: 12
+
   -
     scope:
       path: "doc/user/LIMITATIONS_AND_TROUBLESHOOTING.md"
     values:
       title: Limitations and Troubleshooting
       parent: User Documentation
-      nav_order: 12
+      nav_order: 13
 
 # libf3d doc
   -

doc/libf3d/OPTIONS.md

@@ -24,7 +24,7 @@ Option|Type<br>Default<br>Trigger|Description|F3D option
 :---:|:---:|:---|:---:
 scene.animation.autoplay|bool<br>false<br>load|Automatically start animation.|\-\-animation-autoplay
 scene.animation.index|int<br>0<br>load|Select the animation to load.<br>Any negative value means all animations (glTF only).<br>The default scene always has at most one animation.|\-\-animation-index
-scene.animation.speed_factor|double<br>1<br>render|Set the animation speed factor to slow, speed up or even invert animation.|\-\-animation-speed-factor
+scene.animation.speed_factor|ratio<br>1<br>render|Set the animation speed factor to slow, speed up or even invert animation.|\-\-animation-speed-factor
 scene.animation.time|double<br>optional<br>load|Set the animation time to load.|\-\-animation-time
 scene.camera.index|int<br>optional<br>load|Select the scene camera to use when available in the file.<br>The default scene always uses automatic camera.|\-\-camera-index
 scene.up_direction|string<br>+Y<br>load|Define the Up direction. It impacts the grid, the axis, the HDRI and the camera.|\-\-up
@@ -149,7 +149,7 @@ It's even more true with the few optional boolean options as std::optional has a
 ## String API
 
 The most generic and flexible API, as it rely on parsing and string generation.
-The documentation about option parsing is upcoming.
+See the [parsing documentation](../user/PARSING.md) for more details.
 
 ```cpp
   f3d::engine eng = f3d::engine::create();

doc/user/COMMANDS.md

@@ -111,3 +111,4 @@ Command syntax is similar to bash, as in they will be split by "token" to be pro
  - Other escaped character will be processed as if the escape was not present, eg: `set scene.up.direction +\Z`
  - Unfinished quoted section is invalid, eg: `set scene.up.direction "+Z`
  - A escape at the end is also invalid, eg: `set scene.up.direction +Z\`
+ - Options values are [parsed](PARSING.md) according to their types.

doc/user/PARSING.md

@@ -0,0 +1,59 @@
+# Parsing options
+
+When setting options from the [CLI Options](OPTIONS.md), the [commands](COMMANDS.md) or using the [libf3d options string API](../libf3d/OPTIONS.md#string-api), the values are parsed according to their type. If parsing fails, the value is not changed.
+
+The following types are supported:
+ - bool: A boolean, true or false.
+ - int: A signed integer.
+ - double: A floating point number.
+ - ratio: A double dividend over a double divisor, stored in a double.
+ - string: A string of characters.
+
+As well as a list for each of these types, noted as
+ - vector\<type\>
+
+## Bool
+
+The following formats are supported when parsing a bool, case insensitive:
+ - true/false
+ - yes/no
+ - on/off
+ - 1/0
+
+When formatting a bool into a string, true/false is used.
+
+## Int
+
+Int parsing is supported using [std::stoi](https://en.cppreference.com/w/cpp/string/basic_string/stol) and check
+that the whole string is parsed.
+
+When formatting an int into a string, [std::to_string](https://en.cppreference.com/w/cpp/string/basic_string/to_string) is used.
+
+## Double
+
+Double parsing is supported using [std::stod](https://en.cppreference.com/w/cpp/string/basic_string/stol) and check
+that the whole string is parsed.
+
+When formatting a double into a string, [std::ostringstream](https://en.cppreference.com/w/cpp/io/basic_ostringstream) is used
+with removing the point and precision when the value is exactly an integer.
+
+## Ratio
+
+The following formats are supported when parsing a string into a ratio:
+ - percent% where percent is a double
+ - dividend/divisor where both are doubles
+ - double
+
+Percent, dividend, divisor are then parsed as double.
+
+When formatting a ratio into a string, it is formatted as a double.
+
+## String
+
+String are parsed and formatted as is.
+
+## Vectors
+
+Vector tokens are separated by `,`, tokens are then parsed using their respective types.
+
+When formatting a vector into a string, individual token are formatted according to their type and separated using `,`.

doc/user/QUICKSTART.md

@@ -56,6 +56,7 @@ For **default scene** formats, certain default values are set automatically:
  - normal-scale: 1.0
  - metallic: 0.0
  - roughness: 0.3
+ - camera-orthographic: false
 
 They will be overridden when using corresponding [options](OPTIONS.md).
 

doc/user/README_USER.md

@@ -8,6 +8,7 @@
 - [How to use animations in F3D.](ANIMATIONS.md)
 - [How to configure F3D using a configuration file.](CONFIGURATION_FILE.md)
 - [The different commands available in F3D.](COMMANDS.md)
+- [How are options values are parsed in F3D.](PARSING.md)
 - [How to use colormaps in F3D.](COLOR_MAPS.md)
 - [How to a use custom final shader in F3D.](FINAL_SHADER.md)
 - [How to integrate F3D in your desktop.](DESKTOP_INTEGRATION.md)