1 files changed, 83 insertions, 0 deletions
diff --git a/docs/trblcache.md b/docs/trblcache.md
new file mode 100644
index 0000000..7351fb0
--- /dev/null
+++ b/docs/trblcache.md
@@ -0,0 +1,83 @@
+# Cacheing
+
+Nearly all caching happens in `$(pwd)/.trblcache` by default (hereafter `$CACHE`),
+here's a reminder of the process `trblcache` uses when building documentation:
+
+0. Scan: find all source files under the input folders whose extension has
+   a registered comment form (`c`, `h`, `cpp`, `hpp`, `lua`, `py`, `sql`,
+   `md`, `dot`, plus any `-f` additions).
+0. Extract: run each file through an AWK program that emits chunk files
+   into `$CACHE/chunks/`.
+0. Render: for each chunk, strip directives, run the renderer, and append
+   output to `$CACHE/namespace/<namespace>/index.html`.
+0. Assemble: write `main.layout`, `nav.partial`, `global.meta`, and CSS
+   into `$CACHE/namespace/`.
+0. Build: apply the layout/template tokens to each namespace page and
+   write the final site to `-o <dest>` (default `$CACHE/built`).
+
+Of these, only chunk extraction can be cached. Cacheing works by first
+creating a file under `$CACHE/last_processed/<path>` when a file is processed,
+and then on subsequent processing, ignore files if their `$CACHE/last_processed/<path>`
+file timestamp is newer than the `<path>` timestamp. If your filesystem does
+not support file timestamps, `trbldoc` will never assume the cache is invalid,
+and will serve stale data. If you are on such a system, always run with `-C` to
+force `trbldoc` to generate new chunks.
+
+## Notes
+
+### No cached chunks
+The rendered chunks, generally, cannot be cached. If the user provided their
+own tooling (i.e. bash scripts) for `trbldoc`, `trbldoc` cannot check for updates
+to the scripts in order to invalidate the cached rendered chunk. Checking
+file last updated times won't work, if a script invokes another script or relies
+on any system environment the user's updates won't take. Example:
+
+```
+project
+| src/
+| | file1.c - last updated 1d ago
+| tools/
+| | checker.sh - last updated 1d ago
+| | graph.sh - last updated 30s ago
+```
+
+file1.c
+
+```c
+...
+/* tools/checker.sh tools/graph.sh
+strict graph { 
+  a -- b
+  a -- b
+  b -- a [color=blue]
+}
+*/
+...
+```
+
+checker.sh
+
+```sh
+#!/bin/sh
+
+if [ -z "$(command $1 -V)" ]; then
+    echo "Could not find $1"
+    exit -1
+fi
+
+exec $1
+```
+
+graph.sh
+
+```sh
+#!/bin/sh
+
+exec dot
+```
+
+It would be impossible for `trbldoc` to determine that `tools/checker.sh` uses
+`tools/graph.sh` without forcing it to run in a hermetically sealed sandbox that
+carefully controls what environment, filesystem, and other programs may be run.
+Such heavy sandboxing is against the vision of `trbldoc` as a simple, single-file
+documentation generator.