S.H.E.L.F.

The System (for) Hasty Evaluation (of) Literature (in the) Future version 2 (referred to as S.H.E.L.F. hereinafter) is a distributed program to help manage and index a shared set of books.

It allows for a group of trusted individuals to maintain a shared book database (a S.H.E.L.F.) that can be effectively searched, with no active maintenance necessary, and provides easy ingest by ISBN via the Google Books API.

Just watch:

Installation

Windows

1. Download the latest Windows binary.
2. Unzip it (you can now just run the executable).
3. (Optional) To create a start menu shortcut, make a shortcut to the executable in C:\Users\<your username>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs.

To uninstall simply delete the binary/shortcut (if you made one).

Linux

1. Download the latest Linux binary.
2. Extract the downloaded file with tar xf shelf-linux-amd64.tar.xz.
3. Run sudo make install.

To uninstall simply run sudo make uninstall.

Other (Build From Source)

1. Install Go version 1.18 or newer.
2. Install the Fyne prerequisites.
3. Download the latest release's source code.
4. Unzip it.
5. Run go build . from the root of the source code (same directory as the README.md file).

Usage

When you first start shelf, a prompt will open asking if you want to start a S.H.E.L.F., or connect to one. If you're reading this section for the first time, you probably want to start one.

In the less likely scenario that you want to connect to one, you can look at the "Adding/Editing/Deleting Users" section, or look at the step-by-step instructions which can be found in the Quick Help tab of the Information Section.

Adding/Editing/Deleting Books

To add a book, press Add Book in the lower left corner, and fill out the fields. The only requirement is that the title field is not blank.

When editing a book, you can simply enter the ISBN into the ISBN field and press Autofill. This looks up the book, if it is found the relevant fields will be overwritten, otherwise an error will pop up.

To edit a book, from the book's page press the edit button (lower right). Same restrictions as adding a book apply.

To delete a book press delete book on the book's page (lower right, left of edit).

Adding/Editing/Deleting Users

All operations to users happens in the users page located in Settings under the Users tab. From here users can have their permissions set and changed.

The public key can either be in word format or hexadecimal format.

Note that only admin users can change other users, regular users can only add/edit books.

Search

Along with basic, all-field search, the search feature in S.H.E.L.F. has a number of prefixes, allowing search to be narrowed down further. These prefixes apply to the following word, and restrict that word to only being considered found if it is in the field specified by the prefixes.

The full list of prefixes are:

Prefix	Example
title:	title:Frankenstein finds all books with the title Frankenstein.
author:	author:Shelley finds all books with the author Shelley.
publisher:	publisher:Bantam finds all books published by Bantam.
year:	year:1984 finds all published in 1984.
isbn:	isbn:9780553212471 finds all books with the ISBN 9780553212471.
scannable:	scannable:0553212478 finds all books with the scannable field set to 0553212478.
location:	location:A0 finds all books at A0 (whatever that means, maybe A0 is a physical shelf).

Design

This section could also be titled "What happened to S.H.E.L.F. version 1?"

S.H.E.L.F. version 1 was built as a classic Ruby on Rails web application, using the Bootstrap CSS framework. It was able to ingest books manually, or via ISBN lookup by the Google Books API. It included search prefixes that allowed to narrow books, and the latest version of its source code can be found here.

While S.H.E.L.F. version 1 was useful in its time, and worked great as an end user, it presented two major challenges for the maintainer. (1) Its lack of authentication meant that anyone on the network could wreak havoc. (2) It being a web application meant that there was a server that needed active maintenance, and any problem on the network would take the whole service down.

The design of S.H.E.L.F. version 2 seeks to directly resolve the issues of S.H.E.L.F. version 1, while maintaining all its features, and along with a third objective being that complete version history should be retained.

The first issue, that of authentication, is solved by having each device represented by a public key, for which an access control system rooted in a shared, trusted, root key is established. This shared root key, is itself the identification of a shared S.H.E.L.F., and is only used to give another public key administrator permissions. Only administrators can add/change the permissions of other users, everyone else can only edit books.

The second issue, that of maintainability, is solved by moving from a web application to a standalone desktop application that is networked. S.H.E.L.F. version 2 is networked by libp2p, which provides peer discovery (currently only across a local network via mDNS), encrypted channels, and an easy ability to version the network protocol. This, in combination of the data transmitted (see next paragraph), and a canonical ordering for the data, means that the network has eventual consistency, exactly what is needed for me to be able to set this up on the computers of others and forget about it.

The third goal, that of version history, is solved by the data format itself. S.H.E.L.F. version 2 does not directly care about the current state of the book index, rather it deals itself with a set of changes to the shared index. It is this set of changes that is synced, and is used ("replayed") to derive the current state of the book index.

Copyright

The contents of the fonts directory is licensed under the SIL Open Font License version 1.1. See fonts/LICENSE for full details.

Otherwise, the rest of S.H.E.L.F. is licensed under the 2 Clause BSD License. See LICENSE for full details.

Note that this includes images/icon.svg and images/icon.png which are modified from the original public domain image.