Emacs support library for PDF files.
Emacs Lisp C Makefile C++ M4 TeX
Switch branches/tags
Latest commit f314597 Apr 17, 2017 Andreas Politz Replace tabs with spaces

README.org

PDF Tools README

http://melpa.org/packages/pdf-tools-badge.svg https://travis-ci.org/politza/pdf-tools.svg?branch=master

About this package

PDF Tools is, among other things, a replacement of DocView for PDF files. The key difference is, that pages are not pre-rendered by e.g. ghostscript and stored in the file-system, but rather created on-demand and stored in memory.

This rendering is performed by a special library named, for whatever reason, poppler, running inside a server program. This program is called epdfinfo and its job is it to successively read requests from Emacs and produce the proper results, i.e. the PNG image of a PDF page.

Actually, displaying PDF files is just one part of PDF Tools. Since poppler can provide us with all kinds of information about a document and is also able to modify it, there is a lot more we can do with it. Watch

Please read also about known problems.

Features

View

View PDF documents in a buffer with DocView-like bindings.

Isearch

Interactively search PDF documents like any other buffer, either for a string or a PCRE.

Occur

List lines matching a string or regexp in one or more PDF documents.

Follow links

Click on highlighted links, moving to some part of a different page, some external file, a website or any other URI. Links may also be followed by keyboard commands.

Annotations

Display and list text and markup annotations (like underline), edit their contents and attributes (e.g. color), move them around, delete them or create new ones and then save the modifications back to the PDF file.

Attachments

Save files attached to the PDF-file or list them in a dired buffer.

Outline

Use imenu or a special buffer to examine and navigate the PDF’s outline.

SyncTeX

Jump from a position on a page directly to the TeX source and vice versa.

Virtual PDF

Use a collection of documents as if it where one, big single PDF.

Misc

  • Display PDF’s metadata.
  • Mark a region and kill the text from the PDF.
  • Keep track of visited pages via a history.
  • Apply a color filter for reading in low light conditions.

Installation

The package may be installed via melpa and it will try to build the server part when it is activated the first time, though the next section is still relevant.

Server Prerequisites

You’ll need GNU Emacs ≥ 24.3 and some form of a GNU/Linux OS. Other operating systems are currently not supported (patches welcome). The following instructions assume a Debian-based system. (The prerequisites may be installed automatically on this kind of systems, see Compilation .)

First make sure a suitable build-system is installed. We need at least a C/C++ compiler (both gcc and g++), make, automake and autoconf.

Next we need to install a few libraries PDF Tools depends on, some of which are probably already on your system.

$ sudo aptitude install libpng-dev libz-dev
$ sudo aptitude install libpoppler-glib-dev
$ sudo aptitude install libpoppler-private-dev

On some older Ubuntu systems, the final command will possibly give an error. This should be no problem, since in some versions this package was contained in the main package libpoppler-dev.

Debian wheezy comes with libpoppler version 0.18, which is pretty old. The minimally required version is 0.16, but some features of PDF Tools depend on a more recent version of this library. See the following table for what they are and what version they require.

You want to …Required version
… create and modify text annotations.≥ 0.19.4
… search case-sensitive.≥ 0.22
… create and modify markup annotations.≥ 0.26

In case you decide to install libpoppler from source, make sure to run it’s configure script with the --enable-xpdf-headers option.

Finally there is one feature (following links of a PDF document by plain keystrokes) which requires imagemagick’s convert utility. This requirement is optional and you may install it like so:

$ sudo aptitude install imagemagick

Compiling on OS X

Although OS X is not officially supported, it has been reported to have been successfully compiled. You will need to install poppler which you can get with homebrew via

$ brew install poppler automake

You will also have to help pkg-config find some libraries by setting PKG_CONFIG_PATH, e.g.

$ export PKG_CONFIG_PATH=/usr/local/Cellar/zlib/1.2.8/lib/pkgconfig:/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig

or likewise within Emacs using `setenv`.

After that, compilation should proceed as normal.

Compiling on FreeBSD

Although not officially suppported, it has been reported that pdf-tools work well on FreeBSD. Install the dependencies with

$ pkg install autotools gmake poppler-glib

If you choose not to install from melpa, you must substitute gmake for make in the instructions below.

Compiling on Windows

PDF Tools can be built and used on Windows using the MSYS2 compiler. This will work with native (not cygwin) Windows builds of emacs. This includes the standard binaries provided by the GNU project, those available as MSYS2 packages and numerous third-party binaries. It has been tested with emacs 25.1. Instructions are provided under Compilation and installation on Windows, below.

Compilation

Now it’s time to compile the source.
$ cd /path/to/pdf-tools
$ make install-server-deps # optional
$ make -s

