Updated docs and website generation

.gitignore

@@ -5,12 +5,6 @@ subprojects/*
 !subprojects/packagefiles/
 /wraps/cfltk
 *.autogen.*
-/dist/*
-!/dist/wasm-demo/
-!/dist/root-website/
-!/dist/website/
-/dist/website/doxygen/*
-/dist/website/docs/*
 /node_modules/
 /bun.lockb
 /private

README.md

@@ -1,16 +1,17 @@
 > [!WARNING]  
 > Documentation is an ongoing effort.
 
-`vs-templ` is a simple preprocessor for XML files.  
-It can be used to statically generate new files from a template definition and a data source.  
-Static templates can be seen as extremely simple programs serialized in XML which are interpreted by this preprocessor.
-They consume input data (also XML) to generated output XML.
+`vs-templ` is a simple XML preprocessor.  
+It can be used to statically generate new files from a _template_ definition and a _data source_.  
+Static templates can be seen as extremely simple programs which are themselves serialized as XML, and interpreted by this preprocessor.  
+While running, they consume input data (also XML, but could be anything else in principle) to generated output XML.
 
-Details about the syntax & supported features are covered in a [dedicated page](https://lazy-eggplant.github.io/vs.templ/next/docs), or you might want to check some [examples](https://lazy-eggplant.github.io/vs.templ/wasm-demo/).
+Details about the syntax & supported features are covered in a [dedicated page](https://lazy-eggplant.github.io/vs.templ/next/docs).  
+You might want to check some [examples](https://lazy-eggplant.github.io/vs.templ/wasm-demo/) for a less verbose introduction to the syntax.
 
-## Examples
+### Typical template definition
 
-### Simple `for` cycle
+Given an XML data source:
 
 ```xml
 <items>
@@ -20,7 +21,7 @@ Details about the syntax & supported features are covered in a [dedicated page](
 </items>
 ```
 
-and
+and a template:
 
 ```xml
 <ul>
@@ -32,7 +33,7 @@ and
 </ul>
 ```
 
-results in
+once processed, the final result will be:
 
 ```xml
 <ul>
@@ -42,43 +43,52 @@ results in
 </ul>
 ```
 
-For more examples check the [online playground](https://lazy-eggplant.github.io/vs.templ/wasm-demo/)!
+For more examples, please check the [online playground](https://lazy-eggplant.github.io/vs.templ/wasm-demo/).
 
 ## Usage
 
-The functionality of this template builder is exposed as a library.  
-You can link it to your own application either statically or dynamically.
-This repository is also providing a self-contained CLI utility as a system utility.
+This preprocessor can be used in one of two ways:
 
 ### As a library
 
-`vs-templ` is specifically intended to be embedded in other applications.  
-If you want to integrate `vs-templ` in your own, [this](./docs/for-developers.md) is where to start.
+`vs.templ` is specifically intended to be embedded in other applications.  
+You can use it either as a dynamic or a static library.  
+If you want to integrate `vs.templ` in your own codebase, [this](./docs/for-developers.md) is where to start.
 
 ### Via its CLI
 
-This repo also provides a minimal wrapper to use it via command line.
+This repo provides a minimal standalone wrapper to access most features offered by this library from command line.
 
-```
-vs.tmpl <template-file> <data-file> [namespace=`s:`]
+```bash
+vs.templ <template-file> <data-file> [namespace=`s:`]
 ```
 
 There is also an alternative format:
 
-```
-vs.tmpl [namespace=`s:`]
+```bash
+vs.templ [namespace=`s:`]
 ```
 
 with both files added via pipes, like `vs.tmpl <(cat template.xml) <(cat data.xml)`
 
+#### vs.templ.js
+
+If you don't want to install `vs.templ`, it can be used standalone if you have a compatible WASM runtime on your system.  
+WASM builds are attached to releases.
+
+```bash
+bun run ./vs.templ.js [...]
+```
+
 ## Installation
 
 ```bash
 meson setup build
 meson install -C build
 ```
 
-should work on most systems. I highly suggest a dry run by setting `DESTDIR` somewhere safe to ensure expected behaviour.
+This works on most systems.  
+Still, to ensure expected behaviour, I highly suggest a dry run by setting `DESTDIR` somewhere safe.
 
 ## Projects using `vs.templ`
 
@@ -97,3 +107,5 @@ While the XML ecosystem is often reliant on XSLT as a preprocessor, this option
 
 Hence, `vs` vendors 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.
+
+If you have more questions, I collected some in a [FAQ](./docs/faq.md) document.

TODO.md

@@ -1,10 +1,18 @@
 # Milestones
 
+## `v0.4.1`
+
+- [ ] In the UI for the demo, lock button to generate while fetching examples
+- [ ] In the UI for the demo, add a loader as the first boot is quite slow
+- [ ] Fill in the docs at least of the public interface
+
 ## `v0.4.x`
 
 - [ ] Much more robust test-suite with higher coverage.
 - [ ] 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.
 
 ## `v1.0.0`
 

dist/.gitignore

@@ -0,0 +1,2 @@
+/website/doxygen/
+/website/docs/

Doxyfile → dist/configs/Doxyfile

@@ -41,7 +41,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "vs.fltk"
+PROJECT_NAME           = "vs.templ"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -1268,7 +1268,7 @@ GENERATE_HTML          = YES
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = html
+HTML_OUTPUT            = .
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).
@@ -1891,7 +1891,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

mkdocs.yml → dist/configs/mkdocs.yml

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

dist/website/index.html

@@ -55,7 +55,7 @@
             <a href="https://github.com/lazy-eggplant/vs.templ"><button><i class="fa-brands fa-github"></i>
                     Source</button></a>
             <a href="./docs"><button><i class="fa-solid fa-book"></i> Main documentation</button></a>
-            <a href="./doxygen/html"><button><i class="fa-solid fa-book"></i> Doxygen reference</button></a>
+            <a href="./doxygen"><button><i class="fa-solid fa-book"></i> Doxygen reference</button></a>
             <a href="../wasm-demo"><button>Online demo</button></a>
             <button disabled><i class="fa-solid fa-comment"></i> Help</button>
         </nav>

docs/faq.md

@@ -17,7 +17,7 @@ Still, nothing about its semantics or syntax is directly tied to `vs`, so I am d
 
 ## 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 can be unsound.
+That class of templating solutions cannot understand XML. As such, the resulting generation might not be proper XML.
 
 ## Is there a SAX implementation?
 
@@ -29,4 +29,7 @@ Still, if you want to do so you are very welcome!
 ## 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.
+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.

docs/for-developers.md

@@ -31,8 +31,8 @@ The CLI in `src/app` shows everything that is needed to use `vs.templ` as a libr
 
 ### C bindings
 
-At this time, no C bindings are provided since all my downstream project don't need them, and pugixml is C++ only.  
-Still, the public interface is quite thin, so they can be easily introduced if so desired.
+At this time, no C bindings are provided. My downstream project don't need them, and pugixml is C++ only.  
+Still, the public interface of this library is quite thin, so they can be easily introduced if so desired.
 
 ## Versioning
 

docs/ordering.md

@@ -0,0 +1,14 @@
+
+## Strings
+### Encoding ordering
+### Lexicographic ordering
+### Pseudo-random ordering
+### Dot modifier
+
+## Nodes
+
+## Integers
+
+## Floats
+
+## Booleans

include/vs-templ.hpp

@@ -77,11 +77,27 @@ struct preprocessor{
         pugi::xml_node root_data;
 
     public:
+        /**
+         * @brief Construct a new preprocessor object
+         * 
+         * @param root_data 
+         * @param root_template 
+         * @param prefix 
+         * @param logfn 
+         * @param includefn 
+         * @param loadfn 
+         * @param seed 
+         */
         inline preprocessor(const pugi::xml_node& root_data, const pugi::xml_node& root_template, const char* prefix="s:", logfn_t logfn = default_logfn, includefn_t includefn = default_includefn,  loadfn_t loadfn = default_loadfn, uint64_t seed = 0){
             init(root_data,root_template,prefix,logfn,includefn,loadfn,seed);
         }
 
         void init(const pugi::xml_node& root_data, const pugi::xml_node& root_template, const char* prefix="s:", logfn_t logfn = default_logfn, includefn_t includefn = default_includefn,  loadfn_t loadfn = default_loadfn,  uint64_t seed = 0);
+
+        /**
+         * @brief 
+         * 
+         */
         void reset();
 
         /**
@@ -91,7 +107,18 @@ struct preprocessor{
          */
         inline void load_env(std::map<std::string,symbol>& env){symbols.reset(env);symbols.set("$",root_data);}
 
+        /**
+         * @brief 
+         * 
+         * @return pugi::xml_document& 
+         */
         inline pugi::xml_document& parse(){_parse({});return compiled;}
+
+        /**
+         * @brief 
+         * 
+         * @param str 
+         */
         inline void ns(const char* str){ns_prefix = str;strings.prepare(str);}
 
         std::array<uint64_t,2> hash(const symbol& ref);

test/cases/when.prop.xml

@@ -7,7 +7,6 @@
         <identity>
             <h1 s:when=": false"></h1>
             <h2 s:when=": true"></h2>
-
         </identity>
     </template>