\input texinfo
@c -*-texinfo-*-

@c %**start of header
@setfilename guile-reading-heap.info
@documentencoding UTF-8
@settitle Reading Heap Reference Manual
@c %**end of header

@include version.texi

@copying
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
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying

@dircategory The Algorithmic Language Scheme
@direntry
* Reading Heap: (guile-reading-heap).      Manage your heap of to-consume media.
@end direntry

@titlepage
@title The Guile Reading Heap Manual
@author Christopher R. Nelson

@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*

@insertcopying
@end titlepage

@contents

@c *********************************************************************
@node Top, Introduction, (dir), (dir)
@top Reading Heap

This document describes Reading Heap version @value{VERSION}.

@menu
* 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, Installation, Top, Top
@chapter Introduction

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

@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