1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
[[!meta title="An introduction to the Emacs Reader"]]
[[!meta copyright="Copyright © 2025 Divyá"]]
[[!inline pages="internal(2025/info/reader-nav)" raw="yes"]]
<!-- Initially generated with emacsconf-publish-talk-page and then left alone for manual editing -->
<!-- You can manually edit this file to update the abstract, add links, etc. --->
# An introduction to the Emacs Reader
Divyá - IRC: divya, Website: <https://www.phimulambda.org> Mastodon: <https://mathstodon.xyz/@divyaranjan>, <mailto:divya@subvertising.org>
[[!inline pages="internal(2025/info/reader-before)" raw="yes"]]
<https://codeberg.org/divyaranjan/emacs-reader>
This talk will introduce a new document reader that I have been building for Emacs since the last few months. I will showcase the basic features of the document reader, how well it integrates with Emacs and the performance and other improvements that it provides in comparision to the existing document viewing options such as DocView, PDF Tools and others.
I will also describe the core architectural decisions that were made, specficially the fact that it is a dynamic module and the pains and pleasures of interfacing Emacs with C and vice-versa.
I will give a high-level tour of the codebase, which is pretty small as of now (<3K LOC), so that if a fellow Emacs developer wishes to contribute, they know where and how to get started.
In conclusion, I'll summarize the current features we're in the process of developing, what challenges we're facing in diong so, and what we wish to work on for the upcoming versions of the package.
About the speaker:
I’m Divyá from India. My background has been as a mathematics teacher and now I'm a programmer. I’ve been hacking on free software as a hobby and, for the past three to four years, living inside Emacs. I loved reading PDFs in Emacs via pdf-tools, but poor hardware and maintenance gaps pushed me to build a faster reader. I learned MuPDF and Emacs Dynamic Modules and wrote The Emacs Reader: a dynamic-module-based, high-performance, resource-friendly document viewer for Emacs that supports PDFs and other formats (EPUB, CBZ) while integrating natively with Emacs.
## Discussion / notes
- Q: Is there scope for integrating the C library into Emacs itself
with muPDF becoming an optional dependency?
- A: That will entail having a pdf engine integrated into Emacs
source-tree, not sure if that\'s a good idea.
- Q: The dynamic modules sound great, and it\'s amazing they\'re there
since 2017. Why is it so slow to take off, do you think? Is there
prior art with them?
- A: Mostly because Elisp is so nice to use for almost everything
you need to do in Emacs. It\'s only in very specific cases that
you require to care about real-time latency and memory
efficiency. And packages like libvterm and others do use it for
such purposes.
- Q: How is pdf-tools difficult to install? I install it using the
built in package manager. Looking at the emacs-reader installation
instructions, I don\'t see how install it that easily. I don\'t use
use-package or straight. Question answered in presentation.
- A: Just the list of dependencies required to build epdfinfo itself
makes it difficult, and when you install pdf-tools it does a huge
autotools build as well. Emacs Reader only (and will always) depends
on MuPDF (and Emacs too.).
- Q: What tool(s) did you use to measure the memory usage between the
three packages?
- A: Valgrind\'s massif + massif-visualizer
- I've been using perf and then visualizing with hotspot when debugging FFI in Common Lisp... it's felt successful
- (I've never had success with valgrind, but I've not dug deep with it)
- I discovered perf only recently when I had a deep need for low-level optimisation (which is not something I often need) - it's a really nice workflow!
- Q: How is the conversion between ELisp and the foreign language type
system done? For example when interfacing with a C++ library that
makes heavy use of C++ object system and templates?
- A: Basically, dynamic modules make you write Emacs Lisp in your
language. Consult the blogpost above for a more elaborate and
complete explanation.
- Q: pdf-tools renders high quality images. Does emacs-reader do that?
- A: Yes! We can render high-quality images just fine!
- Q: Can one look at pdf metadata with emacs-reader? Can annotations
be added? Does it understand forms? Can it handle encrypted pdfs?
- A: Support for all of this is planned.
- Q: I installed emacs-reader already. It is as promised :) Great job!
How can I associate odt files to open with emacs-reader?
- A: It should just work with the **find-file** command**.**
- Q: If a pdf file is open in emacs-reader and I regenerate the pdf
with some changes, does emacs-reader actually refresh the pdf on its
own or do I have to reload the pdf?
- A: Yes if it\'s a complete file with the same filename, but no
if it\'s still being created with LaTeX - we need SyncTeX for
that
- Q: What are the challenges with integrating with SyncTeX and AucTeX?
This would be great to see as pdf-tools handles this well.
- A: Planned, no major obstacles anticipated. The only reason we
haven\'t done it yet is more important highlighting and text
selection features planned.
- Q: Loved that presentation! Will you be giving another talk on the
architecture you went over? A deep-dive there would be awesome.
- A: Not at EmacsConf, but check out my streaming sessions at
[https://tv.dyne.org/c/phimulambda](https://tv.dyne.org/c/phimulambda)
and I can talk about it there.
- Q: Is there search functionality? Something like isearch and occur?
- A: Not as such yet. But it is HIGH PRIORITY.
- Q: Does dynamic module prevent customization that Elisp usually
provide? (Advices, Hooks, etc).
- A: No, you can do everything on the Elisp side that you want. On
the dynamic side, it\'s a bit more tricky, not much support
there right now.
- Q: Follow-up on dynamic module: Do you usually create an Elisp shim
from the FFI and then use them with Elisp code?
- A: Yes, we usually wrap dynamic module functions in Elisp to
make sure the foreign function gets called when it\'s needed.
- Q: Is searching on the roadmap? Or is it already available as a
feature? Thanks!
- A: YES! HIGH PRIORITY \<3
- Q: Will there be occur like searching?
- A: YES! Basically everything in PDF Tools is planned!
- Q: What is your timing expectation for it to appear on ELPA?
- A: By next major release, which will be in 1-2 months.
- Q: is this essentially FFI?
- A: Yup
- Q: interesting.. is that how webkit integration works?
- (audience): not really.
- Q: thank you. Are there other packages that use dynamic modules?
- (audience): Yes, vterm also uses a C module
- Q: Has any work been done to make org-noter work with emacs reader?
- (audience): not yet. It is in the plans, though.
- (audience): Nice. That would allow me to switch, because I use org-noter quite a bit.
- Q: Are any of you doing simple editing of PDFs in Emacs? I'm thinking about form-filling, adding signatures, that sort of thing
- A: that's something I'd also like to integrate once we have other basic features ready
- (audience): not yet. We do want to add annotation support though. Not sure if that's the same thing.
- I don't believe it is, but I could be mistaken
- A: slightly, but not exactly, mupdf does support forms and signatures so we shouldn't have much issues except making it work with emacs.
- I'm not fond of annotations, because it mutates the original PDF.
- Q: From the example when calling page 56, is there another thread immediately fetching the next 5 pages for cache?
- A: yeah indeed I'll talk about it later in the slides, you'll have to build mupdf from scratch in that case.
- A: there are multiple threads competing to fill the cache window, depending upon how long it takes to render each slice.
- Q: here is a question that I am a bit embarassed to ask... is there an easy way to install emacs-reader with package-vc without use-package?
- yes!
- I am asking just because I've been postponing learning use-package for ages
- you can use just package-vc totally. use-package uses package-vc under the hood anyway
- I tried this - (package-vc-install "https://codeberg.org/divyaranjan/emacs-reader")
- you need to do a build step. you can just go and do it manually
- Q: how does the dark mode compare to midnight mode in pdf-tools?
- it is simply inverting the colors
- Q: so it does not support setting the foreground and background colours?
- It does not.
- pdf-tools has pdf-view-themed-minor-mode that tries to match a PDF with the current theme. It's kinda nice. I'm glad Emacs Reader is aiming to have something similar in the near future.
- dark mode intergration with the dark themes would be cool
- Q: that is a question that I've had for ages - how do we handle that PDFs that (La)TeX generates one page at a time, and that will be broken until the last page is generated...
- using synctex
- Q: I will try to attend one of your streamings... where can I find info about them?
- A: https://tv.dyne.org/c/phimulambda
- we also have an IRC at #phi-mu-lambda you're also welcomed there edrx
- Q: Oh, emacs reader can open epubs? I use nov.el for that, and it has trouble sometimes with complex epubs.
- yup it can :D
- it comes for free with mupdf
- I mean if mupdf supports it, emacs reader will to
- the only thing we don't support is djvu, but i have plans of making it supported in upstream mupdf
- Oh cool, I didn't know about the other formats!
- [https://codeberg.org/divyaranjan/emacs-reader](https://codeberg.org/divyaranjan/emacs-reader)
- [https://mupdf.com/](https://mupdf.com/)
- [https://www.phimulambda.org/blog/emacs-dynamic-module.html](https://www.phimulambda.org/blog/emacs-dynamic-module.html)
\<\-- that\'s a nice blog post.
- Love this arch diagram step through
- The linked blog for dynamic modules:
[https://www.phimulambda.org/blog/emacs-dynamic-module.html](https://www.phimulambda.org/blog/emacs-dynamic-module.html)
- You can set the maximum ram usage in Okular settings. If it is
configured to load the entire document scrolling is instant even in
large documents \[not the author: this is only relevant to hugely
beefy machines, surely? And it sounds like the Reader does it
naturally, if you will\]
- 16GB of RAM goes a long way even for huge documents like technical
datasheets or photo pdfs. Just be careful not to open too many of
them while also having a lot of browser tabs.
- Looks like Reader simply displays the old page until the new one is
ready. While better than showing a white page it\'s not instant like
Okular
- A: Emacs reader doesn\'t require 16GB RAM to do that same, because
it doesn\'t need to cache everything at once, unlike Okular. The
talk shows a video demonstration of it getting stuck when not
configured to use maximum ram (in which it caches the pages.).
- I didn't realize pdf-tools was using so much RAM.
- I definitely noticed, lol
- The memory graphs are already a very compelling point for emacs reader. I will definitely give this a try.
- If you are dealing with large PDFs you *really* feel the difference
- For doc-view yes. For pdf-tools I have noticed it, but very rarely.
- But yeah, it is interesting how much memory it's taking
- I will definitely try this
- pdf tool caches the pages. once you are moving too fast, it is almost as slow as doc view, because it doesn't have it cached anymore
- This look promising! Dealing with PDFs is an important part of the
things I do with Emacs (academic work). Certainly that Pdf-tools was
already a much needed improvement to Doc-View - for example, not
being able to select text was quite an issue. So when you get text
selection and annotations working, I will be certainly looking
forward your library.
- Great talk about emacs-reader. Looking forward to using it.
- Thank you for making this! :-)
- Really tasteful typography on your slides divya
- A: Thank you it's all in Org :)
- I like pdf-tools, but I'm open to trying something new.
- pdf-tools mostly works well, but these points are very much valid
- also have been fairly satisfied with pdf-tools and avoided installation pain because the package manager of choice makes it easy, intrigued by reader and curious to try regardless though
- I've been using emacs-reader for some time - I have packaged it for nix, although I haven't submitted it to nixpkgs in the hope that emacs-reader will one day end up in ELPA/MELPA. https://git.sr.ht/~johnhamelink/nix/tree/master/item/home/modules/emacs/src/epkgs/reader.nix
- Love this arch diagram step through
- Org-noter integration would be very good
- I am also a big org-noter user
- A: I used pdf-tools for several years, indeed I love org-noter as well. certainly a priority integration for us.
- I like the use of diagrams in this talk. It makes it easier to understand.
- I just realized the thread pool has a bunch of "threads" in it!
- That's what those were! I was thinking, "What does 'S' stand for?"
- very impressive work, I'll have to try this later
- Very nice. I'm definitely giving this a try.
- On my OS: MuPDF version 1.19.0 too old. Require ≥ 1.26.0.
- yueah that is a major problem
- Already looks very promising and the upcoming features are likely to make me switch completely from pdf-tools.
- Exciting project!
- very cool!
- Playing with mupdf standalone, epubs look very nice!
- very nice talk.
- great talk divya! great talk indeed!
- Great talk, thank you!
- I'm sold on Emacs Reader. (looking forward to org-noter support)
- fantastic talk! many claps! =)
- Super cool, emacs-reader on the list to try, we'll see if I can get it installed before the ELPA release
- I'm super excited about this 😊
- great presentation 👏
- Great talk about emacs-reader. Looking forward to using it.
[[!inline pages="internal(2025/info/reader-after)" raw="yes"]]
[[!inline pages="internal(2025/info/reader-nav)" raw="yes"]]
|
