Tools of the Trade: reading PDFs (and keeping bookmarks)
In this article I will take a look at the wonderful MuPDF viewer and present a small modification that saves bookmarks alongside the pdf files, making it infinitely more useful.
Some days I sit down to work and wonder how anything ever gets done. A simple example. When I work on an FPGA design, I wind up with 3 or 4 screens full of documentation, generally in PDF format. There are the Xilinx manuals, the various tool manuals, language reference manuals, you name it. While sourcing parts, I have dozens of specsheets and catalogs open at the same time.
For years I suffered the insult and the injury of just awful pdf readers. While some would say that whatever I had was better than an overflowing desk full of out-of date manuals, reading technical books on the screen is a lot more painful than leafing through a book.
First of all, let's look at Adobe Acrobat Reader. Not opensourced. God only knows what it does, what it phones home with, and why it takes up so much space. Not to mention that it was the leading cause of crashing Windows until I wised up and eventually gave up on both Windows and Adobe Reader.
At some point I found Foxit reader. I used it a lot - it was fast and lightweight. However, some issues came up. To be fair, I will just quote Wikipedia:
"With version 6.1.4, the Foxit installer was bundled with potentially unwanted programs like OpenCandy which installed the browser-hijacking malware Conduit. Following complaints from users, it was removed after version 6.2.1.
In July 2014, the Internet Storm Center reported that the mobile version for iPhone was transmitting unencrypted telemetry and other data to remote servers located in China despite users attempting to opt out of such data collection.".
Crap. No more closed-source readers for me.
I messed around with a few open source PDF readers over the years. Most are slow, ugly, large or some combination thereof. God help us all.
Screen Real Estate Issues
For a reason I fail to comprehend, modern applications take up as much of my screen as they can possibly get away with. As if elaborate frames and menu bars are not enough, icon bars and vertical toolbars, not to mention useless index panes, are there to drive me completely insane.
What is that about? Retail manufacturers pad their boxes to make their merchandise look like a better deal. Not to mention leaving less shelf room for competitors. But this does not translate to computer screens. This is just pure madness.
Now I am not asking for much. I want to bookmark a few choice pages, preferably with keyboard shortcuts. I want my bookmarks persistent, and portable across machines. So all the moronic contraptions that write bookmark files to some hidden directory are out.
MuPDF To The Rescue
MuPDF was the answer to my prayers. It is free and open-sourced. It is reasonably small. It is fast, ridiculously fast. Pages fly as fast as your keyboard's repeat rate when you press page down. You actually feel like you are leafing through a book, just with the page down key. No scroll bars are necessary.
And it's completely unobtrusive - there is no visible user-interface garbage. None. It actually looks like this:
And when you open another pdf file, it just pops another one of these clean windows. Not some idiotic tab.
L-- rotate left
R-- rotate right
h-- scroll left
j down-- scroll down
k up-- scroll up
l-- scroll right
+-- zoom in
--- zoom out
W-- zoom to fit window width
H-- zoom to fit window height
Z-- zoom to fit page
r-- reload file
. pgdn right spc\t-- next page
, pgup left b bkspc\t-- previous page
>-- next 10 pages
<-- back 10 pages
m-- mark page for snap back
t-- pop back to latest mark
1m-- mark page in register 1
1t-- go to page in register 1
G-- go to last page
123g-- go to page 123
/-- search forwards for text
?-- search backwards for text
n-- find next search result
N-- find previous search result
c-- toggle between color and grayscale
i-- toggle inverted color mode
Fixing the Bookmark Issue
There is just enough bookmark functionality in MuPDF. There are 10 bookmarks that can be set by hitting a number key followed by m (mark) and recalled by t (I don't know why). There is an elaborate history queue accessible with m and t keys without any numbers, just keep hitting m to save position and t to back up.
The bookmarks do not persist however. But this is an open-sourced project, so less then 10 lines of C code (and a couple of hours to figure out where to put them), solved all my problems. It turned out to be a lot easier then I ever expected.
I made a small modification to write a bookmark file alongside the original pdf. The file contains 40 bytes - 10 4-byte ints containing page numbers of the bookmarked items. The file is writen when a new bookmark is created, so most of my casual browsing doesn't even pollute the drive.
And since the bookmarks are sitting right next to the original files, I can copy them to another machine as needed. Sweet relief.
Since MuPDF does not maintain github presense, I created a github repo for MuPDF 1.7a, along with my modification (as detailed in the README file).
I recommend that you give MuPDF a try (with or without my mods). It is fast, clean and extremely usable. With the simple bookmark persistence mod it completely satisfies all my pdf viewing needs. If only the rest of my projects were that easy.
P.S. I am in no way affiliated with the MuPDF project. I just like it a lot.
If you are using Linux, Okular and Evince are good alternatives as well.
I understand the desire to be away from Adobe and Foxit, but this is pretty stark.
To post reply to a comment, click on the 'reply' button attached to each comment. To post a new comment (not a reply to a comment) check out the 'Write a Comment' tab at the top of the comments.
Please login (on the right) if you already have an account on this platform.
Otherwise, please use this form to register (free) an join one of the largest online community for Electrical/Embedded/DSP/FPGA/ML engineers: