1
0
Fork
You've already forked emacs-reader
0
An all-in-one document reader for all formats in Emacs, backed by MuPDF.
  • C 41.9%
  • C++ 28.2%
  • Emacs Lisp 24.5%
  • Scheme 3%
  • Makefile 2.2%
  • Other 0.2%
Find a file
2025年06月29日 14:25:28 +00:00
doc Add notes of stream 2025年05月18日 20:05:09 +00:00
extras Add logo 2025年05月16日 03:41:57 +00:00
render chore: update headers 2025年06月29日 14:22:33 +00:00
test/vm doc: add info about GNU Guix vm for testing 2025年06月27日 22:21:20 +05:30
.clang-format Add .clang-format 2025年06月14日 11:54:14 +00:00
.dir-locals.el chore: enable eglot by default, and format C code on save. 2025年06月28日 12:23:53 +05:30
.envrc dev: doc: recommend GNU Guix with direnv. 2025年06月27日 23:15:27 +05:30
.gitignore Update gitignore 2025年05月15日 11:52:57 +00:00
CONTRIBUTORS chore: update CONTRIBUTORS with account of test vms 2025年06月29日 19:15:00 +05:30
default.nix chore: add gdb to default.nix 2025年06月28日 19:52:07 +00:00
LICENSE Initial commit 2025年01月15日 13:41:05 +00:00
Makefile fix: skip pkg-config checks for macos too 2025年06月28日 19:50:23 +00:00
manifest.scm chore: add gdb to manifest.scm 2025年06月28日 23:50:50 +05:30
reader-bookmark.el add: reader-current-pagenumber 2025年05月20日 11:30:46 +05:30
reader-outline.el fix: docs strings in reader-outline 2025年06月29日 16:50:50 +05:30
reader-saveplace.el Indentation 2025年05月30日 14:00:05 +00:00
reader.el chore: update version 2025年06月29日 14:25:28 +00:00
README.org chore: remove references of mupdf sub module from readme 2025年06月29日 18:15:18 +05:30

The GNU Emacs Reader

/prom/emacs-reader/media/branch/master/extras/emacs-reader-logo.png

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

/prom/emacs-reader/media/branch/master/extras/emacs-reader-2025年05月14日_04.32.41.gif

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")))

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, 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-config

After that, you can run git clone --recurse-submodules 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:

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:

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