1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
#+TITLE: PDF Tools README
#+AUTHOR: Andreas Politz
#+EMAIL: politza@fh-trier.de
[[http://melpa.org/#/pdf-tools][http://melpa.org/packages/pdf-tools-badge.svg]]
[[https://travis-ci.org/politza/pdf-tools.svg?branch%3Dmaster][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 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. [[http://www.dailymotion.com/video/x2bc1is_pdf-tools-tourdeforce_tech?forcedQuality%3Dhd720][Watch]]
** 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.
*** Misc
+ Display PDF's metadata.
+ Mark a region and kill the text from the PDF.
+ Keep track of visited pages via a history.
** Installation
The package may be installed via melpa and it will try to build the
server part when it is actiated the first time, though next section
is still relevant.
*** 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]] .)
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.
#+begin_src sh
$ sudo aptitude install libpng-dev libz-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~.
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 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:
#+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
#+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.
*** Compilation
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
nescessary programms 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.
*** Installing
If ~make~ produced the ELP file ~pdf-tools-${VERSION}.tar~ you are
fine. This package contains all the nescessary 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.
# Local Variables:
# mode: org
# End:
|