The make install-server-deps command will try to install all necessary programs and libraries to build the package, though it’ll only work, if sudo and apt-get are available.

This should compile the source code and create a Emacs Lisp Package in the root directory of the project. The configure script also tells you at the very end, which features, depending on the libpoppler version, will be available. These commands should give no error, otherwise you are in trouble.

Compilation and installation on Windows

If using the GNU binaries for Windows, support for PNG and zlib must first be installed by copying the appropriate dlls into emacs’ bin/ directory. Most third-party binaries come with this already done.

First, install install MSYS2 and update the package database and core packages using the instructions provided. Then, to compile PDF tools itself:

  1. Open msys2 shell
  2. Update and install dependencies, skipping any you already have
    pacman -Syu
    pacman -S base-devel
    pacman -S mingw-w64-x86_64-toolchain
    pacman -S mingw-w64-x86_64-zlib
    pacman -S mingw-w64-x86_64-libpng
    pacman -S mingw-w64-x86_64-poppler
    pacman -S mingw-w64-x86_64-imagemagick
        
  3. Install PDF tools in Emacs, but do not try to compile the server. Instead, get a separate copy of the source somewhere else.
    git clone https://github.com/politza/pdf-tools
        
  4. Open mingw64 shell
  5. Compile pdf-tools
    cd pdf-tools/build
    make -s
        
  6. This should produce a file server/epdfinfo.exe. Copy this file into the pdf-tools/ installation directory in your Emacs.
  7. Start Emacs and activate the package.
    M-x pdf-tools-install RET
        
  8. Test.
    M-x pdf-info-check-epdfinfo RET
        

If this is successful, (pdf-tools-install) can be added to Emacs’ config. Note that libraries from other GNU utilities, such as Git for Windows, may interfere with those needed by PDF Tools. pdf-info-check-epdinfo will succeed, but errors occur when trying to view a PDF file. This can be fixed by ensuring that the MSYS libraries are always preferred in emacs:

(setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv "PATH")))

Installing

If make produced the ELP file pdf-tools-${VERSION}.tar you are fine. This package contains all the necessary files for Emacs and may be installed by either using

$ make install-package

or executing the Emacs command

M-x package-install-file RET pdf-tools-${VERSION}.tar RET

To complete the installation process, you need to activate the package by putting

(pdf-tools-install)

somewhere in your .emacs. Next you probably want to take a look at the various features of what you’ve just installed. The following two commands might be of help for doing so.

M-x pdf-tools-help RET
M-x pdf-tools-customize RET

Updating

Some day you might want to update this package via git pull and then reinstall it. Sometimes this may fail, especially if Lisp-Macros are involved and the version hasn’t changed. To avoid this kind of problems, you should delete the old package via list-packages, restart Emacs and then reinstall the package.

This also applies when updating via package and melpa.

Known problems

linum-mode

PDF Tools does not work well together with linum-mode and activating it in a pdf-view-mode, e.g. via global-linum-mode, might make Emacs choke.

auto-revert

Autorevert works by polling the file-system every auto-revert-interval seconds, optionally combined with some event-based reverting via file notification. But this currently does not work reliably, such that Emacs may revert the PDF-buffer while the corresponding file is still being written to (e.g. by LaTeX), leading to a potential error.

With a recent auctex installation, you might want to put the following somewhere in your dotemacs, which will revert the PDF-buffer after the TeX compilation has finished.

(add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer)

Some keybindings

Navigation
Scroll Up / Down by page-fullspace / backspace
Scroll Up / Down by lineC-n / C-b
Scroll Right / LeftC-f / C-b
Top of Page / Bottom of Page< / >
Next Page / Previous Pagen / p
First Page / Last PageM-< / M->
Incremental Search Forward / BackwardC-s / C-r
Occur (list all lines containing a phrase)M-s o
Jump to Occur LineRETURN
Pick a Link and JumpF
Incremental Search in Linksf
History Back / ForwardsB / F
Display Outlineo
Jump to Section from OutlineRETURN
Jump to PageM-g g
Display
Zoom in / Zoom out+ / -
Fit Height / Fit Width / Fit PageH / W / P
Trim margins (set slice to bounding box)s b
Reset marginss r
Reset Zoom0
Annotations
List AnnotationsC-c C-a l
Jump to Annotations from ListSPACE
Mark Annotation for Deletiond
Delete Marked Annotationsx
Unmark Annotationsu
Close Annotation Listq
Add and edit annotationsvia Mouse selection and left-click context menu
Syncing with Auctex
jump to PDF location from sourceC-c C-g
jump source location from PDFdouble-click
Miscellaneous
Refresh File (e.g., after recompiling source)g
Print FileC-c C-p