add readme

This commit is contained in:
filifa 2024-03-19 20:31:33 -05:00
parent 9b480b8d40
commit 00ed30838a
1 changed files with 39 additions and 0 deletions

39
README.md Normal file
View File

@ -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.