From 00ed30838a3fc5f1e08d61ddd7ac110767915b12 Mon Sep 17 00:00:00 2001 From: filifa Date: Tue, 19 Mar 2024 20:31:33 -0500 Subject: [PATCH] add readme --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..6edc7dc --- /dev/null +++ b/README.md @@ -0,0 +1,39 @@ +# xbit +`xbit` (xkcd backward in time) is a program for outputting historical events +while completing a task, inspired by [xkcd](https://xkcd.com/1017). The program +reads a SQLite database that stores event descriptions and timestamps, allowing +you to easily add your own events of interest. + +The provided SQL file will pre-populate the database with thousands of events +scraped from +[Wikipedia](https://en.wikipedia.org/wiki/Detailed_logarithmic_timeline). Of +these events, over 300 were manually given timestamps. + +## How to use +First create the database: +``` +sqlite3 timeline.db < timeline.sql +``` + +Then set the `XBIT_DB` environment variable to the database file. +``` +export XBIT_DB=./timeline.db +``` + +Call the program with `xbit -p `, like `xbit -p 0.25`. This will +calculate a timestamp using the formula from the xkcd comic, then output +information about the event in the database closest to that timestamp. See +`xbit -h` for more args. + +## Database details +* Due to the time-consuming nature of manually assigning timestamps, there are + many events that were scraped from Wikipedia but not given timestamps. You +may wish to skim through these and add timestamps to events you personally find +interesting. +* For an event to be output by `xbit`, it must have an entry in the database + with a unix timestamp of when the event occured. You can optionally set bools +in the "known" columns to indicate how precise your timestamp is. These may be +used to modify how the event is output. +* There are a few other columns that mainly exist as artifacts from the + scraping process. These are not used by `xbit` and do not need to be +populated.