Improve READMEs to use --connection :memory:

examples/README.md

@@ -0,0 +1,79 @@
+# Nanobot Examples
+
+Get a `nanobot` binary
+and then run any of these examples from its directory.
+
+### Binary
+
+1. get a `nanobot` binary, either by
+  - downloading a [release](https://github.com/ontodev/nanobot.rs/releases)
+  - using `cargo build` to build `target/debug/nanobot`
+2. make sure that the `nanobot` binary is on your
+   [`PATH`](https://opensource.com/article/17/6/set-path-linux)
+
+Then inside the directory for the specific example,
+you have two options for running Nanobot:
+temporary and persistent.
+
+### Temporary
+
+1. run `nanobot serve --connection :memory:`.
+2. open <http://0.0.0.0:3000> in your web browser
+3. press `^C` (Control-C) to stop the web server
+
+This will create an "in-memory" SQLite database,
+load and validate all the tables,
+then start the Nanobot server on your local machine,
+so you can work with it in your web browser.
+When you stop the Nanobot server (using Control-C),
+the in-memory SQLite database will be deleted,
+along with all your unsaved changes.
+When you run `nanobot serve --connection :memory:` again,
+Nanobot will start over with a new in-memory SQLite database.
+
+If you want to keep a SQLite database file
+to reuse, view, or modify,
+then use the "persistent" approach to running Nanobot.
+
+### Persistent
+
+1. run `nanobot init` to load and validate the tables,
+   creating the `nanobot.toml` configuration file
+   (if it does not exist)
+   and the `.nanobot.db` SQLite database file
+2. run `nanobot serve` to start the web server,
+3. open <http://0.0.0.0:3000> in your web browser
+4. press `^C` (Control-C) to stop the web server
+5. delete the `.nanobot.db` file when you are done with it
+
+The persistent approach will create a SQLite database file
+that you can work with
+while the Nanobot server is running,
+or after it has stopped.
+If you stop the Nanobot server
+and then start it again with `nanobot serve`,
+Nanobot will reuse this SQLite database file --
+it will not create a new database or reload the TSV files.
+To start fresh,
+delete the `.nanobot.db` file
+and run `nanobot init` again to recreate it.
+
+You can view and modify the `.nanobot.db` SQLite database file
+using the `sqlite3` command-line tool,
+other command-line tools like [Visidata](https://www.visidata.org),
+or GUI applications like [DB Browser for SQLite](https://sqlitebrowser.org).
+
+## Troubleshooting
+
+If you're running into errors,
+see if the debugging messages help.
+You will want a `nanobot.toml` configuration file.
+If it does not exist in the directory,
+running `nanobot init` will create it.
+You can configure more verbose logging
+by adding this to the `nanobot.toml` file:
+
+```toml
+[logging]
+level = "DEBUG"
+```

examples/penguins/README.md

@@ -1,4 +1,4 @@
-# Examples: Penguins
+# Nanobot Examples: Penguins
 
 This directory contains a series of Nanobot examples,
 based on the
@@ -10,62 +10,39 @@ and the
 a member of the
 [Long Term Ecological Research Network](https://lternet.edu/).
 
+See the [README](../README.md) in the parent directory for more information.
+
 ## Examples
 
-The simplest "table" example demonstrates most of Nanobot's features.
+The simplest "[table](table/)" example
+demonstrates most of Nanobot's features.
 The following examples show additional functionality
 and increasingly powerful workflows.
 
-1. table
+1. [table](table/)
 2. tables
 
-## Running Examples
-
-You can run each of these examples individually from its directory.
-First get a `nanobot` binary,
-either by downloading a
-[release](https://github.com/ontodev/nanobot.rs/releases),
-or by using `cargo build` to build `target/debug/nanobot`.
-Second, make sure that the `nanobot` binary is on your
-[`PATH`](https://opensource.com/article/17/6/set-path-linux).
-Then inside the directory:
-
-1. run `nanobot init` to load and validate the tables,
-   creating the `nanobot.toml` configuration file
-   and the `.nanobot.db` SQLite database file
-2. run `nanobot serve` to start the web server,
-   then open <http://localhost:3000> in your web browser
-3. press `^C` (Control-C) to stop the web server
-4. delete the `.nanobot.db` file
-
-If you're running into errors,
-you can configure more verbose logging
-by adding this to the `nanobot.toml` file:
-
-```toml
-[logging]
-level = "DEBUG"
-```
-
 ## Example Data
 
-The `generate.py` script generates random data
+The `generate.py` script generates "synthetic" (i.e. random) data
 with columns and ranges of values similar to Palmer Penguins,
 as many rows as we want,
-and a specified rate of randomly generated errors in the data.
+and a specified rate of randomly generated errors.
 (Note that the probability distribution of the random values
 is not the same as the real Palmer Penguins data.)
 This lets us generate as many rows as we like,
 with whatever error rate we choose,
 and test Nanobot on small or large tables of realistic data.
 
-Each example includes a `src/data/penguin.tsv` table
+Each example directory includes a `src/data/penguin.tsv` table
 with 1000 rows and a 10% error rate.
 
 You can test variations of the `penguin.tsv` table
 by using `generate.py` to generate more random rows
 with a specified error rate.
 Run `python3 generate.py --help` for more information.
-For example, to test the "table" example
+For example, to test the "[table](table/)" example
 using a million rows with a 1% error rate,
 run `python3 generate.py table/src/data/penguin.tsv 1000000 1`.
+You can restore original table
+by running `git checkout table/src/data/penguins.tsv`.

examples/penguins/table/README.md

@@ -2,9 +2,10 @@
 
 This basic Nanobot example includes four tables:
 
-- `src/schema/table.tsv`: all the tables
+- `src/schema/table.tsv`: table definitions for all the tables
 - `src/schema/column.tsv`: column definitions for all the tables
-- `src/schema/datatype.tsv`: datatypes definitions used by the columns
+- `src/schema/datatype.tsv`: datatype definitions used by the columns
 - `src/data/penguin.tsv`: synthetic data about penguins
 
-See the README in the parent directory for more information.
+Run this example with `nanobot serve --connection :memory:`.
+See the [README](../README.md) in the parent directory for more information.