12.67 emacspeak-epub

12.67.1 Introduction

This module implements the Emacspeak EPub Bookshelf — a unified interface for organizing, locating and reading EPub EBooks on the emacspeak Audio Desktop. The epub reader is built using the Emacs Web Browser (EWW), and all of emacspeak’s EWW conveniences are available when reading EBooks — see See emacspeak-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 emacspeak-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 emacspeak Bookshelf and EPub interaction, followed by detailed documentation on the various commands and user options.

12.67.2 Organizing EBooks On The Emacspeak Desktop

In the simplest case, EBooks can be placed under a specific directory (with sub-directories as needed). Customize user option emacspeak-epub-library-directory to point to this location. Here is a quick summary of commands for organizing, saving and opening a bookshelf:























C-x C-q


C-x C-s


12.67.3 Integrating With Project Gutenberg

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.





Once downloaded, these EBooks can be organized under emacspeak-epub-library-directory For more advanced usage, see the next section on integrating with Calibre catalogs.

12.67.4 Calibre Integration

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 emacspeak-epub-calibre-* for customizing emacspeak to work with Calibre. Once set up, Calibre integration provides the following commands from the bookshelf buffer:









12.67.5 Reading EBooks From The Bookshelf

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 emacspeak-epub-eww. You can open the EPub table of contents with command emacspeak-epub-open; for a well-constructed epub, this TOC should provide hyperlinks to each section listed in the table of contents.









Code: Required Modules:

12.67.6 Emacspeak-Epub Commands emacspeak-calibre-mode

Command: emacspeak-calibre-mode
A Calibre Front-end.
Letters do not insert themselves; instead, they are commands.

Key             Binding
RET             emacspeak-epub-calibre-dired-at-point

In addition to any hooks its parent mode ‘special-mode’ might have
run, this mode runs the hook ‘emacspeak-calibre-mode-hook’, as the
final or penultimate step during initialization. emacspeak-epub

Command: emacspeak-epub
C-e M-e
EPub  Interaction.
When opened, displays a bookshelf consisting of  epubs found at the
root directory,see M-x emacspeak-epub-mode emacspeak-epub-bookshelf-add-directory

Command: emacspeak-epub-bookshelf-add-directory (directory &optional recursive)
Add EPubs found in specified directory to the bookshelf.
Interactive prefix arg searches recursively in directory.

(fn DIRECTORY &optional RECURSIVE) emacspeak-epub-bookshelf-add-epub

Command: emacspeak-epub-bookshelf-add-epub (epub-file)
Add epub file to current bookshelf.

(fn EPUB-FILE) emacspeak-epub-bookshelf-calibre-author

Command: emacspeak-epub-bookshelf-calibre-author (pattern)
Add results of an author search to current bookshelf.

(fn PATTERN) emacspeak-epub-bookshelf-calibre-search

Command: emacspeak-epub-bookshelf-calibre-search (pattern)
Add results of an title/author search to current bookshelf.

(fn PATTERN) emacspeak-epub-bookshelf-calibre-title

Command: emacspeak-epub-bookshelf-calibre-title (pattern)
Add results of an title search to current bookshelf.

(fn PATTERN) emacspeak-epub-bookshelf-clear

Command: emacspeak-epub-bookshelf-clear
Clear all books from bookshelf. emacspeak-epub-bookshelf-load

Command: emacspeak-epub-bookshelf-load
Load bookshelf metadata from disk. emacspeak-epub-bookshelf-open

Command: emacspeak-epub-bookshelf-open (bookshelf)
Load bookshelf metadata from specified bookshelf.

(fn BOOKSHELF) emacspeak-epub-bookshelf-open-epub

Command: emacspeak-epub-bookshelf-open-epub (epub-file)
Open epub file and add it to current bookshelf.

(fn EPUB-FILE) emacspeak-epub-bookshelf-redraw

Command: emacspeak-epub-bookshelf-redraw (&optional author-first)
Redraw Bookshelf.
Optional interactive prefix arg author-first prints author at the

(fn &optional AUTHOR-FIRST) emacspeak-epub-bookshelf-refresh

Command: emacspeak-epub-bookshelf-refresh
Refresh and redraw bookshelf. emacspeak-epub-bookshelf-remove-directory

Command: emacspeak-epub-bookshelf-remove-directory (directory &optional recursive)
Remove EPubs found in specified directory from the bookshelf.
Interactive prefix arg searches recursively in directory.

(fn DIRECTORY &optional RECURSIVE) emacspeak-epub-bookshelf-remove-this-book

Command: emacspeak-epub-bookshelf-remove-this-book
Remove the book on current line from this bookshelf.
No book files are deleted. emacspeak-epub-bookshelf-rename

