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