README-elpa (39634B)
1 ━━━━━━━━━━━━━━━━━━ 2 PDF TOOLS README 3 ━━━━━━━━━━━━━━━━━━ 4 5 6 [https://circleci.com/gh/vedang/pdf-tools.svg?style=svg] 7 [http://elpa.nongnu.org/nongnu/pdf-tools.svg] 8 [http://stable.melpa.org/packages/pdf-tools-badge.svg] 9 [http://melpa.org/packages/pdf-tools-badge.svg] 10 [https://ci.appveyor.com/api/projects/status/yqic2san0wi7o5v8/branch/master?svg=true] 11 12 The `pdf-tools' Wiki is maintained at <https://pdftools.wiki>. Head to 13 the site if you find it easier to navigate a website for reading a 14 manual. All the topics on the site are listed at 15 <https://pdftools.wiki/impulse>. 16 17 18 [https://circleci.com/gh/vedang/pdf-tools.svg?style=svg] 19 <https://app.circleci.com/pipelines/github/vedang/pdf-tools> 20 21 [http://elpa.nongnu.org/nongnu/pdf-tools.svg] 22 <https://elpa.nongnu.org/nongnu/pdf-tools.html> 23 24 [http://stable.melpa.org/packages/pdf-tools-badge.svg] 25 <https://stable.melpa.org/#/pdf-tools> 26 27 [http://melpa.org/packages/pdf-tools-badge.svg] 28 <https://melpa.org/#/pdf-tools> 29 30 [https://ci.appveyor.com/api/projects/status/yqic2san0wi7o5v8/branch/master?svg=true] 31 <https://ci.appveyor.com/project/vedang/pdf-tools> 32 33 34 1 About PDF Tools 35 ═════════════════ 36 37 PDF Tools is, among other things, a replacement of DocView for PDF 38 files. The key difference is that pages are not pre-rendered by, say, 39 `ghostscript' and stored in the file-system, but rather created 40 on-demand and stored in memory. 41 42 This rendering is performed by a special library named, for whatever 43 reason, `poppler', running inside a server program. This program is 44 called `epdfinfo' and its job is to successively read requests from 45 Emacs and produce the proper results, i.e. the PNG image of a PDF 46 page. 47 48 Actually, displaying PDF files is just one part of `pdf-tools'. Since 49 `poppler' can provide us with all kinds of information about a 50 document and is also able to modify it, there is a lot more we can do 51 with it. [Watch this video for a detailed demo!] 52 53 54 [Watch this video for a detailed demo!] 55 <https://www.dailymotion.com/video/x2bc1is> 56 57 58 2 Installing pdf-tools 59 ══════════════════════ 60 61 Installing this package via NonGNU ELPA or MELPA or any of the other 62 package managers is straightforward and should just work! You should 63 not require any manual changes. The documentation below is *only if 64 you are installing from source*, or for troubleshooting / debugging 65 purposes. 66 67 `pdf-tools' requires a server `epdfinfo' to run against, which it will 68 try to compile and build when it is activated for the first time. The 69 following steps need to be followed *in this order*, to install 70 `pdf-tools' and `epdfinfo' correctly: 71 72 • 73 • 74 75 76 2.1 Installing the epdfinfo server 77 ────────────────────────────────── 78 79 If you install `pdf-tools' via NonGNU ELPA or MELPA, *you don't need 80 to worry about this separate server installation at all*. 81 82 Note: You'll need GNU Emacs ≥ 26.3 and some form of a GNU/Linux 83 OS. Other operating systems are not officially supported, but 84 `pdf-tools' is known to work on many of them. 85 86 The `epdfinfo' install script takes care of installing all the 87 necessary pre-requisites on supported operating systems (see list 88 below). See the section on to learn how to add your favorite Operating 89 System to this list. 90 91 Similarly, package-managers are not officially supported, but 92 `pdf-tools' is known to be available on some of them. See the section 93 on to avoid manual installation of server / server prerequisites. 94 95 Installation Instructions for `epdfinfo': 96 ┌──── 97 │ $ git clone https://github.com/vedang/pdf-tools 98 │ $ cd /path/to/pdf-tools 99 │ $ make -s # If you don't have make installed, run ./server/autobuild and it will install make 100 └──── 101 102 This should give you no error and should compile the `epdfinfo' 103 server. If you face a problem, please report on the issue tracker! 104 105 The following Operating Systems / package managers are 106 supported. *Note*: The package manager used to install pre-requisites 107 should be installed on your OS for the script to work: 108 109 • Debian-based systems (`debian', `ubuntu'): `apt-get' 110 • Fedora: `dnf' 111 • macOS: `brew' 112 • Windows (MSYS2/ MingW): `pacman' 113 • NixOS: `nix-shell' 114 • openSUSE (Tumbleweed and Leap): `zypper' 115 • Void Linux: `xbps-install' 116 • Apline Linux: `apk' 117 • FreeBSD: `pkg' 118 • OpenBSD: `pkg_add' 119 • NetBSD: `pkgin' 120 • Arch Linux: `pacman' 121 • Gentoo: `emerge' 122 • CentOS: `yum' 123 124 125 2.1.1 Installing the epdfinfo server from package managers 126 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 127 128 `pdf-tools' can be directly installed from the package manager on some 129 operating systems. Note that the packages available on these package 130 managers are not maintained by the author and might be outdated. 131 132 • Debian: <https://packages.debian.org/buster/elpa-pdf-tools-server> 133 • Ubuntu: <https://packages.ubuntu.com/impish/elpa-pdf-tools-server> 134 • MSYS2 / MINGW (Windows): 135 <https://packages.msys2.org/package/mingw-w64-x86_64-emacs-pdf-tools-server?repo=mingw64> 136 • FreeBSD: 137 <https://repology.org/metapackages/?search=pdf-tools&inrepo=freebsd> 138 139 140 2.1.2 Installing the epdfinfo server from source on Windows (+ Gotchas) 141 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 142 143 If using the GNU binaries for Windows, support for PNG and `zlib' must 144 first be installed by copying the appropriate dlls into emacs' `bin/' 145 directory. Most third-party binaries come with this already done. 146 147 1. [install MSYS2] and update the package database and core packages 148 using the instructions provided. 149 2. Open `mingw64' shell (*Note:* You must use `mingw64.exe' and not 150 `msys2.exe') 151 3. Compile the `epdfinfo' server using Installation steps described in 152 4. This should produce a file `server/epdfinfo.exe'. Copy this file 153 into the `pdf-tools/' installation directory in your Emacs. 154 5. Make sure Emacs can find `epdfinfo.exe'. Either add the MINGW 155 install location (e.g. `C:/msys2/mingw64/bin') to the system path 156 with `setx PATH "C:\msys2\mingw64\bin;%PATH%"' or set Emacs's path 157 with `(setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv 158 "PATH")))'. Note that libraries from other GNU utilities, such as 159 Git for Windows, may interfere with those needed by 160 `pdf-tools'. `pdf-info-check-epdinfo' will succeed, but errors 161 occur when trying to view a PDF file. This can be fixed by ensuring 162 that the MSYS libraries are always preferred. 163 6. `pdf-tools' will successfully compile using Cygwin, but it will not 164 be able to open PDFs properly due to the way binaries compiled with 165 Cygwin handle file paths. Please use MSYS2. 166 167 168 [install MSYS2] <https://www.msys2.org/> 169 170 171 2.1.3 Installing the epdfinfo server from source on macOS (+ Gotchas) 172 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 173 174 On macOS, `autobuild' adjusts `PKG_CONFIG_PATH' so that `pdf-tools' 175 can find some of the keg-only packages installed by `brew'. It is 176 recommended that you review the output logs printed by `brew' during 177 the installation process to also export the relevant paths to the 178 appropriate ENV variables. 179 180 181 2.1.4 Common installation gotchas 182 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 183 184 In case you decide to install `libpoppler' from source, make sure to 185 run its configure script with the `--enable-xpdf-headers' option. 186 187 188 2.1.5 Installing optional features 189 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 190 191 One feature – following links of a PDF document by plain keystrokes – 192 requires `imagemagick''s convert utility. This requirement is 193 optional, the installation process will detect if you have 194 `imagemagick' installed or not. 195 196 197 2.2 Installing pdf-tools elisp code 198 ─────────────────────────────────── 199 200 `pdf-tools' requires `tablist' package (>= version 0.70) to be 201 installed, for it to work correctly. Please make sure that the latest 202 version of `tablist' is installed. 203 204 We have already run the steps necessary to install `pdf-tools' as part 205 of ! These are: 206 ┌──── 207 │ $ git clone https://github.com/vedang/pdf-tools 208 │ $ cd /path/to/pdf-tools 209 │ $ make -s 210 └──── 211 212 If the `make' command produced the ELP file `pdf-tools-${VERSION}.tar' 213 you are fine! This package contains all the necessary files for Emacs 214 and may be installed by either using 215 ┌──── 216 │ $ make install-package 217 └──── 218 or executing the Emacs command 219 ┌──── 220 │ M-x package-install-file RET pdf-tools-${VERSION}.tar RET 221 └──── 222 223 You can test if the package has been installed correctly, by running 224 ┌──── 225 │ M-x pdf-info-check-epdfinfo RET 226 └──── 227 228 To complete the installation process, you need to activate the package 229 by putting the code below somewhere in your `.emacs'. Alternatively, 230 and if you care about startup time, you may want to use the loader 231 version instead. 232 ┌──── 233 │ (pdf-tools-install) ; Standard activation command 234 │ (pdf-loader-install) ; On demand loading, leads to faster startup time 235 └──── 236 237 Once the Installation process is complete, check out and to get 238 started! 239 240 241 2.3 Updating pdf-tools 242 ────────────────────── 243 244 Some day you might want to update this package via `git pull' and then 245 reinstall it. Sometimes this may fail, especially if Lisp-Macros are 246 involved and the version hasn't changed. To avoid this kind of 247 problems, you should delete the old package via `list-packages', 248 restart Emacs, run `make distclean' and then reinstall the 249 package. Follow the steps described in . 250 251 This also applies when updating via MELPA / NonGNU ELPA (except for 252 running the `make distclean' step). 253 254 255 3 Features 256 ══════════ 257 258 View 259 View PDF documents in a buffer with DocView-like bindings. . 260 Isearch 261 Interactively search PDF documents like any other buffer, either 262 for a string or a PCRE. 263 Occur 264 List lines matching a string or regexp in one or more PDF 265 documents. 266 Follow 267 Click on highlighted links, moving to some part of a different 268 page, some external file, a website or any other URI. Links may 269 also be followed by keyboard commands. 270 Annotations 271 Display and list text and markup annotations (like underline), 272 edit their contents and attributes (e.g. color), move them 273 around, delete them or create new ones and then save the 274 modifications back to the PDF file. . 275 Attachments 276 Save files attached to the PDF-file or list them in a dired 277 buffer. 278 Outline 279 Use `imenu' or a special buffer (`M-x pdf-outline') to examine 280 and navigate the PDF's outline. 281 SyncTeX 282 Jump from a position on a page directly to the TeX source and 283 vice versa. 284 Virtual 285 Use a collection of documents as if it were one, big single PDF. 286 Misc 287 • Display PDF's metadata. 288 • Mark a region and kill the text from the PDF. 289 • Keep track of visited pages via a history. 290 • Apply a color filter for reading in low light conditions. 291 292 293 3.1 View and Navigate PDFs 294 ────────────────────────── 295 296 PDFView Mode is an Emacs PDF viewer. It displays PDF files as PNG 297 images in Emacs buffers. PDFs are navigable using DocView-like 298 bindings. Once you have installed `pdf-tools', opening a PDF in Emacs 299 will automatically trigger this mode. 300 301 302 3.1.1 Keybindings for navigating PDF documents 303 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 304 305 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 306 Navigation 307 ──────────────────────────────────────────────────────────────────────── 308 Scroll Up / Down by Page-full `space' / `backspace' 309 Scroll Up / Down by Line `C-n' / `C-p' 310 Scroll Right / Left `C-f' / `C-b' 311 First Page / Last Page `<', `M-<' / `>', `M->' 312 Next Page / Previous Page `n' / `p' 313 Incremental Search Forward / Backward `C-s' / `C-r' 314 Occur (list all lines containing a phrase) `M-s o' 315 Jump to Occur Line `RETURN' 316 Pick a Link and Jump `F' 317 Incremental Search in Links `f' 318 History Back / Forwards `l' / `r' 319 Display Outline `o' 320 Jump to Section from Outline `RETURN' 321 Jump to Page `M-g g' 322 Store position / Jump to position in register `m' / `'' 323 ──────────────────────────────────────────────────────────────────────── 324 325 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 326 Note that `pdf-tools' renders the PDF as images inside Emacs. This 327 means that all the keybindings of `image-mode' work on individual PDF 328 pages as well. 329 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 330 Image Mode 331 ───────────────────────────────────────────────────────────────────── 332 image-scroll-right `C-x >' / `<remap> <scroll-right>' 333 image-scroll-left `C-x <' / `<remap> <scroll-left>' 334 image-scroll-up `C-v' / `<remap> <scroll-up>' 335 image-scroll-down `M-v' / `<remap> <scroll-down>' 336 image-forward-hscroll `C-f' / `right' / `<remap> <forward-char>' 337 image-backward-hscroll `C-b' / `left' / `<remap> <backward-char>' 338 image-bob `<remap> <beginning-of-buffer>' 339 image-eob `<remap> <end-of-buffer>' 340 image-bol `<remap> <move-beginning-of-line>' 341 image-eol `<remap> <move-end-of-line>' 342 image-scroll-down `<remap> <scroll-down>' 343 image-scroll-up `<remap> <scroll-up>' 344 image-scroll-left `<remap> <scroll-left>' 345 image-scroll-right `<remap> <scroll-right>' 346 ───────────────────────────────────────────────────────────────────── 347 348 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 349 350 351 3.1.2 Keybindings for manipulating display of PDF 352 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 353 354 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 355 Display 356 ─────────────────────────────────────────────────────────── 357 Zoom in / Zoom out `+' / `-' 358 Fit Height / Fit Width / Fit Page `H' / `W' / `P' 359 Trim Margins (set slice to bounding box) `s b' 360 Reset Margins `s r' 361 Reset Zoom `0' 362 Rotate Page `R' 363 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 364 365 366 3.2 Annotations 367 ─────────────── 368 369 `pdf-tools' supports working with PDF Annotations. You can display and 370 list text and markup annotations (like squiggly, highlight), edit 371 their contents and attributes (e.g. color), move them around, delete 372 them or create new ones and then save the modifications back to the 373 PDF file. 374 375 376 3.2.1 Keybindings for working with Annotations 377 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 378 379 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 380 Annotations 381 ───────────────────────────────────────────────────────────────────────────────────────── 382 List Annotations `C-c C-a l' 383 Jump to Annotations from List `SPACE' 384 Mark Annotation for Deletion `d' 385 Delete Marked Annotations `x' 386 Unmark Annotations `u' 387 Close Annotation List `q' 388 Enable/Disable Following Annotations `C-c C-f' 389 ───────────────────────────────────────────────────────────────────────────────────────── 390 Add and Edit Annotations Select region via Mouse selection. 391 Then left-click context menu OR keybindings below 392 ───────────────────────────────────────────────────────────────────────────────────────── 393 Add a Markup Annotation `C-c C-a m' 394 Add a Highlight Markup Annotation `C-c C-a h' 395 Add a Strikeout Markup Annotation `C-c C-a o' 396 Add a Squiggly Markup Annotation `C-c C-a s' 397 Add an Underline Markup Annotation `C-c C-a u' 398 Add a Text Annotation `C-c C-a t' 399 ───────────────────────────────────────────────────────────────────────────────────────── 400 401 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 402 403 404 3.3 Working with AUCTeX 405 ─────────────────────── 406 407 3.3.1 Keybindings for working with AUCTeX 408 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 409 410 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 411 Syncing with AUCTeX 412 ──────────────────────────────────────────────────────────── 413 Refresh File (e.g., after recompiling source) `g' 414 Jump to PDF Location from Source `C-c C-g' 415 Jump Source Location from PDF `C-mouse-1' 416 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 417 418 419 3.4 Miscellaneous features 420 ────────────────────────── 421 422 3.4.1 Keybindings for miscellaneous features in PDF tools 423 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 424 425 ━━━━━━━━━━━━━━━━━━━━━━━━━━ 426 Miscellaneous 427 ────────────────────────── 428 Print File `C-c C-p' 429 ━━━━━━━━━━━━━━━━━━━━━━━━━━ 430 431 432 3.5 Easy Help for PDF Tools features 433 ──────────────────────────────────── 434 435 ┌──── 436 │ M-x pdf-tools-help RET 437 └──── 438 439 Run `M-x pdf-tools-help' inside Emacs, as shown above. It will list 440 all the features provided by `pdf-tools' as well as the key-bindings 441 for these features. 442 443 444 3.6 Configuring PDF Tools features 445 ────────────────────────────────── 446 447 Once you have read through the features provided by `pdf-tools', you 448 probably want to customize the behavior of the features as per your 449 requirements. Full customization of features is available by running 450 the following: 451 ┌──── 452 │ M-x pdf-tools-customize RET 453 └──── 454 455 456 4 Known problems 457 ════════════════ 458 459 4.1 linum-mode 460 ────────────── 461 462 `pdf-tools' does not work well together with `linum-mode' and 463 activating it in a `pdf-view-mode', e.g. via `global-linum-mode', 464 might make Emacs choke. 465 466 467 4.2 display-line-numbers-mode 468 ───────────────────────────── 469 470 This mode is an alternative to `linum-mode' and is available since 471 Emacs 26. `pdf-tools' does not work well with it. For example, it 472 makes horizontal navigation (such as `C-f', `C-b', `C-x <' or `C-x >' 473 ) in a document impossible. 474 475 476 4.3 auto-revert 477 ─────────────── 478 479 Autorevert works by polling the file-system every 480 `auto-revert-interval' seconds, optionally combined with some 481 event-based reverting via [file notification]. But this currently does 482 not work reliably, such that Emacs may revert the PDF-buffer while the 483 corresponding file is still being written to (e.g. by LaTeX), leading 484 to a potential error. 485 486 With a recent [AUCTeX] installation, you might want to put the 487 following somewhere in your dotemacs, which will revert the PDF-buffer 488 *after* the TeX compilation has finished. 489 ┌──── 490 │ (add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer) 491 └──── 492 493 494 [file notification] 495 <https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html> 496 497 [AUCTeX] <https://www.gnu.org/software/auctex/> 498 499 500 4.4 sublimity 501 ───────────── 502 503 L/R scrolling breaks while zoomed into a pdf, with usage of sublimity 504 smooth scrolling features 505 506 507 4.5 Text selection is not transparent in PDFs OCRed with Tesseract 508 ────────────────────────────────────────────────────────────────── 509 510 In such PDFs the selected text becomes hidden behind the selection; 511 see [this issue], which also describes the workaround in detail. The 512 following function, which depends on the [qpdf.el] package, can be 513 used to convert such a PDF file into one where text selection is 514 transparent: 515 ┌──── 516 │ (defun my-fix-pdf-selection () 517 │ "Replace pdf with one where selection shows transparently." 518 │ (interactive) 519 │ (unless (equal (file-name-extension (buffer-file-name)) "pdf") 520 │ (error "Buffer should visit a pdf file.")) 521 │ (unless (equal major-mode 'pdf-view-mode) 522 │ (pdf-view-mode)) 523 │ ;; save file in QDF-mode 524 │ (qpdf-run (list 525 │ (concat "--infile=" 526 │ (buffer-file-name)) 527 │ "--qdf --object-streams=disable" 528 │ "--replace-input")) 529 │ ;; do replacements 530 │ (text-mode) 531 │ (read-only-mode -1) 532 │ (while (re-search-forward "3 Tr" nil t) 533 │ (replace-match "7 Tr" nil nil)) 534 │ (save-buffer) 535 │ (pdf-view-mode)) 536 └──── 537 Note that this overwrites the PDF file visited in the buffer from 538 which it is run! To avoid this replace the `--replace-input' with 539 `(concat "--outfile=" (file-truename (read-file-name "Outfile: ")))'. 540 541 542 [this issue] <https://github.com/vedang/pdf-tools/issues/149> 543 544 [qpdf.el] <https://github.com/orgtre/qpdf.el> 545 546 547 5 Key-bindings in PDF Tools 548 ═══════════════════════════ 549 550 • 551 • 552 • 553 • 554 • 555 556 557 6 Tips and Tricks for Developers 558 ════════════════════════════════ 559 560 6.1 Turn on debug mode 561 ────────────────────── 562 563 ┌──── 564 │ M-x pdf-tools-toggle-debug RET 565 └──── 566 Toggling debug mode prints information about various operations in the 567 `*Messages*' buffer, and this is useful to see what is happening 568 behind the scenes 569 570 571 6.2 Run Emacs lisp tests locally 572 ──────────────────────────────── 573 574 You can go to the `pdf-tools' folder and run `make test' to run the 575 ERT tests and check if the changes you have made to the code break any 576 of the tests. 577 578 The tests are written in ERT, which is the built-in testing system in 579 Emacs. However, they are run using `Cask' which you will have to 580 install first, if you don't have it already. You can install `Cask' by 581 following the instructions on their site at 582 <https://github.com/cask/cask> 583 584 585 6.3 Run server compilation tests locally 586 ──────────────────────────────────────── 587 588 You can go to the `pdf-tools' folder and run `make server-test' to 589 check if the changes you have made to the server code break 590 compilation on any of the supported operating systems. 591 592 The tests build `Podman' images for all supported operating systems, 593 so you will have to install `Podman' first, if you don't have 594 already. You can install `Podman' by following the instructions on 595 their site at <https://podman.io/getting-started/installation> 596 597 Podman is compatible with Docker, so if you already have `docker' 598 installed, you should be able to `alias podman=docker' on your shell 599 and run the tests, without having to install Docker. (Note: I have not 600 tested this) 601 602 603 6.4 Add a Dockerfile to automate server compilation testing 604 ─────────────────────────────────────────────────────────── 605 606 The `server/test/docker' folder contains Dockerfile templates used for 607 testing that the `epdfinfo' server compiles correctly on various 608 operating systems (). 609 610 To see the list of operating systems where compilation testing is 611 supported, run `make server-test-supported'. To see the list of 612 operating systems where testing is unsupported, run `make 613 server-test-unsupported'. To add support, look into the 614 `server/test/docker/templates' folder (`ubuntu' files are a good 615 example to refer to) 616 617 618 6.5 Issue Template for Bug Reports 619 ────────────────────────────────── 620 621 Please use the 'Bug Report' issue template when reporting bugs. The 622 template is as follows: 623 624 625 6.5.1 Describe the bug 626 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 627 628 A clear and concise description of what the bug is. 629 630 631 6.5.2 Steps To Reproduce the behaviour: 632 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 633 634 1. Go to '…' 635 2. Click on '….' 636 3. Scroll down to '….' 637 4. See error 638 639 640 6.5.3 What is the expected behaviour? 641 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 642 643 A clear and concise description of what you expected to happen. 644 645 646 6.5.4 Desktop 647 ╌╌╌╌╌╌╌╌╌╌╌╌╌ 648 649 Please complete the following information: 650 651 • OS: [eg: MacOS Catalina] 652 • Emacs Version: [This should be the output of `M-x emacs-version' ] 653 • Poppler Version: [eg: output of `brew info poppler' and similarly 654 for other OSs] 655 656 657 6.5.5 Your pdf-tools install 658 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 659 660 Please complete the following information: 661 • `pdf-tools' Version: [ `M-x package-list-packages' -> Search for 662 `pdf-tools' -> Hit Enter and copy all the details that pop up in the 663 Help buffer] 664 • `pdf-tools' customization / configuration that you use: 665 666 667 6.5.6 Additional context 668 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ 669 670 • If you are reporting a crash, please try and add the Backtrace / 671 Stacktrace of the crash. 672 • If you are reporting a bug, please try and attach an example PDF 673 file where I can reproduce the bug. 674 • If you can attach screenshots or recordings, that is a great help 675 • Please try reproducing the bug yourself on Vanilla Emacs before 676 reporting the problem. 677 678 679 7 FAQs 680 ══════ 681 682 7.1 PDFs are not rendering well! 683 ──────────────────────────────── 684 685 `pdf-tools' version `1.1.0' release changed the default value of 686 `pdf-view-use-scaling' to `t' (previously, it was `nil'). This has 687 been done keeping in mind that most modern monitors are HiDPI screens, 688 so the default configuration should cater to this user. If you are not 689 using a HiDPI screen, you might have to change this value to `nil' in 690 your configuration 691 692 ┌──── 693 │ (setq pdf-view-use-scaling nil) 694 └──── 695 696 to scale the images correctly when rendering them. 697 698 699 7.2 What Emacs versions does pdf-tools support? 700 ─────────────────────────────────────────────── 701 702 `pdf-tools' supports the 3 latest versions of Emacs major releases. At 703 the moment of this writing, this means that the minimum supported 704 Emacs version is `26.3'. 705 706 707 7.3 I want to add support for pdf-tools on "My Fav OS". How do I do that? 708 ───────────────────────────────────────────────────────────────────────── 709 710 I'm working on automating `pdf-tools' installation as much as 711 possible, in order to improve the installation experience. If you want 712 to add support for a new / currently unsupported Operating System, 713 please modify the `server/autobuild' script. Say you want to support a 714 new Operating System called MyFavOS. You need to do the following 715 work: 716 717 1. Search for the `Figure out where we are' section. Here, add a call 718 to `os_myfavos' right below `handle_options' at the end of the 719 existing call chain. Here we try and pick up the correct Operating 720 System and install the relevant dependencies. 721 2. Add handling for the `--os' argument in `os_argument' for 722 `myfavos', so that the appropriate function can be called to 723 install pre-requisites. `--os' is the argument that we pass to the 724 script from the command-line to indicate which OS we are on. 725 3. Create a `os_myfavos' function. This function checks if we are 726 running on MyFavOS. If we are running on MyFavOS, it sets up 727 `PKGCMD', `PKGARGS' and `PACKAGES' variables so that the 728 appropriate package manager can install the dependencies as part of 729 the rest of the `autobuild' script. 730 4. If you are adding support for your favorite operating system, 731 consider adding automated testing support as well, to help me 732 ensure that `epdfinfo' continues to compile correctly. See for more 733 details. 734 735 The idea here is to make the `server/autobuild' file the single place 736 from which installation can happen on any Operating System. This makes 737 building `pdf-tools' dead simple via the `Makefile'. 738 739 This seems like a lot of work, but it is not. If you need a reference, 740 search for `os_gentoo' or `os_debian' in the `server/autobuild' file 741 and see how these are setup and used. The functions are used to 742 install dependencies on Gentoo and Debian respectively, and are simple 743 to copy / change. 744 745 When you make your changes, please be sure to test as well as as 746 described in the linked articles. 747 748 749 7.4 I am on a Macbook M1 and pdf-tools installation fails with a stack-trace 750 ──────────────────────────────────────────────────────────────────────────── 751 752 There have been a number of issues around `pdf-tools' installation 753 problems on M1. `M-x pdf-tools-install' throws the following stack 754 trace: 755 ┌──── 756 │ 1 warning generated. 757 │ ld: warning: ignoring file /opt/homebrew/opt/gettext/lib/libintl.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64 758 │ ld: warning: ignoring file /opt/homebrew/Cellar/glib/2.72.1/lib/libglib-2.0.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64 759 │ ld: warning: ignoring file /opt/homebrew/Cellar/poppler/22.02.0/lib/libpoppler-glib.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64 760 │ ld: warning: ignoring file /opt/homebrew/Cellar/glib/2.72.1/lib/libgobject-2.0.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64 761 │ ld: warning: ignoring file /opt/homebrew/Cellar/poppler/22.02.0/lib/libpoppler.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64 762 │ ld: warning: ignoring file /opt/homebrew/Cellar/cairo/1.16.0_5/lib/libcairo.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64 763 │ ld: warning: ignoring file /opt/homebrew/Cellar/libpng/1.6.37/lib/libpng16.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64 764 │ ld: warning: ignoring file /opt/homebrew/Cellar/zlib/1.2.11/lib/libz.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64 765 │ Undefined symbols for architecture x86_64: 766 └──── 767 768 This happens because M1 architecture is `ARM64', whereas the Emacs App 769 you are using has been compiled for the `x86_64' architecture. The way 770 to solve this problem is to install a version of Emacs which has been 771 compiled for the M1. As of today, [2022-05-09 Mon], the latest version 772 of Emacs available on <https://emacsformacosx.com/> is natively 773 compiled and you will not face these issues on it. Please remove your 774 current Emacs App and install it from <https://emacsformacosx.com/>. 775 776 Thank you. 777 778 PS: How do I know if the Emacs I'm running has been compiled 779 correctly? 780 781 You can see this by opening the `Activity Monitor', selecting `Emacs', 782 clicking on the `Info' key, and then clicking on `Sample'. The `Code 783 Type' field in the Sample output will show you how your Application 784 has been compiled. Here is the output for EmacsForMacOSX (you can see 785 that it's `ARM64'): 786 ┌──── 787 │ Sampling process 61824 for 3 seconds with 1 millisecond of run time between samples 788 │ Sampling completed, processing symbols... 789 │ Analysis of sampling Emacs-arm64-11 (pid 61824) every 1 millisecond 790 │ Process: Emacs-arm64-11 [61824] 791 │ Path: /Applications/Emacs.app/Contents/MacOS/Emacs-arm64-11 792 │ Load Address: 0x1007f0000 793 │ Identifier: org.gnu.Emacs 794 │ Version: Version 28.1 (9.0) 795 │ Code Type: ARM64 796 │ Platform: macOS 797 └──── 798 799 If your Emacs is compiled for x86, the `Code Type' will be `x86_64'. 800 801 802 7.5 I am a developer, making changes to the pdf-tools source code 803 ───────────────────────────────────────────────────────────────── 804 805 Thank you for taking the time to contribute back to the code. You may 806 find some useful notes in the section. Please be sure to check it out!