doc: README.org->README.rst

cgit and friends (as well as my poor slow-to-reprogram brain) like
ReStructuredText better than they like org-mode files. Let's give it to
them because the org-mode file was only used as hall auto-generated it.

4 files changed, 119 insertions, 60 deletions

diff --git a/README b/README
index 314e17d..92cacd2 120000
--- a/README
+++ b/README
@@ -1 +1 @@
-README.org
\ No newline at end of file
+README.rst
\ No newline at end of file
diff --git a/README.org b/README.org
deleted file mode 100644
index df50fa6..0000000
--- a/README.org
+++ /dev/null
@@ -1,57 +0,0 @@
-# -*- mode: org; coding: utf-8; -*-
-
-#+TITLE: README for Reading-Heap
-
-* Reading-Heap
-
-Reading-Heap: a service and clients for managing your media consumption order.
-
-* Description
-
-** What is 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 can 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 via a (upcoming) emacs client.
-
-* Installation
-
-** Dependencies
-
-- [[https://www.gnu.org/software/guile/][Guile 3.0]] (or later)
-- [[https://gitlab.com/a-sassmannshausen/guile-config][guile-config]]
-- [[https://github.com/aconchillo/guile-json][guile-json]]
-- [[https://github.com/jerry40/guile-simple-zmq][Guile-Simple-ZMQ]]
-- [[https://zeromq.org/][ZeroMQ]]
-
-** Build Dependencies
-
-- [[https://www.gnu.org/software/automake/][GNU AutoMake]]
-- [[https://www.gnu.org/software/autoconf/][GNU AutoConf]]
-- (optionally) [[https://gitlab.com/a-sassmannshausen/guile-hall][Guile Hall]] 0.4.1+
-
-** Procedure
-
-The usual autotools make process applies here.
-
-#+BEGIN_SRC bash
-  ./autogen.sh
-  ./configure
-  make
-  sudo make install
-#+END_SRC
-
-* Usage
-
-** Command-line client
-
-#+BEGIN_SRC bash
-  reading-heap-client new --priority -1 --title "Foundation Trilogy" --author "Issac Asimov" --location "SF Bookshelf" --unique_id "0739444050"
-  reading-heap-client next
-#+END_SRC
-
-** TODO Web client
-
-Details Forthcoming
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
diff --git a/hall.scm b/hall.scm
index 28a38bc..64f7b63 100644
--- a/hall.scm
+++ b/hall.scm
@@ -38,8 +38,8 @@ read is, without having to devote your own brain power to sorting them.")
           (text-file "COPYING")
           (text-file "HACKING")
 	  (text-file "NEWS")
-          (symlink "README" "README.org")
-          (org-file "README")))
+          (symlink "README" "README.rst")
+          (text-file "README.rst")))
         (infrastructure
          ((scheme-file "hall")
           (text-file ".gitignore")