sloum
/
libman
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updates readme

This commit is contained in:
sloum 2024-03-26 20:16:09 -07:00
parent 772d96cdee
commit 91fb6fa02a
1 changed files with 99 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
README.md
View File

@ -17,22 +17,33 @@ You can always use `go build` instead of `go install`. If you do so, change the
## Usage
There are currently three known json files supporting our format (two scraped, one hand built):
There are currently four known json files supporting our format (three scraped, one hand built):
- https://rawtext.club/~sloum/lib/standard-ebooks.json
- https://rawtext.club/~sloum/lib/global-grey.json
- https://rawtext.club/~sloum/lib/project-gutenberg.json
- https://hearthstories.org/hearth-stories.json
The PG file is quite large, both in file size and in number of books, and does slow down querying a bit.
### To add a source
Let's add two. That way we get some variety. As things are currently built, each add needs to be a separate action (the program does not support multiple `-add` options in one command).
```sh
libman -add https://rawtext.club/~sloum/lib/standard-ebooks.json
libman -add https://rawtext.club/~sloum/lib/global-grey.json
```
### To list your current sources
```sh
libman -sources
#
# Output:
#
# Global Grey: https://rawtext.club/~sloum/lib/global-grey.json
# Standard Ebooks: https://rawtext.club/~sloum/lib/standard-ebooks.json
```
### To search
@ -41,14 +52,25 @@ A basic search by author...
```sh
libman -author "fenimore cooper"
#
# Output:
#
# The Deerslayer by James Fenimore Cooper Global Grey pdf, epub, mobi, azw3, html
# The Last of the Mohicans by James Fenimore Cooper Global Grey pdf, epub, mobi
# The Last of the Mohicans by James Fenimore Cooper Standard Ebooks epub, azw3, kepub
# The Pathfinder by James Fenimore Cooper Global Grey pdf, epub, mobi, azw3, html
```
...you can use any part of the authors name (the whole thing is not usually required, and it is not case sensitive).
We can hone in on a specific source...
We can hone in on a specific source. You will notice in the example below that we only use part of the source name. Use as much of a name as is needed to get the specificity you want.
```sh
libman -author "fenimore cooper" -source "global grey"
libman -author "fenimore cooper" -source "standard"
#
# Output:
#
# The Last of the Mohicans by James Fenimore Cooper Standard Ebooks epub, azw3, kepub
```
...that still leaves us with three results. They are all part of a series, so we can skip doing a `-title` filter if we want the whole series.
@ -56,7 +78,21 @@ libman -author "fenimore cooper" -source "global grey"
If we want to get more detailed information we can add a `-l` flag for long resuls:
```sh
libman -author "fenimore cooper" -source "global grey" -l
libman -author "fenimore cooper" -source "standard" -l
#
# Output:
#
# The Last of the Mohicans by James Fenimore Cooper
# Source: Standard Ebooks
# Subjects: adventure, fiction
# Files:
# epub - https://standardebooks.com/ebooks/james-fenimore-cooper/the-last-of-the-mohicans/downloads/james-fenimore-cooper_the-last-of-the-mohicans.epub
# azw3 - https://standardebooks.com/ebooks/james-fenimore-cooper/the-last-of-the-mohicans/downloads/james-fenimore-cooper_the-last-of-the-mohicans.azw3
# kepub - https://standardebooks.com/ebooks/james-fenimore-cooper/the-last-of-the-mohicans/downloads/james-fenimore-cooper_the-last-of-the-mohicans.kepub.epub
# Description:
# The Last of the Mohicans is one of the most famous tales of pioneer American adventure. Set during the French and Indian War, Mohicans tells the tale of the journey of two daughters to meet their father, a colonel, at Fort William Henry. The road is long and dangerous, and they, along with their American and Native guides, encounter adventure at each step.
#
# Mohicans is actually the second book in a pentalogy, the Leatherstocking Tales pentalogy. While the pentalogy saw success in its time, today Mohicans is by far the best-known of the books.
```
### To download/install
@ -65,6 +101,12 @@ Okay. Let's download these. Wait, what format do we want? The output (either lon
```sh
libman -author "fenimore cooper" -source "global grey" -format "epub" -install
#
# Output:
#
# GET https://www.globalgreyebooks.com/ebooks/james-fenimore-cooper_deerslayer.epub
# GET https://www.globalgreyebooks.com/ebooks1/james-fenimore-cooper/last-of-the-mohicans/last-of-the-mohicans.epub
# GET https://www.globalgreyebooks.com/ebooks/james-fenimore-cooper_pathfinder.epub
```
Great! Those got added to our book download folder, which defaults to `~/.local/share/libman`, so we can read them with whatever reader we prefer. An important note is that when you use the `-install` option it will download _all the books_ that you are currently filtered to. If you are not careful this could end up being a huge quantity of books. So narrow things down to the correct specificity before downloading.
@ -75,9 +117,15 @@ It is easy to update your book cache. Every now and again run the following:
```sh
libman -sync
#
# Output:
#
# Syncing Sources
# Retrieving: Global Grey...
# Retrieving: Standard Ebooks...
```
That will go through each source you have added and check to see if there is a newer version of the source's json file, if so: it downloads it and replaces the old one.
That will go through each source you have added and check to see if there is a newer version of the source's json file. To do so, it downloads the json, parses it, and compares the update date. If the version that was just downloaded is newer it replaces the older version in your local cache. Since syncing does require a full download and parse cycle, it can take a bit for some sources. Unless you are wanting a specific book you know a source added most users can probably sync once every few weeks or even months and have plenty of great books to read.
### To update settings
@ -87,11 +135,54 @@ To update configuration/settings we can do as follow:
libman -configure
```
...which will open the configuration file in your `$EDITOR`.
...which will open the configuration file in your `$EDITOR`. The main use case for this would be to change your install location. Most other settings can be left alone, unless you really want to tinker in the file rather than use the program itself (such as for adding and removing sources).
There are other filters (for example by `-subject`... for which you can also use `-subjects` to see the available subjects). To see the full list run: `libman -h`.
If you prefer to just open the file in your editor directly you can do something like:
```sh
vim ~/.config/libman/settings.json
```
### Other filters/options
There are other filters (for example by `-subject`... for which you can also use `-subjects` to see the available subjects).
```sh
libman -h
#
# Output:
#
# Usage of ./libman:
# -a Sort by author instead of title
# -add string
# Add a URL or filepath as a source location
# -author string
# Filter by author
# -configure
# Open the configuration file in your $EDITOR
# -format string
# Filter by format; ex. "epub"
# -install
# Installs the results of the query
# -l Show full details for each searched book
# -remove string
# Remove a source by name
# -source string
# Filter results by the given source
# -sources
# List sources
# -subject string
# Filter by subject
# -subjects
# List all subjects in cache
# -sync
# Sync sources
# -title string
# Filter by title
```
## Why
I like command line tools. I like books. I doubt many folks will start offering up their libraries in this format, but it is a decent idea for book distribution (even if I didnt handle it as elegantly as some folks might like). Mostly this caters to the public domain books crowd, but there are lots of CC licensed works as well that cold be distributed this way as well. Any individual person can distribute their library as a json file that contains download links and any number of frontends could use this file type. If nothing else, it lets me search a few places that I would otherwise have to go to a few different web pages to search, so that is nice.
I like command line tools. I like books. I doubt many folks will start offering up their libraries in this format, but it is a decent idea for book distribution (even if I didnt handle it as elegantly as some folks might like). Mostly this caters to the public domain books crowd, but there are lots of CC licensed works that cold be distributed this way as well. Any individual person can distribute their library as a json file that contains download links and any number of frontends could use this file type. If nothing else, it lets me search a few places that I would otherwise have to go to a few different web pages to search, so that is nice.