The GNU Emacs Reader

An all-in-one document reader for GNU Emacs, supporting all major document formats. This package intends to take from doc-view, nov.el, and pdf-tools and make them better. And as such, it is effectively a drop-in replacement for them

Screencast

Supported Formats

The Emacs Reader (via MuPDF) can open all the formats below.

Well-supported Formats

• PDF
• EPUB
• MOBI
• FB2
• XPS/OpenXPS
• CBZ

Office Document Formats

These formats below are not really for document reading, and as such while they are supported by MuPDF and can be opened fine, it’s just not going to be that good of an experience. It should only be used for quickly checking the textual contents of the document, and certainly cannot be edited inside Emacs. (You may use LibreOffice for that.)

Open Document Formats (LibreOffice)

• ODT
• ODS
• ODP
• ODG

Proprietary Micro$oft Formats

Using these formats is heavily discouraged, you should always prefer the above formats from LibreOffice (Which can also you help you edit these formats if you need to). But since MuPDF does come with some very minimal support for these proprietary formats as well, they can also be viewed:

• DOCX
• PPTX
• XLSX

Dependencies

The only thing this package depends on is mupdf, at minimum v1.26.0.

Installation

For now, until the package has been published to GNU ELPA, the only way to install and use it is through locally cloning the repo and building it. This is different across platforms:

GNU/Linux

On GNU/Linux all you need is: gcc and make. Then you can simply install through the Emacs’ built-in package-vc or the straight package manager. The built-in package-vc still has some quirks, but here are the recipes for both:

• use-package with package-vc:

  (setq package-vc-allow-build-commands t)
  (use-package reader
    :vc (:url "https://codeberg.org/divyaranjan/emacs-reader"
  	    :make "all"))
      

• use-package with straight

  (use-package reader
    :straight '(reader :type git :host codeberg :repo "divyaranjan/emacs-reader"
  	      :files ("*.el" "render-core.so")
  	      :pre-build ("make" "all")))
      

GNU Guix

Using the GNU Guix package manager, you can get emacs-reader through the divya-lambda Guix channel. Follow the instructions there to add the Guix channel to your configuration. Then all that remains to do is,

guix install emacs-reader

This will get the latest release of emacs-reader. However, if you want to get latest features, bug fixes (and bugs!) to help us with testing emacs-reader, you should use the master branch. You can instruct Guix to get it for you, like so,

guix install emacs-reader --with-branch=emacs-reader=master

You can also upgrade an already installed package with,

guix upgrade emacs-reader --with-branch=emacs-reader=master

You may replace the branch name as you need.

Nix

Follow the instructions here.

MacOS

Since MacOS’ package manager Homebrew already has the latest version of MuPDF (1.26.0), you don’t need the submodule at all. You just need to do:

brew install gcc
brew install make
brew install mupdf

And then use the straight or package-vc recipe from the GNU/Linux section.

Windows

With Windows, you need MSYS2 toolchain, first install MSYS2, then choose one of the environment that MSYS2 provided, on a modern 64bit Windows system, you want either MINGW64 or UCRT64. If you never try MSYS2 before, we recommend MINGW64 since this is the environment that used to build the official GNU/Emacs’ Windows version.

The following steps assume you use MINGW64:

First install the build dependencies:

pacman -S make mingw-w64-x86_64-gcc git pkg-config

Then you need install libmupdf, unfortunately right now MSYS2’s repo only has MuPDF 1.24.3, so you need this PR, there are 2 ways to use this PR:

1. Download the pre-compiled package from the PR’s CI, then use pacman -U to install the package file.
2. Clone the PR, goto the folder mingw-w64-mupdf then run command makepkg -s to compile MuPDF, and then use pacman -U to install the package file.

After that, you can run git clone https://codeberg.org/divyaranjan/emacs-reader.git and then:

make all

Manual

This section is about how to install this package manually. Intended to be used by developers.

After cloning the repository, follow the instructions from the previous section to install dependencies on your respective operating system.

Then, you run make in the git repository, as noted earlier this may take a few depending on if it is fetching and building mupdf.

After this, you add the path to emacs-reader git repository to load-path,

(add-to-list 'load-path "/path/to/emacs-reader")

You can also utilize use-package to do the same,

(use-package reader
  :vc t
  :load-path "/path/to/emacs-reader")

To test emacs-reader in a default Emacs config, use something like:

emacs -q -L . -l reader.el

This command adds the current directory to path, and loads reader.el.

This will not work for testing auto loading though. You can try using package-vc-install-from-checkout to test that. This video demonstrates how to do that.

Key Bindings

• n for going to next page
• p for going to previous page
• C-n for scrolling down.
• C-p for scrolling up.
• C-b for scrolling left.
• C-f for scrolling right.
• Q for closing the Emacs Reader buffer.
• M-< for going to the first page.
• M-> for going to the last page.
• M-g g for going to a particular page.
• M-v or Page Up for scrolling to the top of the page.
• C-v or Page Down for scrolling to the end of the page.
• SPC, S-SPC , and DEL make the above two commands keep scrolling the pages.
• ===, +, and C-<wheel-up> for zooming into the page.
• - and C-<wheel-down> for zooming out of the page.
• H to make the page fit the height of the current window.
• W to make the page fit the width of the current window.

How It Works

This package is entirely distinct from DocView and pdf-tools in both its architecture and implementation. It leverages Emacs’ dynamic/native modules which allows it to interoperate with other programming languages outside of its Emacs Lisp environment.

Thus, we rely on the efficient MuPDF library as a shared object with which our dynamic modules work. All the tasks that require manual memory management, efficiently dealing with the rendered pages, and so on are delegated to the C backend, and Emacs takes care of exclusively what it’s good at: displaying produced pages, buffer management, and all round integration with the rest of Emacs.

For understanding how dynamic modules work within Emacs, please consult the following article I wrote:

https://www.phimulambda.org/blog/emacs-dynamic-module.html

Live Streams

I have been streaming the development of this package on my PeerTube channel: (phi (mu (lambda)))

Here are the recordings of the streams:

• Part I: Introduction
• Part II: Making Overlays Centered and Zoomable
• Part III: Multi-Threading

The streams happen on Sundays, biweekly at around 5:30 PM UTC. Follow the channel on Peertube or my Mastodon to be notified when I stream. You can also find some stream notes here.

If you wish to join the discussion for the package, you should join the IRC channel #phi-mu-lambda on Libera.

License

Unless another license is listed, all files in emacs-reader are licensed under the GNU General Public License version 3 (or at your option), any later version. See LICENSE and CONTRIBUTORS for further details.

The logo of the project was made by Divya Ranjan Pattanaik and is shared under CC-BY-SA-4.0. The logo uses the following artworks from GNU:

• A Bold GNU Head by Aurélio A. Heckert
• Icon for Emacs 23 by Kentaro Ohkouchi

The interesting history of different Emacs logos is outlined by Luis Fernandes, in his article on The Design of the Emacs Logo.