Add shutdown command, and refactor server impl

zmq: refactor server to functions
     add shutdown function (end recursion)
media: fix bug with missing directories
rh-client: support shutdown function
rh-server: update to use build variables

1 files changed, 124 insertions, 12 deletions

diff --git a/doc/reading-heap.texi b/doc/reading-heap.texi
index 5e2735a..d1f2557 100644
--- a/doc/reading-heap.texi
+++ b/doc/reading-heap.texi
@@ -2,15 +2,15 @@
 @c -*-texinfo-*-
 
 @c %**start of header
-@setfilename reading-heap.info
+@setfilename guile-reading-heap.info
 @documentencoding UTF-8
-@settitle Reading-Heap Reference Manual
+@settitle Reading Heap Reference Manual
 @c %**end of header
 
 @include version.texi
 
 @copying
-Copyright @copyright{} 2023 Christopher R. Nelson
+Copyright @copyright{} 2024 Christopher R. Nelson
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -22,11 +22,11 @@ Documentation License''.
 
 @dircategory The Algorithmic Language Scheme
 @direntry
-* Reading-Heap: (reading-heap).   
+* Reading Heap: (guile-reading-heap).      Manage your heap of to-consume media.
 @end direntry
 
 @titlepage
-@title The Reading-Heap Manual
+@title The Guile Reading Heap Manual
 @author Christopher R. Nelson
 
 @page
@@ -40,21 +40,133 @@ Edition @value{EDITION} @*
 @contents
 
 @c *********************************************************************
-@node Top
-@top Reading-Heap
+@node Top, Introduction, (dir), (dir)
+@top Reading Heap
 
-This document describes Reading-Heap version @value{VERSION}.
+This document describes Reading Heap version @value{VERSION}.
 
 @menu
-* Introduction::                Why Reading-Heap?
+* Introduction::                What is Reading-Heap?
+* Installation::                How to install Reading-Heap?
+* Quickstart::                  Getting Started
+* Client Subcommands::          How to operate the client
+
+* Contributing::                Contributing to the Reading Heap project
+* Acknowledgments::             Thanks!
 @end menu
 
 @c *********************************************************************
-@node Introduction
+@node Introduction, Installation, Top, Top
 @chapter Introduction
 
-INTRODUCTION HERE
+What is Reading Heap? It's a @emph{heap} of things you want to
+@emph{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 next, it will take your priorities into
+account and provide you one of the most important entries as a
+suggestion.
+
+How does this improve on the reading list you have taped to your
+refrigerator? Primarily by removing the cognitive burden on choosing
+what's next. It also lets you specify that, for instance, you have in
+your head you want to read ``Battlefield Earth'', but it's really more
+of a sometime before you die thing. You give it the appropriate
+priority, and it won't clutter your heap when what you really should
+be reading about @uref{https://spritely.institute/hoot, Hoot
+WebAssembly}.
+
+@c *********************************************************************
+@node Installation, Quickstart, Introduction, Top
+@chapter Installation
+
+First, check your favorite package manager. Reading Heap will likely
+not be there, but it's the best way to acquire end-user software and
+should be a first port of call.
+
+If (when) that fails, you can continue with the Guile Autotools build.
+
+@heading Using Autotools
+
+Installing Reading Heap should be as easy as:
+@enumerate
+@item
+Install the dependencies:
+@itemize
+@item
+autoconf
+@item
+automake
+@item
+pkg-config
+@item
+guile
+@item
+texinfo
+@item
+guile-config
+@item
+guile-json
+@item
+guile-simple-zmq
+@item
+zeromq
+@end itemize
+@item
+Run @code{autoreconf -vif && ./configure && make && sudo make install}
+@end enumerate
+
+Exactly how you install the dependencies will depend on your distro.
+While installing Guile libraries using autotools you will need to
+augment the @env{GUILE_LOAD_PATH} and the
+@env{GUILE_LOAD_COMPILED_PATH} environment variables to ensure that
+the installed code will be available to Guile & Guile applications.
+You could accomplish this by adding the following to your shell of
+choice's startup files (for example, .bash_profile or .zshrc)
+
+@example
+
+export GUILE_LOAD_PATH=/usr/local/share/guile/site/3.0/
+export GUILE_LOAD_COMPILED_PATH=/usr/local/lib/guile/3.0/site-ccache/
+export PATH=/usr/local/bin/:$PATH
+
+@end example
 
-This documentation is a stub.
+@c *********************************************************************
+@node Quickstart, Client Subcommands, Installation, Top
+@chapter Quickstart
+
+To get quickly started, run the command @command{rh-server --write}
+
+@c *********************************************************************
+@node Client Subcommands, Contributing, Quickstart, Top
+@chapter Client Subcommands
+
+Reading Heap is sub-divided into different subcommands designed to achieve
+specific tasks. You can pass the @option{--help} switch to any of the
+subcommands to get concise documentation.
+
+@c *********************************************************************
+@node Contributing, Acknowledgments, Client Subcommands, Top
+@chapter Contributing
+
+Reading Heap is an open project and we actively invite contribution.
+Get in touch with the project on
+@email{christopher.nelson@@languidnights.com} or on the
+@uref{https://codeberg.org/languidnights/reading-heap, the project
+forge page}. The project welcomes ideas, bug reports, patches, or
+feedback.
+
+@c *********************************************************************
+@node Acknowledgments, , Contributing, Top
+@chapter Acknowledgments
+
+Reading Heap would be impossible without the input of various people.
+Much of the technical details were ``borrowed'' from guile-hall and
+guile-config. The
+@uref{https://www.gnu.org/software/guile/manual/index.html, Guile
+Manual} is a quite well-written, if occasionally dense, source of
+information on some of the thornier issues. And
+@uref{https://systemcrafters.net, the System Crafters community}
+helped some confidence issues I was having :-)
 
 @bye