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
The Emacs Reader (via MuPDF) renders all the formats below by way of SVGs (Scalable Vector Graphics):
- EPUB
- MOBI
- FB2
- XPS/OpenXPS
- CBZ
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.)
- ODT
- ODS
- ODP
- ODG
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
Technically the only thing this package depends on is mupdf, but for various reasons, the way it is packaged in most distributions (at least GNU Guix and Arch) is that it has a conflict with on of its own dependencies, effectively making the package unusable. So for now, mupdf is provided as a submodule in the repository. We have spoken to the mupdf developers, and they have fixed it upstream, we will wait for GNU/Linux distributions to follow before removing the submodule (More details at #18).
So, since you’d be building mupdf from source to produce the shared object libmupdf.so which the package relies on, you’d need to have the depencies that mupdf has, check them from here and make sure you have them installed. But most of them are actually bundled with mupdf itself.
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:
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-packagewithpackage-vc:(setq package-vc-allow-build-commands t) (use-package reader :vc (:url "https://codeberg.org/divyaranjan/emacs-reader" :make "all"))
use-packagewithstraight(use-package reader :straight '(reader :type git :host codeberg :repo "divyaranjan/emacs-reader" :files ("*.el" "render-core.so") :pre-build ("make" "all")))
NOTE: Both of these commands will take a long time, because they’re going to invoke the make command which will recursively fetch the submodule and it’s dependencies. It’ll hang your Emacs for a good ~15-20m, so be careful.
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 mupdfAnd then use the straight or package-vc recipe from the GNU/Linux section.
With Windows, things are slightly tricky. The only toolchain where I got it to work is with MSYS2. So, you need to install that and then use MSYS2 to install the following:
pacman -S make mingw-w64-x86_64-gcc git pkg-configAfter that, you can run git clone --recurse-submodules https://codeberg.org/divyaranjan/emacs-reader.git and then:
make allThis 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.elThis 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.
nfor going to next pagepfor going to previous pageC-nfor scrolling down.C-pfor scrolling up.C-bfor scrolling left.C-ffor scrolling right.Qfor closing the Emacs Reader buffer.M-<for going to the first page.M->for going to the last page.M-g gfor going to a particular page.M-vorPage Upfor scrolling to the top of the page.C-vorPage Downfor scrolling to the end of the page.SPC,S-SPC, andDELmake the above two commands keep scrolling the pages.- ===,
+, andC-<wheel-up>for zooming into the page. -andC-<wheel-down>for zooming out of the page.Hto make the page fit the height of the current window.Wto make the page fit the width of the current window.
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 rendering SVGs, and so on are delegated to the C backend, and Emacs takes care of exclusively what it’s good at: displaying produced SVGs and buffer management.
For understanding how dynamic modules work within Emacs, please consult the following article I wrote:
https://www.phimulambda.org/blog/emacs-dynamic-module.html
I have been streaming the development of this package on my PeerTube channel: (phi (mu (lambda)))
Here are the recordings of the streams:
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.
Licensed under GPLv3. Check LICENSE and CONTRIBUTORS for details.
The logo of the project was made by the author and is shared under CC-BY-SA-4.0. The logo uses the following artworks from GNU:
The interesting history of different Emacs logos is outlined by Luis Fernandes, in his article on The Design of the Emacs Logo.