Updating docs

TODO.md

@@ -12,7 +12,8 @@
 - [ ] Optimization for lower-end systems by reducing explicit memory allocations if possible and adopting string views.
 - [ ] Support for string natural order (111 > 22).
 - [ ] Properly show ctx information while logging
-- [ ] Expose a mechanism to allow externally defined expressions? Not sure about this one, but it might be good when embedding this library.
+- [ ] Expose a mechanism to allow externally defined expressions? Not sure about this one, but it might be good when embedding this library.\
+- [ ] Strings in dot notation when ordering by random should apply hashing and comparison to each block sequentially.
 
 ## `v1.0.0`
 

docs/faq.md

@@ -2,7 +2,7 @@
 title: FAQ
 ---
 
-## Why not XSLT?
+## Why not using XSLT?
 
 `vs-templ` was first developed in the context of [vs](https://github.com/karurochori/vs-fltk) to express static, yet parametric, components.  
 While the XML ecosystem is often reliant on XSLT as a preprocessor, this option was quickly dismissed in the parent project for several reasons:
@@ -15,21 +15,21 @@ While the XML ecosystem is often reliant on XSLT as a preprocessor, this option
 Hence, `vs` vendors `vs.templ` its own XSLT-ish preprocessor.  
 Still, nothing about its semantics or syntax is directly tied to `vs`, so I am distributing it as a separate package, hoping it can reach a wider adoption.
 
-## Why not [handlebars](https://handlebarsjs.com/) or [mustache](https://mustache.github.io/)
+## Why not [handlebars](https://handlebarsjs.com/) or [mustache](https://mustache.github.io/)?
 
-That class of templating solutions cannot understand XML. As such, the resulting generation might not be proper XML.
+This class of templating solutions cannot understand XML.  
+As such, the resulting generation will not ensure something syntactically correct is generated.
 
 ## Is there a SAX implementation?
 
-No, there is not.
+No, there is not.  
 Some features don't strictly require a DOM, but they don't really translate well in terms of a pull parser.  
-The memory peak usage would not be much better either for many reasonable templates, so there is no real incentive to implement this preprocessor based on a different backend for now.  
-Still, if you want to do so you are very welcome!
+The memory peak usage would not be much better either for most reasonable templates, so there is no real incentive to implement this preprocessor based on a different backend for now.  
+If one needs to access data sources with thousands or millions of entries before processing and setting the window of interest, external sources are the right approach, and they are fully supported.  
+That way, there is no need to load the entire data source in memory as it would happen with an XML file.
 
 ## Can we support other input formats for the dataset?
 
 In theory, it would be possible for data to be expressed in other formats (eg. JSON) as well, but at the moment this is not a supported feature and is not likely going to be in scope for quite a while.  
-However, a native integration of SQLite to use it as data-source is almost surely going to happen at some point.  
-
 For the time being, you can offer external data sources of whatever type by implementing the optional `loadfn` downstream.  
-This would allow `vs.templ` to indirectly work with any data source you want.
+This allows `vs.templ` to indirectly work with any data source you desire.

docs/ordering.md

@@ -1,14 +1,35 @@
+Ordering criteria are used in two situations:
 
-## Strings
-### Encoding ordering
-### Lexicographic ordering
-### Pseudo-random ordering
-### Dot modifier
+- in `order-by` attributes of cycles of every type except `for-range`
+- as basic boolean binary operator in the RPN vm
 
-## Nodes
+## Order types
 
-## Integers
+### `ASC` & `DESC`
 
-## Floats
+### `RANDOM`
 
-## Booleans
+Data of any type is first hashed.
+For integers, floats and booleans this only involves their immediate data.  
+For strings the characters buffer. Order will be based on the numerical comparison of the hash.  
+For strings adopting the dot notation, each token is handled separately in hashing and comparing.
+
+## Comparison operators for supported types.
+
+### Nodes
+
+### Integers
+
+### Floats
+
+### Booleans
+
+### Strings
+
+#### Natural ordering
+
+#### Lexicographic ordering
+
+#### Pseudo-random ordering
+
+#### Dot modifier

docs/repl-vm.md

@@ -2,6 +2,11 @@
 title: Computing expressions
 ---
 
+> [!WARNING]  
+> This document was originally just a draft to keep as reference while implementing the RPN vm.  
+> As such, its content does not fully represent features has they have been implemented.  
+> Also, some functions reported as _not implemented_ will never be, or some are yet to report.
+
 Tentative specs for higher order expressions to add some degree of freedom in calculations.  
 They are still interpreted as expression, starting with `:`. The content of the expression represent the serialization of a program in reverse polish notation (RPN).  
 The VM is going to run it, and the only element left on stack is taken as the final expression value.