1 files changed, 116 insertions, 0 deletions
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..f09a862
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,116 @@
+README for Reading-Heap
+***********************
+
+Reading-Heap
+============
+
+Reading-Heap: a service and clients for managing your media consumption
+order.
+
+Description
+===========
+
+What is a Reading Heap?
+-----------------------
+
+It's a *heap* of things you want to *read*. Shocking, I know. But what
+does that mean? Simply, it means you add a priority when you put an item
+on the heap, and when you ask the heap what to read it will take your
+priorities into account (another name for a heap is a priority queue,
+after all).
+
+What sets Reading Heap apart?
+-----------------------------
+
+Reading-Heap is implemented as a service, so any zmq-enabled language
+can write a client for it. You could possibly write a client to add an
+article from your phone via a web service, grab the details into your
+wayland clipboard from the command line, and maybe one day file it into
+your org-mode agenda buffer.
+
+Installation
+============
+
+Dependencies
+------------
+
+* `Guile 3`_ (or later)
+* `guile-config`_
+* `guile-json`_
+* `Guile-Simple-ZMQ`_
+* `ZeroMQ`_
+
+Build Dependencies
+------------------
+
+* `GNU AutoMake`_
+* `GNU AutoConf`_
+* `Guile Hall`_ (optionally)
+
+Procedure
+---------
+
+.. role:: bash(code)
+   :language: bash
+
+The usual autotools make process applies here. We've put the call to
+:bash:`hall build -x` in the autogen.sh script, and only run it if we
+find `Guile Hall`_.
+
+.. code-block:: bash
+
+   ./autogen.sh
+   ./configure
+   make
+   sudo make install
+
+Usage
+=====
+
+Server
+------
+
+To start this whole thing, put the following in your favorite autostart
+mechanism, or just run it from the command line.
+
+.. code-block:: bash
+
+   rh-server
+
+If you need to shut it down, you can use the command-line client.
+
+.. code-block:: bash
+
+   rh-client shutdown
+
+Command-line Client
+-------------------
+
+Let's say you're a refined sort with good taste, and you want to read
+that collection of Emily Dickinson poems you've had next to your bed for
+the last year. You might do this:
+
+.. code-block:: bash
+
+   rh-client new --priority 1 --title "The Poems of Emily Dickinson: Reading Edition" --author "Emily Dickinson (Author) RW Franklin (Editor)" --location "Nightstand"
+
+To get something back out, you would issue a 'next' command:
+
+.. code-block:: bash
+
+   rh-client next
+
+To let the system know you've been edified by the verse:
+
+.. code-block:: bash
+
+   rh-client consume
+
+.. _`Guile 3`: https://www.gnu.org/software/guile/
+.. _`guile-config`: https://gitlab.com/a-sassmannshausen/guile-config
+.. _`guile-json`: https://github.com/aconchillo/guile-json
+.. _`Guile-Simple-ZMQ`: https://github.com/jerry40/guile-simple-zmq
+.. _`ZeroMQ`: https://zeromq.org/
+.. _`GNU AutoMake`: https://www.gnu.org/software/automake/
+.. _`GNU AutoConf`: https://www.gnu.org/software/autoconf/
+.. _`Guile Hall`: https://gitlab.com/a-sassmannshausen/guile-hall