This module implements the Emacsvox EPub Bookshelf — a unified interface for organizing, locating and reading EPub EBooks on the emacsvox Audio Desktop. The epub reader is built using the Emacs Web Browser (EWW), and all of emacsvox’s EWW conveniences are available when reading EBooks — see See emacsvox-eww for useful tools including bookmarking and structured navigation. For now it supports epub2 — it will support epub3 some time in the future.
The main entry point is command emacsvox-epub bound to
C-e g. This command opens a new bookshelf buffer unless the
user has previously opened a specific bookshelf. A
bookshelf is a buffer that lists books placed on a given
bookshelf — these are listed by title and
author. The bookshelf buffer is in a special mode that
provides single-key commands for adding, removing and finding
books, as well as for opening the selected book using Emacs’
built-in Web browser (eww).
The next few sections give a high-level overview of the emacsvox Bookshelf and EPub interaction, followed by detailed documentation on the various commands and user options.
In the simplest case, EBooks can be placed under a specific
directory (with sub-directories as needed).
Customize user option emacsvox-epub-library-directory
to point to this location.
Here is a quick summary of commands for
organizing, saving and opening a bookshelf:
emacsvox-epub-bookshelf-add-epub
emacsvox-epub-bookshelf-open
emacsvox-epub-bookshelf-clear
emacsvox-epub-bookshelf-remove-this-book
emacsvox-epub-bookshelf-rename
emacsvox-epub-locate-epubs
emacsvox-epub-bookshelf-add-directory
emacsvox-epub-bookshelf-remove-directory
emacsvox-epub-bookshelf-redraw
emacsvox-epub-bookshelf-open-epub
emacsvox-epub-bookshelf-save
emacsvox-epub-bookshelf-refresh
emacsvox-epub-bookshelf-save
Gutenberg integration provides one-shot commands for downloading the latest copy of the Gutenberg catalog and finding and downloading the desired epub for offline reading.
emacsvox-epub-gutenberg-catalog
emacsvox-epub-gutenberg-download
Once downloaded, these EBooks can be
organized under emacsvox-epub-library-directory
For more advanced usage, see the next section
on integrating with Calibre catalogs.
Project Calibre enables the indexing and searching of large EBook
collections. Read the Calibre documentation for organizing and
indexing your EBook library. See user options named
emacsvox-epub-calibre-* for customizing emacsvox to work
with Calibre. Once set up, Calibre integration provides the
following commands from the bookshelf buffer:
emacsvox-epub-calibre-results
emacsvox-epub-bookshelf-calibre-author
emacsvox-epub-bookshelf-calibre-search
emacsvox-epub-bookshelf-calibre-title
The most efficient means to read an EBook is to have EWW render
the entire book — this works well even for very large EBooks
given that EWW is efficient at rendering HTML. Rendering the
entire book means that all of the contents are available for
searching. To view an EBook in its entirety, use command
emacsvox-epub-eww. You can open the EPub table of contents
with command emacsvox-epub-open; for a
well-constructed epub, this TOC should provide hyperlinks to each
section listed in the table of contents.
emacsvox-epub-eww
emacsvox-epub-eww
emacsvox-epub-browse-files
emacsvox-epub-open
A Calibre Front-end. Letters do not insert themselves; instead, they are commands. Key Binding ——————————————————————————- RET emacsvox-epub-calibre-dired-at-point In addition to any hooks its parent mode ‘special-mode’ might have run, this mode runs the hook ‘emacsvox-calibre-mode-hook’, as the final or penultimate step during initialization.
Add EPubs found in specified directory to the bookshelf. Interactive prefix arg searches recursively in directory. (fn DIRECTORY &optional RECURSIVE)
Add epub file to current bookshelf. (fn EPUB-FILE)
Add results of an author search to current bookshelf. (fn PATTERN)
Add results of an title/author search to current bookshelf. (fn PATTERN)
Add results of an title search to current bookshelf. (fn PATTERN)
Clear all books from bookshelf.
Load bookshelf metadata from disk.
Load bookshelf metadata from specified bookshelf. (fn BOOKSHELF)
Open epub file and add it to current bookshelf. (fn EPUB-FILE)
Redraw Bookshelf. Optional interactive prefix arg author-first prints author at the left. (fn &optional AUTHOR-FIRST)
Refresh and redraw bookshelf.
Remove EPubs found in specified directory from the bookshelf. Interactive prefix arg searches recursively in directory. (fn DIRECTORY &optional RECURSIVE)
Remove the book on current line from this bookshelf. No book files are deleted.
Saves current bookshelf to specified name. Interactive prefix arg ‘overwrite’ will overwrite existing file. (fn NAME &optional OVERWRITE)
Save bookshelf metadata.
Browse list of HTML files in EPub. Useful if table of contents in toc.ncx is empty. (fn EPUB)
Open directory containing current result.
Show most recent Calibre search results.
Search for Epubs from Google Books. (fn QUERY)
Open Gutenberg catalog. Fetch if needed, or if refresh is T. (fn &optional REFRESH)
Open web page for specified book. Place download url for epub in kill ring. With interactive prefix arg ‘download’, download the epub. (fn BOOK-ID &optional DOWNLOAD)
Locate epub files using locate. (fn PATTERN)
An EPub Front-end. Letters do not insert themselves; instead, they are commands. Key Binding ——————————————————————————- C-a emacsvox-epub-bookshelf-add-directory C-d emacsvox-epub-bookshelf-remove-directory C-k emacsvox-epub-delete C-l emacsvox-epub-bookshelf-redraw RET emacsvox-epub-eww C-o emacsvox-epub-bookshelf-open-epub / emacsvox-epub-calibre-results A emacsvox-epub-bookshelf-calibre-author C emacsvox-epub-gutenberg-catalog G emacsvox-epub-google O emacsvox-epub-open-with-nov S emacsvox-epub-bookshelf-calibre-search T emacsvox-epub-bookshelf-calibre-title a emacsvox-epub-bookshelf-add-epub b emacsvox-epub-bookshelf-open c emacsvox-epub-bookshelf-clear d emacsvox-epub-bookshelf-remove-this-book e emacsvox-epub-eww f emacsvox-epub-browse-files g emacsvox-epub-gutenberg-download l emacsvox-epub-locate-epubs n next-line o emacsvox-epub-open p previous-line r emacsvox-epub-bookshelf-rename M-s emacsvox-epub-bookshelf-save C-x C-q emacsvox-epub-bookshelf-refresh C-x C-s emacsvox-epub-bookshelf-save In addition to any hooks its parent mode ‘special-mode’ might have run, this mode runs the hook ‘emacsvox-epub-mode-hook’, as the final or penultimate step during initialization.
Open specified Epub. Filename may need to be shell-quoted when called from Lisp. (fn EPUB-FILE)
Directory where we keep .bsf files defining various bookshelves.
Default Value:
"~/EBooks/bsf/"
Root of Calibre library.
Default Value:
"~/EBooks/calibre"
Base URL for Gutenberg mirror.
Default Value:
"http://www.gutenberg.org/ebooks/"
Suffix of book type we retrieve.
Default Value:
".epub.noimages"
Directory under which we store Epubs.
Default Value:
"~/EBooks/"