Command: emacspeak-epub-bookshelf-rename (name &optional overwrite)
Saves current bookshelf to  specified name.
Interactive prefix arg ‘overwrite’ will overwrite existing file.

(fn NAME &optional OVERWRITE) emacspeak-epub-bookshelf-save

Command: emacspeak-epub-bookshelf-save
Save bookshelf metadata. emacspeak-epub-browse-files

Command: emacspeak-epub-browse-files (epub)
Browse list of HTML files in  EPub.
Useful if table of contents in toc.ncx is empty.

(fn EPUB) emacspeak-epub-calibre-dired-at-point

Command: emacspeak-epub-calibre-dired-at-point
Open directory containing current result. emacspeak-epub-calibre-results

Command: emacspeak-epub-calibre-results
Show most recent Calibre search results. emacspeak-epub-delete

Command: emacspeak-epub-delete
Delete EPub under point. emacspeak-epub-eww

Command: emacspeak-epub-eww (epub-file &optional use-ncx)
C-e y E
Display entire book  using EWW from EPub.
Use content listed in toc.ncx  if prefix-arg use-ncx is true.
Default is to  use   the sorted list of html files
in the epub file.

(fn EPUB-FILE &optional USE-NCX) emacspeak-epub-google

Command: emacspeak-epub-google (query)
Search for Epubs from Google Books.

(fn QUERY) emacspeak-epub-gutenberg-catalog

Command: emacspeak-epub-gutenberg-catalog (&optional refresh)
Open Gutenberg catalog.
Fetch if needed, or if refresh is T.

(fn &optional REFRESH) emacspeak-epub-gutenberg-download

Command: emacspeak-epub-gutenberg-download (book-id &optional download)
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) emacspeak-epub-locate-epubs

Command: emacspeak-epub-locate-epubs (pattern)
Locate epub files using locate.

(fn PATTERN) emacspeak-epub-mode

Command: emacspeak-epub-mode
An EPub Front-end.
Letters do not insert themselves; instead, they are commands.

Key             Binding
C-a             emacspeak-epub-bookshelf-add-directory
C-d             emacspeak-epub-bookshelf-remove-directory
C-k             emacspeak-epub-delete
C-l             emacspeak-epub-bookshelf-redraw
RET             emacspeak-epub-eww
C-o             emacspeak-epub-bookshelf-open-epub
/               emacspeak-epub-calibre-results
A               emacspeak-epub-bookshelf-calibre-author
C               emacspeak-epub-gutenberg-catalog
G               emacspeak-epub-google
O               emacspeak-epub-open-with-nov
S               emacspeak-epub-bookshelf-calibre-search
T               emacspeak-epub-bookshelf-calibre-title
a               emacspeak-epub-bookshelf-add-epub
b               emacspeak-epub-bookshelf-open
c               emacspeak-epub-bookshelf-clear
d               emacspeak-epub-bookshelf-remove-this-book
e               emacspeak-epub-eww
f               emacspeak-epub-browse-files
g               emacspeak-epub-gutenberg-download
l               emacspeak-epub-locate-epubs
n               next-line
o               emacspeak-epub-open
p               previous-line
r               emacspeak-epub-bookshelf-rename

M-s             emacspeak-epub-bookshelf-save

C-x C-q         emacspeak-epub-bookshelf-refresh
C-x C-s         emacspeak-epub-bookshelf-save

In addition to any hooks its parent mode ‘special-mode’ might have
run, this mode runs the hook ‘emacspeak-epub-mode-hook’, as the final
or penultimate step during initialization. emacspeak-epub-next

Command: emacspeak-epub-next
Move to next book. emacspeak-epub-open

Command: emacspeak-epub-open (epub-file)
Open specified Epub.
Filename may need to  be shell-quoted when called from Lisp.

(fn EPUB-FILE) emacspeak-epub-open-with-nov

Command: emacspeak-epub-open-with-nov
Open ebook at point in nov-mode. emacspeak-epub-previous

Command: emacspeak-epub-previous
Move to previous book. emacspeak-epub-url-executor

Command: emacspeak-epub-url-executor (url)
Custom URL executor for use in EPub Mode.

(fn URL)

12.67.7 emacspeak-epub Options

Variable: User Option emacspeak-epub-bookshelf-directory
Directory where we keep .bsf files defining various bookshelves.

Default Value:


Variable: User Option emacspeak-epub-calibre-root-dir
Root of Calibre library.

Default Value:


Variable: User Option emacspeak-epub-gutenberg-mirror
Base URL  for Gutenberg mirror.

Default Value:


Variable: User Option emacspeak-epub-gutenberg-suffix
Suffix of book type we retrieve.

Default Value:


Variable: User Option emacspeak-epub-library-directory
Directory under which we store Epubs.

Default Value: