372 lines
16 KiB
Plaintext
372 lines
16 KiB
Plaintext
#+TITLE: PDF Tools README
|
|
#+AUTHOR: Andreas Politz
|
|
#+EMAIL: politza@fh-trier.de
|
|
|
|
[[https://travis-ci.org/politza/pdf-tools.svg?branch%3Dmaster][https://travis-ci.org/politza/pdf-tools.svg?branch=master]]
|
|
[[http://stable.melpa.org/#/pdf-tools][http://stable.melpa.org/packages/pdf-tools-badge.svg]]
|
|
[[http://melpa.org/#/pdf-tools][http://melpa.org/packages/pdf-tools-badge.svg]]
|
|
|
|
|
|
|
|
** 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 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. [[http://www.dailymotion.com/video/x2bc1is_pdf-tools-tourdeforce_tech?forcedQuality%3Dhd720][Watch]]
|
|
|
|
Please read also about [[#known-problems][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 ::
|
|
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 ::
|
|
Use a collection of documents as if it were 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 regarding build-prerequisites is still relevant, the rest
|
|
of the installation instructions assume a build from within a git
|
|
repository. (The melpa package has a different directory
|
|
structure.)
|
|
|
|
*** Server Prerequisites
|
|
You'll need GNU Emacs \ge 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][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.
|
|
#+begin_src sh
|
|
$ sudo aptitude install libpng-dev zlib1g-dev
|
|
$ sudo aptitude install libpoppler-glib-dev
|
|
$ sudo aptitude install libpoppler-private-dev
|
|
#+end_src
|
|
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~. Also
|
|
note, that ~zlib1g-dev~ was for a long time called ~libz-dev~,
|
|
which it still may be on your system.
|
|
|
|
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. | \ge 0.19.4 |
|
|
| ... search case-sensitive. | \ge 0.22 |
|
|
| ... create and modify markup annotations. | \ge 0.26 |
|
|
|-------------------------------------------+------------------|
|
|
|
|
In case you decide to install libpoppler from source, make sure
|
|
to run its 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:
|
|
#+begin_src sh
|
|
$ sudo aptitude install imagemagick
|
|
#+end_src
|
|
**** 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
|
|
#+BEGIN_SRC sh
|
|
$ brew install poppler automake
|
|
#+END_SRC
|
|
|
|
You will also have to help ~pkg-config~ find some libraries by
|
|
setting ~PKG_CONFIG_PATH~, e.g.
|
|
#+BEGIN_SRC sh
|
|
$ export PKG_CONFIG_PATH=/usr/local/Cellar/zlib/1.2.8/lib/pkgconfig:/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig
|
|
#+END_SRC
|
|
or likewise within Emacs using `setenv`.
|
|
|
|
After that, compilation should proceed as normal.
|
|
**** FreeBSD
|
|
Although not officially supported, it has been reported that
|
|
pdf-tools work well on FreeBSD. Instead of building pdf-tools, you
|
|
can install one of the OS packages with, e.g.
|
|
#+BEGIN_SRC sh
|
|
$ pkg install pdf-tools-emacs25
|
|
#+END_SRC
|
|
To see the current list of pdf-tools packages for FreeBSD visit
|
|
[[https://repology.org/metapackages/?search=pdf-tools&inrepo=freebsd][the Repology list]].
|
|
|
|
To build pdf-tools from either melpa or directly from the source
|
|
repository, install the dependencies with
|
|
#+BEGIN_SRC sh
|
|
$ pkg install autotools gmake poppler-glib
|
|
#+END_SRC
|
|
|
|
If you choose not to install from melpa, you must substitute
|
|
~gmake~ for ~make~ in the instructions below.
|
|
**** Compiling on Centos
|
|
It is possible to compile pdf-tools on Centos. Install poppler the dependencies with:
|
|
#+BEGIN_SRC sh
|
|
$ yum install poppler-devel poppler-glib-devel
|
|
#+END_SRC
|
|
|
|
**** Compiling on Fedora
|
|
#+BEGIN_SRC sh
|
|
$ sudo dnf install make automake autoconf gcc gcc-c++ ImageMagick libpng-devel zlib-devel poppler-glib-devel
|
|
#+END_SRC
|
|
|
|
**** 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][Compilation and installation on Windows]], below.
|
|
PDF Tools will successfully compile using Cygwin, but it will not be
|
|
able to open PDFs properly due to the way binaries compiled with Cygwin
|
|
handle file paths.
|
|
|
|
*** Compilation
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: compilation
|
|
:END:
|
|
Now it's time to compile the source.
|
|
#+begin_src sh
|
|
$ cd /path/to/pdf-tools
|
|
$ make install-server-deps # optional
|
|
$ make -s
|
|
#+end_src
|
|
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 [[http://www.msys2.org/][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
|
|
#+BEGIN_SRC sh
|
|
$ 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
|
|
#+END_SRC
|
|
|
|
3. Install PDF tools in Emacs, but do not try to compile the
|
|
server. Instead, get a separate copy of the source somewhere
|
|
else.
|
|
#+BEGIN_SRC sh
|
|
$ git clone https://github.com/politza/pdf-tools
|
|
#+END_SRC
|
|
|
|
4. Open mingw64 shell (*Note:* You must use mingw64.exe and not msys2.exe)
|
|
|
|
5. Compile pdf-tools
|
|
#+BEGIN_SRC sh
|
|
$ cd /path/to/pdf-tools
|
|
$ make -s
|
|
#+END_SRC
|
|
|
|
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.
|
|
#+BEGIN_SRC
|
|
M-x pdf-tools-install RET
|
|
#+END_SRC
|
|
|
|
8. Test.
|
|
#+BEGIN_SRC
|
|
M-x pdf-info-check-epdfinfo RET
|
|
#+END_SRC
|
|
|
|
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:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv "PATH")))
|
|
#+END_SRC
|
|
|
|
*** ELisp Prerequisites
|
|
This package depends on the following Elisp packages, which should
|
|
be installed before installing the Pdf Tools package.
|
|
|
|
| Package | Required version |
|
|
|-----------+----------------------------------|
|
|
| [[https://elpa.gnu.org/packages/let-alist.html][let-alist]] | >= 1.0.4 (comes with Emacs 25.2) |
|
|
| [[http://melpa.org/#/tablist][tablist]] | >= 0.70 |
|
|
|-----------+----------------------------------|
|
|
|
|
*** 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
|
|
#+begin_src sh
|
|
$ make install-package
|
|
#+end_src
|
|
or executing the Emacs command
|
|
#+begin_src elisp
|
|
M-x package-install-file RET pdf-tools-${VERSION}.tar RET
|
|
#+end_src
|
|
|
|
To complete the installation process, you need to activate the
|
|
package by putting
|
|
#+begin_src elisp
|
|
(pdf-tools-install)
|
|
#+end_src
|
|
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.
|
|
#+begin_src elisp
|
|
M-x pdf-tools-help RET
|
|
M-x pdf-tools-customize RET
|
|
#+end_src
|
|
|
|
*** 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
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: known-problems
|
|
:END:
|
|
|
|
*** 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 [[https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html][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 [[https://www.gnu.org/software/auctex/][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.
|
|
#+BEGIN_SRC emacs-lisp
|
|
(add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer)
|
|
#+END_SRC
|
|
** Some keybindings
|
|
|
|
| Navigation | |
|
|
|--------------------------------------------+-----------------------|
|
|
| Scroll Up / Down by page-full | ~space~ / ~backspace~ |
|
|
| Scroll Up / Down by line | ~C-n~ / ~C-b~ |
|
|
| Scroll Right / Left | ~C-f~ / ~C-b~ |
|
|
| Top of Page / Bottom of Page | ~<~ / ~>~ |
|
|
| Next Page / Previous Page | ~n~ / ~p~ |
|
|
| First Page / Last Page | ~M-<~ / ~M->~ |
|
|
| Incremental Search Forward / Backward | ~C-s~ / ~C-r~ |
|
|
| Occur (list all lines containing a phrase) | ~M-s o~ |
|
|
| Jump to Occur Line | ~RETURN~ |
|
|
| Pick a Link and Jump | ~F~ |
|
|
| Incremental Search in Links | ~f~ |
|
|
| History Back / Forwards | ~B~ / ~F~ |
|
|
| Display Outline | ~o~ |
|
|
| Jump to Section from Outline | ~RETURN~ |
|
|
| Jump to Page | ~M-g g~ |
|
|
|
|
| Display | |
|
|
|------------------------------------------+-----------------|
|
|
| Zoom in / Zoom out | ~+~ / ~-~ |
|
|
| Fit Height / Fit Width / Fit Page | ~H~ / ~W~ / ~P~ |
|
|
| Trim margins (set slice to bounding box) | ~s b~ |
|
|
| Reset margins | ~s r~ |
|
|
| Reset Zoom | 0 |
|
|
|
|
| Annotations | |
|
|
|-------------------------------+-------------------------------------------------|
|
|
| List Annotations | ~C-c C-a l~ |
|
|
| Jump to Annotations from List | ~SPACE~ |
|
|
| Mark Annotation for Deletion | ~d~ |
|
|
| Delete Marked Annotations | ~x~ |
|
|
| Unmark Annotations | ~u~ |
|
|
| Close Annotation List | ~q~ |
|
|
| Add and edit annotations | via Mouse selection and left-click context menu |
|
|
|
|
| Syncing with Auctex | |
|
|
|----------------------------------+-------------|
|
|
| jump to PDF location from source | ~C-c C-g~ |
|
|
| jump source location from PDF | ~C-mouse-1~ |
|
|
|
|
| Miscellaneous | |
|
|
|-----------------------------------------------+-----------|
|
|
| Refresh File (e.g., after recompiling source) | ~g~ |
|
|
| Print File | ~C-c C-p~ |
|
|
|
|
# Local Variables:
|
|
# mode: org
|
|
# End:
|