Improving docs

README.md

@@ -1,9 +1,11 @@
 > [!WARNING]  
-> Migration and adaptation from the other repository is done.  
-> Documentation and missing features still ongoing.
+> Some features are still missing, they are tracked in the [TODO](./TODO.md) file.
+> Documentation is an ongoing effort.
 
 `vs-templ` is a simple preprocessor for XML files. It can be used statically generate new files from a template definition.  
-Static templates can be seen as extremely simple programs which are interpreted by this preprocessor. They consume input data also formatted as XML, and generate some output XML file. In theory, it is possible for data to be expressed in other formats (eg. JSON) as well, but at the moment this is not a supported feature.
+Static templates can be seen as extremely simple programs which are interpreted by this preprocessor.  
+They consume input data also formatted as XML, and generate some output XML file.  
+In theory, it is possible for data to be expressed in other formats (eg. JSON) as well, but at the moment this is not a supported feature.
 
 ## Examples
 

TODO.md

@@ -42,13 +42,6 @@ This is a list of commands which are currently supported:
 
 # Milestones
 
-## `v0.3.0`
-
-- [x] At least feature parity with what it was before moving it out of `vs-fltk`.
-- [x] Some degree of documentation.
-- [x] Add support for `element.text()` & `element.name()` in query.
-- [x] Replace the current split implementation with something requiring less allocations
-
 ## `v0.3.5`
 
 - [x] At least feature parity with what it was before moving it out of `vs-fltk`.

docs/calc.md

@@ -2,52 +2,62 @@
 title: Computing expressions
 ---
 
-Tentative specs for the expressions used in:
+Tentative specs for higher order expressions.  
+They extends the current expression by starting with `:`. Instead of being interpreted as usual, they represent the serialization of a program in reverse polish notation (RPN).  
+This is going to run, and the single element left out on stack will be taken as the final expression.
 
-- `calc`
-- its prop variant
-- in filters within `for`
-- maybe in `for-range`, replacing simple numbers.
-
-My plan is to add a stack-based language in polish notation, constrained to have only one root.  
-For example:
+For example, assuming the environment had `i` set to `1`:
 
 ```
-add:2 int:2 [{var-a}/path~attribute] error add:2 [2] [3]
+: `#name-` `{i}` concat.*`
 ```
 
-Compressed it would be something like:
+will return an expression of type string embedding the value `name-1`.
 
-```
-+   int[{var-a}/path~attribute]!
-    +[2][3]
-```
+Type casting should be explicit, but some operations like `concat` might cast automatically.  
+The delimiters are needed, since some types of expressions like strings can contain spaces and other escaping characters.
+
+## Design
+
+### Why RPN?
 
-Inside `[...]` there are path expressions. Type casting should be explicit. The delimiters are needed since expressions can contain spaces and other escaping characters.  
 The reason for going with something like this are:
 
 - to avoid a complex parser for what will end up being a quite marginal feature
 - to avoid the arbitrary precedence rules usually associated to algebraic operator
-- to be fast and easy to compile into native code via tcc
+- to be fast and easy to compile into native code via tcc if so desired (but for now it is just going to be interpreted)
+
+### Possible extensions
 
-I will probably allow braces, just for the sake of readability. At some point I might validate them if present just to highlight potential bugs.
+I will probably allow braces, just for the sake of readability, and to avoid being explicit about the number of arguments a function should take.  
+At some point I might validate them if present just to highlight potential bugs.
 
-Options for implementation:
+### Options for implementation
 
-- Add them to this repo directly.
-- Build a schema based generator and use it. This way it is easier to build different backends and integrate fast dispatching via perfect minimal hashing functions.
-- Find a library already implementing this design and use that.
+Assumption: these programs are very short. As such their source is not read in streaming, but it is all resident in memory while compiling. This allows the usage of `string_views` and the buffer itself in place of allocating too many temporary objects in memory. Hence, processing these expressions should be very memory efficient.
 
-Assumption: these programs are very short. As such their source is not read in streaming, but it is all resident in memory while compiling. This allows the usage of string_views and the buffer itself in place of allocating too many temporary objects in memory. Hence, processing these expressions should be very memory efficient.
+- Add the vm to this repo directly.
+- Build a generic vm library for which specific instances can be generated downstream of a schema.  
+  This way it is easier to build different backends and integrate fast dispatching via perfect minimal hashing functions.
+- ~~Find a library already implementing this design and use that.~~ no success in that
 
 ## Operators
 
+### Array operators
+
 - `count` `[expr] #`, count the dimensionality of expression returning a 1-dimensional scalar number
 - `reduce` `[initial] [reducer] [container] V`, reduces to a 1-dimensional object each element of the container starting from the initial expression (sum, join etc)
 - `filter` `[container] F`, filters elements out of a container
 - `map` `[expr] [container] M`, maps container based on a lamba
 
+### String operators
+
 - `concat` `[container] cat`, simplified version of `V` where based on the type, the 0 is used as initial and the reducer is the natural `+` operation
+
+### Boolean operators
+
 - `if` `[false] [true] [condition] ?`
 
+### Common algebraic operators
+
 - And all the typical math operations as usual

docs/for-developers.md

@@ -10,11 +10,15 @@ title: Information for developers
 
 To build, test and install it you can just use normal meson commands.
 
-## Using it
+## Embedding it
 
-Right now this project is only available as a meson package.  
+Right now, this project is only available as a meson package.  
 I might consider adding `cmake` later on to gain a wider compatibility.
 
+If `pugixml` is already provided as a dependency in the main project, that will be used.
+
+The CLI in `src/app` shows all that is needed to use `vs.templ` as a library.
+
 ## Versioning
 
 At this time, this repository is only available as a [meson](https://mesonbuild.com/) package.  

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: vs.templ
-repo_url: https://github.com/lazy-eggplant/vs-templ
+repo_url: https://github.com/lazy-eggplant/vs.templ
 site_dir: dist/website/docs
 docs_dir: docs