add readme

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 <percentage>`, 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.