flesh out Readme

[?]

Jan 8, 2023, 4:11 PM

2DVVKKVA6PJ7VKYLGPQ22AXUB6ZWFMPWB445PRDZJDNLURUFDNDQC

Dependencies

[2] BPYWIU62 new fork: template for live programming with editor widgets
[3] PNBKVYZ4 more cogent onboarding instructions
[4] UGYRO7TO forgot to commit documentation for the commandline arg
[5] IDGP4BJZ new known issue with drawings
[6] UEE5W7WJ document one more shortcut
[7] MOAEVTKJ clean up a few more loose ends
[8] ZTMRQZSW Readme
[9] D4FEFHQC flesh out Readme
[10] CZRMAMSB clearer discription of how to run lines.love
[11] MD3W5IRA new fork: rip out drawing support
[12] KQWIMWJ5 deemphasize the terminal in Readme
[13] FS2ITYYH record a known issue
[*] R5QXEHUI somebody stop me
[*] A2TQYJ6J .
[*] SBS2F7GR link to export tool

Change contents

file addition: representation.md (----------)

[15.2]

# 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.
file addition: assets (d--r------)

[15.2]
file addition: 2.gif (----------)

[0.1833]
replacement in README.md at line 1

[3.6]→[2.16:62](∅→∅)

# Live apps that can have text editor widgets

[3.6]

[3.11634]

# Example "freewheeling" app that can be modified without being restarted
replacement in README.md at line 3

[3.11635]→[2.63:252](∅→∅)

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?).

[3.11635]

[3.18]

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)
replacement in README.md at line 18

[3.21]→[3.21:171](∅→∅),[3.171]→[3.162:163](∅→∅),[3.162]→[3.162:163](∅→∅),[3.163]→[3.172:242](∅→∅),[3.242]→[3.11833:11863](∅→∅),[3.11863]→[3.273:277](∅→∅),[3.273]→[3.273:277](∅→∅)

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.

Alternatively, turn it into a .love file you can double-click on:
```
$ zip -r /tmp/text.love *.lua
```

[3.21]

[3.222]

Run this app from the terminal, [passing its directory to LÖVE](https://love2d.org/wiki/Getting_Started#Running_Games)
replacement in README.md at line 20

[3.223]→[3.11864:11929](∅→∅),[3.11929]→[3.296:378](∅→∅),[3.296]→[3.296:378](∅→∅)

By default, it reads/writes the file `lines.txt` in your default
user/home directory (`https://love2d.org/wiki/love.filesystem.getUserDirectory`).

[3.223]

[3.378]

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:
replacement in README.md at line 24

[3.379]→[3.11930:11983](∅→∅)

To open a different file, drop it on the app window.

[3.379]

[3.504]

![making changes without restarting the app](assets/2.gif)
replacement in README.md at line 28

[3.662]→[3.662:682](∅→∅)

While editing text:

[3.662]

[3.682]

Up to you! But within the included editor widget if you use it:
edit in README.md at line 43

[3.13]

[16.79]

* 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.
edit in README.md at line 76

[3.12675]

[17.145]

* https://codeberg.org/akkartik/luaML.love - a "browser" for a Lua-based
markup language, loosely analogous to HTML except it's all Lua.