Evo: add more documentation and test files.

Author: adriweb

evo-doc/8xd2-gdb.md

@@ -0,0 +1,99 @@
+# `.8xd2` graph databases
+
+Sample file: `testData/evo/more/GDB1.8xd2`.
+
+Metadata:
+
+```text
+metaData.type    = 3
+metaData.version = 1
+metaData.flags   = 0
+metaData.name    = E890 0000
+```
+
+`E890` is `TOK_VAR_GDB1`.
+
+Body fields:
+
+```text
+version = 1
+size    = 836
+data    = Evo graph database payload
+```
+
+The payload is not the same flat byte layout as pre-Evo `.8xd` graph
+database data. The observed payload begins with a tokenized settings
+header, followed by records marked with ASCII tags:
+
+```text
+RAVI  variable/value record
+NQEI  equation display metadata record
+```
+
+Observed header words:
+
+```text
+000A
+E58B TOK_PARAM
+0001
+0000 TOK_EOS
+0000 TOK_EOS
+0000 TOK_EOS
+0010
+E5B2 TOK_RECTG
+E5B3 TOK_COORDON
+E606 TOK_GRIDOFF
+E5AC TOK_MEDGRAY
+E5A2 TOK_BLACK
+E608 TOK_LBLOFF
+E4F7 TOK_EXPR_ON
+E50B TOK_CRIT_PNTS_ON
+E5B7 TOK_BACK_OFF
+E5BB TOK_DETECT_ASYM_ON
+E60A TOK_WEBOFF
+```
+
+The first `RAVI` records hold Parametric window settings:
+
+```text
+token  payload
+E996   TMIN
+E997   TMAX
+E998   T_STEP
+E98F   XMIN
+E990   XMAX
+E991   XSCL
+E993   YMIN
+E994   YMAX
+E995   YSCL
+```
+
+The equation section alternates `NQEI` display metadata records and
+`RAVI` equation expression records. In this sample:
+
+```text
+pair       NQEI style  NQEI flags  NQEI color token  expr
+X1T/Y1T    8           2           E5A0 TOK_BLUE     X1T=2T, Y1T=-5.5T
+X2T/Y2T    6           4           E5A1 TOK_RED      X2T=cos(T/2, Y2T=sin(T/3
+X3T/Y3T    4           4           E5A4 TOK_GREEN    X3T=T^2, Y3T=-T
+X4T/Y4T    1           6           E5A3 TOK_MAGENTA  X4T=0, Y4T=T
+X5T/Y5T    1           0 or 1      E5A4 TOK_GREEN    empty
+X6T/Y6T    1           0 or 1      E5A5 TOK_ORANGE   empty
+```
+
+The X1T/Y1T pair was disabled in the equation editor when this GDB was
+exported. Its `NQEI` flags are `2`, while the enabled pairs in this
+sample use `4` or `6`. This suggests bit `0x04` is tied to enabled /
+plotted equation state, but the exact meaning of bit `0x02` is still
+not fully proven.
+
+The `NQEI` style values are not currently mapped to the legacy GDB
+`GraphStyle` enum. Observed values in this sample are:
+
+```text
+8  blue thin line
+6  red dotted line
+4  green connected line
+1  magenta thick line
+```
+

evo-doc/8xn2-number.md

@@ -13,9 +13,13 @@ metaData.name    = variable token, little-endian, then 0000
 
 The observed `metaData.flags = 8` top-level samples are `X.8xn2` and
 `Y.8xn2`. The same metadata flag appears on nested `XMIN`, `XMAX`,
-`YMIN`, and `YMAX` entries in `Window.8xw2`. This appears tied to
-special graph/window coordinate variables, not to the scalar data format
-itself.
+`YMIN`, and `YMAX` entries in `testData/evo/Window.8xw2`, while the
+same nested entries use `metaData.flags = 0` in
+`testData/evo/more/Window.8xw2` and
+`testData/evo/more/Window_parametric.8xw2`. This appears tied to
+metadata context for special graph/window coordinate variables, not to
+the scalar data format itself, and should not be required to recognize
+those variables.
 
 Body fields:
 

evo-doc/8xw2-window.md

@@ -1,6 +1,10 @@
 # `.8xw2` window settings
 
-Sample file: `Window.8xw2`.
+Sample files:
+
+- `testData/evo/Window.8xw2`
+- `testData/evo/more/Window.8xw2`
+- `testData/evo/more/Window_parametric.8xw2`
 
 Metadata:
 
