PDF Tools is, among other things, a replacement of DocView for PDF files. The key difference is, that pages are not prerendered 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 programm. This
programm is called epdfinfo
and it’s 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 informations about a document and is also able to modify it, there is a lot more we can do with it. Watch
View PDF documents in a buffer with DocView-like bindings.
Interactively search PDF documents like any other buffer. (Though there is currently no regexp support.)
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.
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.
Save files attached to the PDF-file or list them in a dired buffer.
Use imenu or a special buffer to examine and navigate the PDF’s outline.
Jump from a position on a page directly to the TeX source and vice-versa.
- Display PDF’s metadata.
- Mark a region and kill the text from the PDF.
- Search for occurrences of a string.
- Keep track of visited pages via a history.
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. (On this system prerequisites may be installed automatically, see Compilation .)
First make shure 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 shure
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
Now it’s time to compile the source. Since we are building from the git repository, we have to initialize the build-system first. There is a tiny script in the root directory doing this for us.
$ cd /path/to/pdf-tools
$ ./autogen.sh
The autogen.sh
also takes an optional argument --install-deps
,
which will try to install above prerequisites.
Now comes the familiar
./configure && make
which should compile the source code and create a Emacs Lisp Package in the root directory. 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.
If make
produced the ELP file pdf-tools-0.40.tar
you are fine.
This package contains all the nescessary files for Emacs and may
be installed via
$ make install-package
Alternatively start the one true Editor from the same directory and execute the command
M-x package-install-file RET pdf-tools-0.40.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 might 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
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. To avoid this kind of problems, you
should delete the old package via list-packages
, restart Emacs
and then reinstall the package.