README
1#+TITLE: PDF Tools README
2#+AUTHOR: Andreas Politz
3#+EMAIL: politza@fh-trier.de
4#+Maintainer: Vedang Manerikar
5#+Maintainer_Email: vedang.manerikar@gmail.com
6
7[[https://app.circleci.com/pipelines/github/vedang/pdf-tools][https://circleci.com/gh/vedang/pdf-tools.svg?style=svg]]
8[[https://stable.melpa.org/#/pdf-tools][http://stable.melpa.org/packages/pdf-tools-badge.svg]]
9[[https://melpa.org/#/pdf-tools][http://melpa.org/packages/pdf-tools-badge.svg]] [[https://ci.appveyor.com/project/vedang/pdf-tools][https://ci.appveyor.com/api/projects/status/yqic2san0wi7o5v8/branch/master?svg=true]]
10
11** About this package
12 PDF Tools is, among other things, a replacement of DocView for PDF
13 files. The key difference is that pages are not pre-rendered by
14 e.g. ghostscript and stored in the file-system, but rather created
15 on-demand and stored in memory.
16
17 This rendering is performed by a special library named, for
18 whatever reason, poppler, running inside a server program. This
19 program is called ~epdfinfo~ and its job is to successively
20 read requests from Emacs and produce the proper results, i.e. the
21 PNG image of a PDF page.
22
23 Actually, displaying PDF files is just one part of PDF Tools.
24 Since poppler can provide us with all kinds of information about a
25 document and is also able to modify it, there is a lot more we can
26 do with it. [[http://www.dailymotion.com/video/x2bc1is_pdf-tools-tourdeforce_tech?forcedQuality%3Dhd720][Watch]]
27
28 Please read also about [[#known-problems][known problems.]]
29
30** Features
31 + View :: View PDF documents in a buffer with DocView-like
32 bindings.
33 + Isearch :: Interactively search PDF documents like any other
34 buffer, either for a string or a PCRE.
35 + Occur :: List lines matching a string or regexp in one or more
36 PDF documents.
37 + Follow ::
38 Click on highlighted links, moving to some part of a different
39 page, some external file, a website or any other URI. Links may
40 also be followed by keyboard commands.
41 + Annotations :: Display and list text and markup annotations (like
42 underline), edit their contents and attributes
43 (e.g. color), move them around, delete them or
44 create new ones and then save the modifications
45 back to the PDF file.
46 + Attachments :: Save files attached to the PDF-file or list them
47 in a dired buffer.
48 + Outline :: Use imenu or a special buffer to examine and navigate
49 the PDF's outline.
50 + SyncTeX :: Jump from a position on a page directly to the TeX
51 source and vice versa.
52 + Virtual ::
53 Use a collection of documents as if it were one, big single PDF.
54
55 + Misc ::
56 - Display PDF's metadata.
57 - Mark a region and kill the text from the PDF.
58 - Keep track of visited pages via a history.
59 - Apply a color filter for reading in low light conditions.
60
61** Installation
62 The package may be installed via MELPA and it will try to build the
63 server part when it is activated the first time. Though the next
64 section regarding build-prerequisites is still relevant, the rest
65 of the installation instructions assume a build from within a git
66 repository. (The MELPA package has a different directory
67 structure.)
68
69*** Server prerequisites
70 You'll need GNU Emacs \ge 24.3 and some form of a GNU/Linux OS.
71 Other operating systems are currently not supported (patches
72 welcome). The following instructions assume a Debian-based
73 system. (The prerequisites may be installed automatically on this
74 kind of systems, see [[#compilation][Compilation]] .)
75
76 First make sure a suitable build-system is installed. We need at
77 least a C/C++ compiler (both ~gcc~ and ~g++~), ~make~, ~automake~
78 and ~autoconf~.
79
80 Next we need to install a few libraries PDF Tools depends on, some
81 of which are probably already on your system.
82#+begin_src sh
83 $ sudo aptitude install libpng-dev zlib1g-dev
84 $ sudo aptitude install libpoppler-glib-dev
85 $ sudo aptitude install libpoppler-private-dev
86#+end_src
87 On some older Ubuntu systems, the final command will possibly give
88 an error. This should be no problem, since in some versions this
89 package was contained in the main package ~libpoppler-dev~. Also
90 note, that ~zlib1g-dev~ was for a long time called ~libz-dev~,
91 which it still may be on your system.
92
93 Debian wheezy comes with libpoppler version 0.18, which is pretty
94 old. The minimally required version is 0.16, but some features of
95 PDF Tools depend on a more recent version of this library. See
96 the following table for what they are and what version they
97 require.
98
99 | You want to ... | Required version |
100 |-------------------------------------------+------------------|
101 | ... create and modify text annotations. | \ge 0.19.4 |
102 | ... search case-sensitive. | \ge 0.22 |
103 | ... create and modify markup annotations. | \ge 0.26 |
104 |-------------------------------------------+------------------|
105
106 In case you decide to install libpoppler from source, make sure
107 to run its configure script with the ~--enable-xpdf-headers~
108 option.
109
110 Finally there is one feature (following links of a PDF document by
111 plain keystrokes) which requires imagemagick's convert utility.
112 This requirement is optional and you may install it like so:
113#+begin_src sh
114 $ sudo aptitude install imagemagick
115#+end_src
116**** Compiling on macOS
117 Although macOS is not officially supported, it has been reported
118 to have been successfully compiled. You will need to install
119 poppler which you can get with Homebrew via
120#+BEGIN_SRC sh
121 $ brew install poppler automake
122#+END_SRC
123
124 You will also have to help ~pkg-config~ find some libraries by
125 setting ~PKG_CONFIG_PATH~, e.g.
126#+BEGIN_SRC sh
127 $ export PKG_CONFIG_PATH=/usr/local/Cellar/zlib/1.2.8/lib/pkgconfig:/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig
128#+END_SRC
129 or likewise within Emacs using `setenv`.
130
131 After that, compilation should proceed as normal.
132**** FreeBSD
133 Although not officially supported, it has been reported that
134 pdf-tools work well on FreeBSD. Instead of building pdf-tools, you
135 can install one of the OS packages with, e.g.
136#+BEGIN_SRC sh
137 $ pkg install pdf-tools-emacs26
138#+END_SRC
139 To see the current list of pdf-tools packages for FreeBSD visit
140 [[https://repology.org/metapackages/?search=pdf-tools&inrepo=freebsd][the Repology list]].
141
142 To build pdf-tools from either MELPA or directly from the source
143 repository, install the dependencies with
144#+BEGIN_SRC sh
145 $ pkg install autotools gmake poppler-glib
146#+END_SRC
147
148 If you choose not to install from MELPA, you must substitute
149 ~gmake~ for ~make~ in the instructions below.
150**** Compiling on CentOS
151 It is possible to compile pdf-tools on CentOS. Install poppler the dependencies with:
152#+BEGIN_SRC sh
153 $ yum install poppler-devel poppler-glib-devel
154#+END_SRC
155
156**** Compiling on Fedora
157#+BEGIN_SRC sh
158 $ sudo dnf install make automake autoconf gcc gcc-c++ ImageMagick libpng-devel zlib-devel poppler-glib-devel
159#+END_SRC
160
161**** Compiling on Alpine Linux
162#+BEGIN_SRC sh
163 $ apk add build-base g++ gcc automake autoconf libpng-dev glib-dev poppler-dev
164#+END_SRC
165
166**** Compiling on Windows
167 PDF Tools can be built and used on Windows using the MSYS2
168 compiler. This will work with native (not cygwin) Windows builds of
169 emacs. This includes the standard binaries provided by the GNU
170 project, those available as MSYS2 packages and numerous third-party
171 binaries. It has been tested with Emacs 25.1. Instructions are
172 provided under [[#compilation-and-installation-on-windows][Compilation and installation on Windows]], below.
173 PDF Tools will successfully compile using Cygwin, but it will not be
174 able to open PDFs properly due to the way binaries compiled with Cygwin
175 handle file paths.
176
177*** Compilation
178 :PROPERTIES:
179 :CUSTOM_ID: compilation
180 :END:
181 Now it's time to compile the source.
182#+begin_src sh
183 $ cd /path/to/pdf-tools
184 $ make install-server-deps # optional
185 $ make -s
186#+end_src
187 The ~make install-server-deps~ command will try to install all
188 necessary programs and libraries to build the package, though
189 it'll only work, if ~sudo~ and ~apt-get~ are available.
190
191 This should compile the source code and create a Emacs Lisp
192 Package in the root directory of the project. The configure script
193 also tells you at the very end, which features, depending on the
194 libpoppler version, will be available. These commands should give
195 no error, otherwise you are in trouble.
196**** Compilation and installation on Windows
197 :PROPERTIES:
198 :CUSTOM_ID: compilation-and-installation-on-windows
199 :END:
200 If using the GNU binaries for Windows, support for PNG and zlib
201 must first be installed by copying the appropriate dlls into
202 emacs' ~bin/~ directory. Most third-party binaries come with this
203 already done.
204
205 First, install [[http://www.msys2.org/][install MSYS2]] and update
206 the package database and core packages using the instructions
207 provided. Then, to compile PDF tools itself:
208
209 1. Open msys2 shell
210
211 2. Update and install dependencies, skipping any you already have
212 #+BEGIN_SRC sh
213 $ pacman -Syu
214 $ pacman -S base-devel
215 $ pacman -S mingw-w64-x86_64-toolchain
216 $ pacman -S mingw-w64-x86_64-zlib
217 $ pacman -S mingw-w64-x86_64-libpng
218 $ pacman -S mingw-w64-x86_64-poppler
219 $ pacman -S mingw-w64-x86_64-imagemagick
220 #+END_SRC
221
222 3. Install PDF tools in Emacs, but do not try to compile the
223 server. Instead, get a separate copy of the source somewhere
224 else.
225 #+BEGIN_SRC sh
226 $ git clone https://github.com/politza/pdf-tools
227 #+END_SRC
228
229 4. Open ~mingw64~ shell (*Note:* You must use ~mingw64.exe~ and not ~msys2.exe~)
230
231 5. Compile pdf-tools
232 #+BEGIN_SRC sh
233 $ cd /path/to/pdf-tools
234 $ make -s
235 #+END_SRC
236
237 6. This should produce a file ~server/epdfinfo.exe~. Copy this file
238 into the ~pdf-tools/~ installation directory in your Emacs.
239
240 7. Start Emacs and activate the package.
241 #+BEGIN_SRC
242 M-x pdf-tools-install RET
243 #+END_SRC
244
245 8. Test.
246 #+BEGIN_SRC
247 M-x pdf-info-check-epdfinfo RET
248 #+END_SRC
249
250 If this is successful, ~(pdf-tools-install)~ can be added to Emacs'
251 config. Note that libraries from other GNU utilities, such as Git
252 for Windows, may interfere with those needed by PDF Tools.
253 ~pdf-info-check-epdinfo~ will succeed, but errors occur when trying
254 to view a PDF file. This can be fixed by ensuring that the MSYS
255 libraries are always preferred in Emacs:
256
257 #+BEGIN_SRC emacs-lisp
258 (setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv "PATH")))
259 #+END_SRC
260
261*** Elisp prerequisites
262 This package depends on the following Elisp packages, which should
263 be installed before installing the PDF Tools package.
264
265 | Package | Required version |
266 |-----------+----------------------------------|
267 | [[https://elpa.gnu.org/packages/let-alist.html][let-alist]] | >= 1.0.4 (comes with Emacs 25.2) |
268 | [[http://melpa.org/#/tablist][tablist]] | >= 0.70 |
269 |-----------+----------------------------------|
270
271*** Installing
272 If ~make~ produced the ELP file ~pdf-tools-${VERSION}.tar~ you are
273 fine. This package contains all the necessary files for Emacs
274 and may be installed by either using
275#+begin_src sh
276 $ make install-package
277#+end_src
278 or executing the Emacs command
279#+begin_src elisp
280 M-x package-install-file RET pdf-tools-${VERSION}.tar RET
281#+end_src
282
283 To complete the installation process, you need to activate the
284 package by putting
285#+begin_src elisp
286 (pdf-tools-install)
287#+end_src
288 somewhere in your ~.emacs~. Alternatively, and if you care about
289 start-up time, you may want to use
290#+begin_src elisp
291 (pdf-loader-install)
292#+end_src
293 instead. Next you probably want to take a look at the various
294 features of what you've just installed. The following two commands
295 might be of help for doing so.
296#+begin_src elisp
297 M-x pdf-tools-help RET
298 M-x pdf-tools-customize RET
299#+end_src
300
301*** Updating
302 Some day you might want to update this package via ~git pull~ and
303 then reinstall it. Sometimes this may fail, especially if
304 Lisp-Macros are involved and the version hasn't changed. To avoid
305 this kind of problems, you should delete the old package via
306 ~list-packages~, restart Emacs and then reinstall the package.
307
308 This also applies when updating via package and MELPA.
309
310** Known problems
311 :PROPERTIES:
312 :CUSTOM_ID: known-problems
313 :END:
314
315*** linum-mode
316 PDF Tools does not work well together with ~linum-mode~ and
317 activating it in a ~pdf-view-mode~, e.g. via ~global-linum-mode~,
318 might make Emacs choke.
319
320*** auto-revert
321 Autorevert works by polling the file-system every
322 ~auto-revert-interval~ seconds, optionally combined with some
323 event-based reverting via [[https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html][file notification]]. But this currently
324 does not work reliably, such that Emacs may revert the PDF-buffer
325 while the corresponding file is still being written to (e.g. by
326 LaTeX), leading to a potential error.
327
328 With a recent [[https://www.gnu.org/software/auctex/][AUCTeX]] installation, you might want to put the
329 following somewhere in your dotemacs, which will revert the PDF-buffer
330 *after* the TeX compilation has finished.
331#+BEGIN_SRC emacs-lisp
332 (add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer)
333#+END_SRC
334
335*** sublimity
336 L/R scrolling breaks while zoomed into a pdf, with usage of sublimity smooth scrolling features
337
338** Some keybindings
339
340| Navigation | |
341|--------------------------------------------+-----------------------|
342| Scroll Up / Down by Page-full | ~space~ / ~backspace~ |
343| Scroll Up / Down by Line | ~C-n~ / ~C-p~ |
344| Scroll Right / Left | ~C-f~ / ~C-b~ |
345| Top of Page / Bottom of Page | ~<~ / ~>~ |
346| Next Page / Previous Page | ~n~ / ~p~ |
347| First Page / Last Page | ~M-<~ / ~M->~ |
348| Incremental Search Forward / Backward | ~C-s~ / ~C-r~ |
349| Occur (list all lines containing a phrase) | ~M-s o~ |
350| Jump to Occur Line | ~RETURN~ |
351| Pick a Link and Jump | ~F~ |
352| Incremental Search in Links | ~f~ |
353| History Back / Forwards | ~B~ / ~N~ |
354| Display Outline | ~o~ |
355| Jump to Section from Outline | ~RETURN~ |
356| Jump to Page | ~M-g g~ |
357
358| Display | |
359|------------------------------------------+-----------------|
360| Zoom in / Zoom out | ~+~ / ~-~ |
361| Fit Height / Fit Width / Fit Page | ~H~ / ~W~ / ~P~ |
362| Trim Margins (set slice to bounding box) | ~s b~ |
363| Reset Margins | ~s r~ |
364| Reset Zoom | 0 |
365
366| Annotations | |
367|-------------------------------+-------------------------------------------------|
368| List Annotations | ~C-c C-a l~ |
369| Jump to Annotations from List | ~SPACE~ |
370| Mark Annotation for Deletion | ~d~ |
371| Delete Marked Annotations | ~x~ |
372| Unmark Annotations | ~u~ |
373| Close Annotation List | ~q~ |
374| Add and Edit Annotations | via Mouse selection and left-click context menu |
375
376| Syncing with AUCTeX | |
377|----------------------------------+-------------|
378| Jump to PDF Location from Source | ~C-c C-g~ |
379| Jump Source Location from PDF | ~C-mouse-1~ |
380
381| Miscellaneous | |
382|-----------------------------------------------+-----------|
383| Refresh File (e.g., after recompiling source) | ~g~ |
384| Print File | ~C-c C-p~ |
385
386# Local Variables:
387# mode: org
388# End:
389
README.org
1#+TITLE: PDF Tools README
2#+AUTHOR: Andreas Politz
3#+EMAIL: politza@fh-trier.de
4#+Maintainer: Vedang Manerikar
5#+Maintainer_Email: vedang.manerikar@gmail.com
6
7[[https://app.circleci.com/pipelines/github/vedang/pdf-tools][https://circleci.com/gh/vedang/pdf-tools.svg?style=svg]]
8[[https://stable.melpa.org/#/pdf-tools][http://stable.melpa.org/packages/pdf-tools-badge.svg]]
9[[https://melpa.org/#/pdf-tools][http://melpa.org/packages/pdf-tools-badge.svg]] [[https://ci.appveyor.com/project/vedang/pdf-tools][https://ci.appveyor.com/api/projects/status/yqic2san0wi7o5v8/branch/master?svg=true]]
10
11** About this package
12 PDF Tools is, among other things, a replacement of DocView for PDF
13 files. The key difference is that pages are not pre-rendered by
14 e.g. ghostscript and stored in the file-system, but rather created
15 on-demand and stored in memory.
16
17 This rendering is performed by a special library named, for
18 whatever reason, poppler, running inside a server program. This
19 program is called ~epdfinfo~ and its job is to successively
20 read requests from Emacs and produce the proper results, i.e. the
21 PNG image of a PDF page.
22
23 Actually, displaying PDF files is just one part of PDF Tools.
24 Since poppler can provide us with all kinds of information about a
25 document and is also able to modify it, there is a lot more we can
26 do with it. [[http://www.dailymotion.com/video/x2bc1is_pdf-tools-tourdeforce_tech?forcedQuality%3Dhd720][Watch]]
27
28 Please read also about [[#known-problems][known problems.]]
29
30** Features
31 + View :: View PDF documents in a buffer with DocView-like
32 bindings.
33 + Isearch :: Interactively search PDF documents like any other
34 buffer, either for a string or a PCRE.
35 + Occur :: List lines matching a string or regexp in one or more
36 PDF documents.
37 + Follow ::
38 Click on highlighted links, moving to some part of a different
39 page, some external file, a website or any other URI. Links may
40 also be followed by keyboard commands.
41 + Annotations :: Display and list text and markup annotations (like
42 underline), edit their contents and attributes
43 (e.g. color), move them around, delete them or
44 create new ones and then save the modifications
45 back to the PDF file.
46 + Attachments :: Save files attached to the PDF-file or list them
47 in a dired buffer.
48 + Outline :: Use imenu or a special buffer to examine and navigate
49 the PDF's outline.
50 + SyncTeX :: Jump from a position on a page directly to the TeX
51 source and vice versa.
52 + Virtual ::
53 Use a collection of documents as if it were one, big single PDF.
54
55 + Misc ::
56 - Display PDF's metadata.
57 - Mark a region and kill the text from the PDF.
58 - Keep track of visited pages via a history.
59 - Apply a color filter for reading in low light conditions.
60
61** Installation
62 The package may be installed via MELPA and it will try to build the
63 server part when it is activated the first time. Though the next
64 section regarding build-prerequisites is still relevant, the rest
65 of the installation instructions assume a build from within a git
66 repository. (The MELPA package has a different directory
67 structure.)
68
69*** Server prerequisites
70 You'll need GNU Emacs \ge 24.3 and some form of a GNU/Linux OS.
71 Other operating systems are currently not supported (patches
72 welcome). The following instructions assume a Debian-based
73 system. (The prerequisites may be installed automatically on this
74 kind of systems, see [[#compilation][Compilation]] .)
75
76 First make sure a suitable build-system is installed. We need at
77 least a C/C++ compiler (both ~gcc~ and ~g++~), ~make~, ~automake~
78 and ~autoconf~.
79
80 Next we need to install a few libraries PDF Tools depends on, some
81 of which are probably already on your system.
82#+begin_src sh
83 $ sudo aptitude install libpng-dev zlib1g-dev
84 $ sudo aptitude install libpoppler-glib-dev
85 $ sudo aptitude install libpoppler-private-dev
86#+end_src
87 On some older Ubuntu systems, the final command will possibly give
88 an error. This should be no problem, since in some versions this
89 package was contained in the main package ~libpoppler-dev~. Also
90 note, that ~zlib1g-dev~ was for a long time called ~libz-dev~,
91 which it still may be on your system.
92
93 Debian wheezy comes with libpoppler version 0.18, which is pretty
94 old. The minimally required version is 0.16, but some features of
95 PDF Tools depend on a more recent version of this library. See
96 the following table for what they are and what version they
97 require.
98
99 | You want to ... | Required version |
100 |-------------------------------------------+------------------|
101 | ... create and modify text annotations. | \ge 0.19.4 |
102 | ... search case-sensitive. | \ge 0.22 |
103 | ... create and modify markup annotations. | \ge 0.26 |
104 |-------------------------------------------+------------------|
105
106 In case you decide to install libpoppler from source, make sure
107 to run its configure script with the ~--enable-xpdf-headers~
108 option.
109
110 Finally there is one feature (following links of a PDF document by
111 plain keystrokes) which requires imagemagick's convert utility.
112 This requirement is optional and you may install it like so:
113#+begin_src sh
114 $ sudo aptitude install imagemagick
115#+end_src
116**** Compiling on macOS
117 Although macOS is not officially supported, it has been reported
118 to have been successfully compiled. You will need to install
119 poppler which you can get with Homebrew via
120#+BEGIN_SRC sh
121 $ brew install poppler automake
122#+END_SRC
123
124 You will also have to help ~pkg-config~ find some libraries by
125 setting ~PKG_CONFIG_PATH~, e.g.
126#+BEGIN_SRC sh
127 $ export PKG_CONFIG_PATH=/usr/local/Cellar/zlib/1.2.8/lib/pkgconfig:/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig
128#+END_SRC
129 or likewise within Emacs using `setenv`.
130
131 After that, compilation should proceed as normal.
132**** FreeBSD
133 Although not officially supported, it has been reported that
134 pdf-tools work well on FreeBSD. Instead of building pdf-tools, you
135 can install one of the OS packages with, e.g.
136#+BEGIN_SRC sh
137 $ pkg install pdf-tools-emacs26
138#+END_SRC
139 To see the current list of pdf-tools packages for FreeBSD visit
140 [[https://repology.org/metapackages/?search=pdf-tools&inrepo=freebsd][the Repology list]].
141
142 To build pdf-tools from either MELPA or directly from the source
143 repository, install the dependencies with
144#+BEGIN_SRC sh
145 $ pkg install autotools gmake poppler-glib
146#+END_SRC
147
148 If you choose not to install from MELPA, you must substitute
149 ~gmake~ for ~make~ in the instructions below.
150**** Compiling on CentOS
151 It is possible to compile pdf-tools on CentOS. Install poppler the dependencies with:
152#+BEGIN_SRC sh
153 $ yum install poppler-devel poppler-glib-devel
154#+END_SRC
155
156**** Compiling on Fedora
157#+BEGIN_SRC sh
158 $ sudo dnf install make automake autoconf gcc gcc-c++ ImageMagick libpng-devel zlib-devel poppler-glib-devel
159#+END_SRC
160
161**** Compiling on Alpine Linux
162#+BEGIN_SRC sh
163 $ apk add build-base g++ gcc automake autoconf libpng-dev glib-dev poppler-dev
164#+END_SRC
165
166**** Compiling on Windows
167 PDF Tools can be built and used on Windows using the MSYS2
168 compiler. This will work with native (not cygwin) Windows builds of
169 emacs. This includes the standard binaries provided by the GNU
170 project, those available as MSYS2 packages and numerous third-party
171 binaries. It has been tested with Emacs 25.1. Instructions are
172 provided under [[#compilation-and-installation-on-windows][Compilation and installation on Windows]], below.
173 PDF Tools will successfully compile using Cygwin, but it will not be
174 able to open PDFs properly due to the way binaries compiled with Cygwin
175 handle file paths.
176
177*** Compilation
178 :PROPERTIES:
179 :CUSTOM_ID: compilation
180 :END:
181 Now it's time to compile the source.
182#+begin_src sh
183 $ cd /path/to/pdf-tools
184 $ make install-server-deps # optional
185 $ make -s
186#+end_src
187 The ~make install-server-deps~ command will try to install all
188 necessary programs and libraries to build the package, though
189 it'll only work, if ~sudo~ and ~apt-get~ are available.
190
191 This should compile the source code and create a Emacs Lisp
192 Package in the root directory of the project. The configure script
193 also tells you at the very end, which features, depending on the
194 libpoppler version, will be available. These commands should give
195 no error, otherwise you are in trouble.
196**** Compilation and installation on Windows
197 :PROPERTIES:
198 :CUSTOM_ID: compilation-and-installation-on-windows
199 :END:
200 If using the GNU binaries for Windows, support for PNG and zlib
201 must first be installed by copying the appropriate dlls into
202 emacs' ~bin/~ directory. Most third-party binaries come with this
203 already done.
204
205 First, install [[http://www.msys2.org/][install MSYS2]] and update
206 the package database and core packages using the instructions
207 provided. Then, to compile PDF tools itself:
208
209 1. Open msys2 shell
210
211 2. Update and install dependencies, skipping any you already have
212 #+BEGIN_SRC sh
213 $ pacman -Syu
214 $ pacman -S base-devel
215 $ pacman -S mingw-w64-x86_64-toolchain
216 $ pacman -S mingw-w64-x86_64-zlib
217 $ pacman -S mingw-w64-x86_64-libpng
218 $ pacman -S mingw-w64-x86_64-poppler
219 $ pacman -S mingw-w64-x86_64-imagemagick
220 #+END_SRC
221
222 3. Install PDF tools in Emacs, but do not try to compile the
223 server. Instead, get a separate copy of the source somewhere
224 else.
225 #+BEGIN_SRC sh
226 $ git clone https://github.com/politza/pdf-tools
227 #+END_SRC
228
229 4. Open ~mingw64~ shell (*Note:* You must use ~mingw64.exe~ and not ~msys2.exe~)
230
231 5. Compile pdf-tools
232 #+BEGIN_SRC sh
233 $ cd /path/to/pdf-tools
234 $ make -s
235 #+END_SRC
236
237 6. This should produce a file ~server/epdfinfo.exe~. Copy this file
238 into the ~pdf-tools/~ installation directory in your Emacs.
239
240 7. Start Emacs and activate the package.
241 #+BEGIN_SRC
242 M-x pdf-tools-install RET
243 #+END_SRC
244
245 8. Test.
246 #+BEGIN_SRC
247 M-x pdf-info-check-epdfinfo RET
248 #+END_SRC
249
250 If this is successful, ~(pdf-tools-install)~ can be added to Emacs'
251 config. Note that libraries from other GNU utilities, such as Git
252 for Windows, may interfere with those needed by PDF Tools.
253 ~pdf-info-check-epdinfo~ will succeed, but errors occur when trying
254 to view a PDF file. This can be fixed by ensuring that the MSYS
255 libraries are always preferred in Emacs:
256
257 #+BEGIN_SRC emacs-lisp
258 (setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv "PATH")))
259 #+END_SRC
260
261*** Elisp prerequisites
262 This package depends on the following Elisp packages, which should
263 be installed before installing the PDF Tools package.
264
265 | Package | Required version |
266 |-----------+----------------------------------|
267 | [[https://elpa.gnu.org/packages/let-alist.html][let-alist]] | >= 1.0.4 (comes with Emacs 25.2) |
268 | [[http://melpa.org/#/tablist][tablist]] | >= 0.70 |
269 |-----------+----------------------------------|
270
271*** Installing
272 If ~make~ produced the ELP file ~pdf-tools-${VERSION}.tar~ you are
273 fine. This package contains all the necessary files for Emacs
274 and may be installed by either using
275#+begin_src sh
276 $ make install-package
277#+end_src
278 or executing the Emacs command
279#+begin_src elisp
280 M-x package-install-file RET pdf-tools-${VERSION}.tar RET
281#+end_src
282
283 To complete the installation process, you need to activate the
284 package by putting
285#+begin_src elisp
286 (pdf-tools-install)
287#+end_src
288 somewhere in your ~.emacs~. Alternatively, and if you care about
289 start-up time, you may want to use
290#+begin_src elisp
291 (pdf-loader-install)
292#+end_src
293 instead. Next you probably want to take a look at the various
294 features of what you've just installed. The following two commands
295 might be of help for doing so.
296#+begin_src elisp
297 M-x pdf-tools-help RET
298 M-x pdf-tools-customize RET
299#+end_src
300
301*** Updating
302 Some day you might want to update this package via ~git pull~ and
303 then reinstall it. Sometimes this may fail, especially if
304 Lisp-Macros are involved and the version hasn't changed. To avoid
305 this kind of problems, you should delete the old package via
306 ~list-packages~, restart Emacs and then reinstall the package.
307
308 This also applies when updating via package and MELPA.
309
310** Known problems
311 :PROPERTIES:
312 :CUSTOM_ID: known-problems
313 :END:
314
315*** linum-mode
316 PDF Tools does not work well together with ~linum-mode~ and
317 activating it in a ~pdf-view-mode~, e.g. via ~global-linum-mode~,
318 might make Emacs choke.
319
320*** auto-revert
321 Autorevert works by polling the file-system every
322 ~auto-revert-interval~ seconds, optionally combined with some
323 event-based reverting via [[https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html][file notification]]. But this currently
324 does not work reliably, such that Emacs may revert the PDF-buffer
325 while the corresponding file is still being written to (e.g. by
326 LaTeX), leading to a potential error.
327
328 With a recent [[https://www.gnu.org/software/auctex/][AUCTeX]] installation, you might want to put the
329 following somewhere in your dotemacs, which will revert the PDF-buffer
330 *after* the TeX compilation has finished.
331#+BEGIN_SRC emacs-lisp
332 (add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer)
333#+END_SRC
334
335*** sublimity
336 L/R scrolling breaks while zoomed into a pdf, with usage of sublimity smooth scrolling features
337
338** Some keybindings
339
340| Navigation | |
341|--------------------------------------------+-----------------------|
342| Scroll Up / Down by Page-full | ~space~ / ~backspace~ |
343| Scroll Up / Down by Line | ~C-n~ / ~C-p~ |
344| Scroll Right / Left | ~C-f~ / ~C-b~ |
345| Top of Page / Bottom of Page | ~<~ / ~>~ |
346| Next Page / Previous Page | ~n~ / ~p~ |
347| First Page / Last Page | ~M-<~ / ~M->~ |
348| Incremental Search Forward / Backward | ~C-s~ / ~C-r~ |
349| Occur (list all lines containing a phrase) | ~M-s o~ |
350| Jump to Occur Line | ~RETURN~ |
351| Pick a Link and Jump | ~F~ |
352| Incremental Search in Links | ~f~ |
353| History Back / Forwards | ~B~ / ~N~ |
354| Display Outline | ~o~ |
355| Jump to Section from Outline | ~RETURN~ |
356| Jump to Page | ~M-g g~ |
357
358| Display | |
359|------------------------------------------+-----------------|
360| Zoom in / Zoom out | ~+~ / ~-~ |
361| Fit Height / Fit Width / Fit Page | ~H~ / ~W~ / ~P~ |
362| Trim Margins (set slice to bounding box) | ~s b~ |
363| Reset Margins | ~s r~ |
364| Reset Zoom | 0 |
365
366| Annotations | |
367|-------------------------------+-------------------------------------------------|
368| List Annotations | ~C-c C-a l~ |
369| Jump to Annotations from List | ~SPACE~ |
370| Mark Annotation for Deletion | ~d~ |
371| Delete Marked Annotations | ~x~ |
372| Unmark Annotations | ~u~ |
373| Close Annotation List | ~q~ |
374| Add and Edit Annotations | via Mouse selection and left-click context menu |
375
376| Syncing with AUCTeX | |
377|----------------------------------+-------------|
378| Jump to PDF Location from Source | ~C-c C-g~ |
379| Jump Source Location from PDF | ~C-mouse-1~ |
380
381| Miscellaneous | |
382|-----------------------------------------------+-----------|
383| Refresh File (e.g., after recompiling source) | ~g~ |
384| Print File | ~C-c C-p~ |
385
386# Local Variables:
387# mode: org
388# End:
389