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.^[12][13] Following complaints from users, it was removed after version 6.2.1.^[14]

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.^[15]".

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.

Bookmark Troubles

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
        w-- shrinkwrap
        f-- fullscreen
        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
        q-- quit

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.

The Code

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

Summary

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.

Sign in