@@ -35,14 +39,14 @@ size      = byte length of data; equals arraylen * 2
 data      = custom scalar payload
 ```
 
-Observed `Window.8xw2` entries:
+All observed `Window.8xw2` files contain the same entries:
 
 ```text
-00  E98F TOK_VAR_XMIN         metaData.flags 8, size 12
-01  E990 TOK_VAR_XMAX         metaData.flags 8, size 12
+00  E98F TOK_VAR_XMIN         size 12
+01  E990 TOK_VAR_XMAX         size 12
 02  E991 TOK_VAR_XSCL         size 6
-03  E993 TOK_VAR_YMIN         metaData.flags 8, size 12
-04  E994 TOK_VAR_YMAX         metaData.flags 8, size 12
+03  E993 TOK_VAR_YMIN         size 12
+04  E994 TOK_VAR_YMAX         size 12
 05  E995 TOK_VAR_YSCL         size 6
 06  E992 TOK_VAR_X_RES        size 6
 07  E9B2 TOK_VAR_DELTA_X      size 12
@@ -60,7 +64,12 @@ Observed `Window.8xw2` entries:
 19  E9AF TOK_VAR_PLOT_STEP    size 6
 ```
 
-Representative custom scalar payloads:
+The root sample has `metaData.flags = 8` on `XMIN`, `XMAX`, `YMIN`,
+and `YMAX`. The `more/Window.8xw2` and
+`more/Window_parametric.8xw2` samples have `metaData.flags = 0` on all
+nested entries, including those coordinate variables.
+
+Representative custom scalar payloads from `testData/evo/Window.8xw2`:
 
 ```text
 XMIN:
@@ -79,7 +88,52 @@ THETA_MAX:
   00 00 00 07 53 18 83 62 01 00 23 00
 ```
 
+Representative custom scalar payloads from
+`testData/evo/more/Window.8xw2`:
+
+```text
+XMIN:
+  00 00 00 00 00 00 90 15 ff 01 23 00
+
+XMAX:
+  00 00 00 27 63 79 70 15 01 00 23 00
+
+XSCL:
+  03 00 01 00 1f 00
+
+YMIN:
+  00 00 00 00 00 00 40 10 ff 01 23 00
+
+YMAX:
+  00 00 00 00 00 00 50 20 01 01 23 00
+
+X_RES:
+  02 00 01 00 1f 00
+
+DELTA_X:
+  00 95 11 09 11 96 93 54 01 fe 23 00
+
+DELTA_Y:
+  00 69 07 23 69 57 85 14 01 ff 23 00
+```
+
+`testData/evo/more/Window_parametric.8xw2` was captured while the
+calculator was in Parametric mode. It has the same entry order and
+metadata flags as `testData/evo/more/Window.8xw2`; the observed payload
+differences are:
+
+```text
+YMIN:
+  00 00 00 00 00 00 40 15 ff 01 23 00
+
+YMAX:
+  00 00 00 00 00 00 50 25 01 01 23 00
+
+DELTA_Y:
+  00 62 84 53 61 34 66 19 01 ff 23 00
+```
+
 The nested scalar `data` encoding matches the `.8xn2` custom scalar
 shape. The observed nested `metaData.flags = 8` values are limited to
-the X/Y min/max coordinate variables in this sample. Other window
-variables use `metaData.flags = 0`.
+the X/Y min/max coordinate variables in the root sample, but the newer
+samples show those same variables can also use `metaData.flags = 0`.

evo-doc/8xy2-equation.md

@@ -1,19 +1,29 @@
 # `.8xy2` equations
 
-Sample file: `Y1.8xy2`.
+Sample files:
+
+- `testData/evo/Y1.8xy2`
+- `testData/evo/more/X1T.8xy2` through `Y4T.8xy2`
 
 Metadata:
 
 ```text
 metaData.type    = 7
 metaData.version = 1
