diff options
Diffstat (limited to 'doc/reading-heap.texi')
| -rw-r--r-- | doc/reading-heap.texi | 136 |
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 |