From 39bd5394bf91411721bb5e06fdfc04aa20c63542 Mon Sep 17 00:00:00 2001 From: "Christopher R. Nelson" Date: Mon, 22 Jan 2024 21:19:37 -0500 Subject: 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. --- README | 2 +- README.org | 57 ------------------------------ README.rst | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ hall.scm | 4 +-- 4 files changed, 119 insertions(+), 60 deletions(-) delete mode 100644 README.org create mode 100644 README.rst 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") -- cgit v1.2.3