-metaData.flags   = 4 in the sample
+metaData.flags   = 4 or 6 in the samples
 metaData.name    = equation token, little-endian, then 0000
 ```
 
-The body has no `flags` key. The observed metadata flag `4` appears to
+The body has no `flags` key. The observed metadata flags appear to
 belong to equation graph/display state rather than to the expression
-token stream. More equation samples are needed before naming this bit.
+token stream. In the standalone parametric equation samples, `X1T` /
+`Y1T` through `X3T` / `Y3T` use `metaData.flags = 4`, while `X4T` /
+`Y4T` use `metaData.flags = 6`.
+
+The standalone equation files do not expose separate `lineStyle` or
+`color` keys. In the observed Evo GDB sample, pair style/color and
+enabled-state metadata are carried by adjacent `NQEI` records, not by
+the individual `.8xy2` expression records.
 
 For `Y1.8xy2`:
 
@@ -35,6 +45,21 @@ data      = byte string of little-endian 16-bit expression tokens
 This is structurally close to a `.8xp2` program, but the token stream is
 an expression rather than a multi-line program.
 
+Parametric samples:
+
+```text
+file      name bytes   metaData.flags  data hex                         code
+X1T.8xy2  50 e8 00 00  4               03 e4 13 e8 00 00               2T
+Y1T.8xy2  51 e8 00 00  4               2e e4 06 e4 0b e4 06 e4 13 e8 00 00
+                                                                        -5.5T
+X2T.8xy2  52 e8 00 00  4               41 e4 13 e8 2b e4 03 e4 00 00   cos(T/2
+Y2T.8xy2  53 e8 00 00  4               3f e4 13 e8 2b e4 04 e4 00 00   sin(T/3
+X3T.8xy2  54 e8 00 00  4               13 e8 2c e4 03 e4 00 00         T^2
+Y3T.8xy2  55 e8 00 00  4               2e e4 13 e8 00 00               -T
+X4T.8xy2  56 e8 00 00  6               01 e4 00 00                     0
+Y4T.8xy2  57 e8 00 00  6               13 e8 00 00                     T
+```
+
 `Y1.8xy2` token stream:
 
 ```text

evo-doc/evo-version-flags.md

@@ -92,16 +92,23 @@ variable-level image/Pic metadata flag rather than a pixel-data flag.
 
 ## `metaData.flags = 4` for equations
 
-The current `.8xy2` sample, `Y1.8xy2`, has:
+The current `.8xy2` samples use:
 
 ```text
-metaData.type  = 7
-metaData.flags = 4
+metaData.type    = 7
+metaData.flags   = 4 or 6
 ```
 
 The body has no `flags` key. This likely belongs to equation
-graph/display state, not to the expression token stream itself. More
-equation samples are needed before naming the bit.
+graph/display state, not to the expression token stream itself.
+
+In the observed Evo GDB sample, `testData/evo/more/GDB1.8xd2`, the
+equation display metadata is stored in `NQEI` records next to the
+equation expression records. The X1T/Y1T pair was disabled in the
+equation editor and has `NQEI` flags `2`; enabled pairs in the same
+file use `4` or `6`. This suggests bit `0x04` is tied to enabled /
+plotted equation state, while the exact meaning of bit `0x02` is still
+unknown.
 
 The online calculator WASM contains a field-name table that includes
 common fields and graph/equation metadata fields:
@@ -126,7 +133,7 @@ X.8xn2    metaData.flags = 8, body flags = 0
 Y.8xn2    metaData.flags = 8, body flags = 0
 ```
 
-and in nested scalar entries inside `Window.8xw2`:
+and in nested scalar entries inside `testData/evo/Window.8xw2`:
 
 ```text
 XMIN      metaData.flags = 8
@@ -135,15 +142,21 @@ YMIN      metaData.flags = 8
 YMAX      metaData.flags = 8
 ```
 
-Other window values in the same file use `metaData.flags = 0`.
+Other window values in the same file use `metaData.flags = 0`. A
+second window sample, `testData/evo/more/Window.8xw2`, and a
+Parametric-mode sample, `testData/evo/more/Window_parametric.8xw2`,
+use `metaData.flags = 0` for all nested entries, including `XMIN`,
+`XMAX`, `YMIN`, and `YMAX`.
+
 Therefore bit `0x08` is not simply "decimal value" or "approximate
 number"; many decimal scalar values use metadata flag `0`.
 
 The current best description is:
 
 ```text
 metaData.flags bit 0x08 appears tied to special graph/window coordinate
-variables, especially X/Y and X/Y min/max.
+variable metadata context, especially X/Y and X/Y min/max, but observed
+files do not always set it for those nested window variables.
 ```
 
 The precise semantic name is still unknown.