flesh out Readme

README.md

@@ -1,8 +1,12 @@
-# Live apps that can have text editor widgets
+# Example "freewheeling" app that can be modified without being restarted
 
-A template repo for building live apps that juggle text editor widgets. The
-editors support copy/paste, search, infinite undo, etc. You can't quite modify
-editor functionality live (yet?).
+Running this repo in isolation won't be very helpful. If you haven't yet,
+first check out [the driver app](https://codeberg.org/akkartik/driver.love).
+This repo is a template you can copy to create your own live apps that juggle
+text editor widgets. The editors support copy/paste, search, infinite undo,
+etc. You can't modify editor functionality live (yet?).
+
+[More information about the on-disk representation of freewheeling apps.](representation.md)
 
 This repo is a fork of [lines.love](http://akkartik.name/lines.html), an
 editor for plain text where you can also seamlessly insert line drawings.
@@ -11,22 +15,18 @@ modifications break something.
 
 ## Invocation
 
-To run from the terminal, [pass this directory to LÖVE](https://love2d.org/wiki/Getting_Started#Running_Games),
-optionally with a file path to edit.
+Run this app from the terminal, [passing its directory to LÖVE](https://love2d.org/wiki/Getting_Started#Running_Games)
 
-Alternatively, turn it into a .love file you can double-click on:
-```
-$ zip -r /tmp/text.love *.lua
-```
+To modify it live without restarting the app each time, install [the driver
+app](https://codeberg.org/akkartik/driver.love). Here's an example session
+using a fork of this repo:
 
-By default, it reads/writes the file `lines.txt` in your default
-user/home directory (`https://love2d.org/wiki/love.filesystem.getUserDirectory`).
-
-To open a different file, drop it on the app window.
+![making changes without restarting the app](assets/2.gif)
 
 ## Keyboard shortcuts
 
-While editing text:
+Up to you! But within the included editor widget if you use it:
+
 * `ctrl+f` to find patterns within a file
 * `ctrl+c` to copy, `ctrl+x` to cut, `ctrl+v` to paste
 * `ctrl+z` to undo, `ctrl+y` to redo
@@ -40,6 +40,11 @@ found anything amiss: http://akkartik.name/contact
 
 ## Known issues
 
+* Both freewheeling apps and the driver for them currently benefit from being
+  launched in terminal windows rather than by being clicked on in a desktop
+  OS. See [the driver app](https://codeberg.org/akkartik/driver.love/src/branch/main/README.md)
+  for details.
+
 * No support yet for Unicode graphemes spanning multiple codepoints.
 
 * No support yet for right-to-left languages.
@@ -69,6 +74,9 @@ from:
 
 Further forks are encouraged. If you show me your fork, I'll link to it here.
 
+* https://codeberg.org/akkartik/luaML.love - a "browser" for a Lua-based
+  markup language, loosely analogous to HTML except it's all Lua.
+
 ## Feedback
 
 [Most appreciated.](http://akkartik.name/contact)

representation.md

@@ -0,0 +1,55 @@
+# The on-disk representation of freewheeling apps
+
+When you start up a freewheeling app, you'll see a directory printed out in
+the parent terminal (always launch it from a terminal window):
+
+```
+new edits will go to /home/...
+```
+
+When editing such an app using the driver (see [README.md](README.md)), new
+definitions will go into this directory. Let's call it `$SAVE_DIR` in the rest
+of this doc.
+
+It is always safe to move such definitions into this repo. (We'll call it `.`
+in the rest of this doc.) You'll want to do this if you're sharing them with
+others, and it's also helpful if the driver crashes on your app. Moving
+definitions will never, ever change app behavior.
+
+```sh
+$ mv -i $SAVE_DIR/[0-9]* .  # should never clobber any existing files
+$ mv $SAVE_DIR/head .  # expected to clobber the existing file
+```
+
+Try looking inside the `head` file with a text editor. It'll contain a number,
+the current version of the _manifest_ for this app. For example:
+
+```
+478
+```
+
+This means the current state of the app is in a file called `0478-manifest`.
+If you moved the files you should see such a file in `.`. If you open this
+file, you'll see a JSON table from definition names to version ids. For
+example:
+
+```
+{ "a": 273, "b": 478}
+```
+
+This means the current definition of `a` is in `0273-a` and of `b` in
+`0478-b`.
+
+Poking around these files gets repetitive, so there's a tool to streamline
+things:
+
+```
+lua tools/stitch-live.lua 0478-manifest
+```
+
+`stitch-live.lua` takes a manifest file as its argument, and prints out all
+the definitions that make up the app at that version.
+
+To compare two versions of the app, use `stitch-live.lua` to copy the
+definitions in each into a separate file, and use a file comparison tool (e.g.
+`diff`) to compare the two files.