README (39380B)
1 #+TITLE: PDF Tools README 2 #+AUTHOR: Andreas Politz 3 #+EMAIL: mail@andreas-politz.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://elpa.nongnu.org/nongnu/pdf-tools.html][http://elpa.nongnu.org/nongnu/pdf-tools.svg]] 9 [[https://stable.melpa.org/#/pdf-tools][http://stable.melpa.org/packages/pdf-tools-badge.svg]] 10 [[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]] 11 12 The ~pdf-tools~ Wiki is maintained at https://pdftools.wiki. Head to the site if you find it easier to navigate a website for reading a manual. All the topics on the site are listed at https://pdftools.wiki/impulse. 13 14 * Table of Contents :noexport:TOC_3_gh: 15 - [[#about-pdf-tools][About PDF Tools]] 16 - [[#installing-pdf-tools][Installing pdf-tools]] 17 - [[#installing-the-epdfinfo-server][Installing the epdfinfo server]] 18 - [[#installing-the-epdfinfo-server-from-package-managers][Installing the epdfinfo server from package managers]] 19 - [[#installing-the-epdfinfo-server-from-source-on-windows--gotchas][Installing the epdfinfo server from source on Windows (+ Gotchas)]] 20 - [[#installing-the-epdfinfo-server-from-source-on-macos--gotchas][Installing the epdfinfo server from source on macOS (+ Gotchas)]] 21 - [[#common-installation-gotchas][Common installation gotchas]] 22 - [[#installing-optional-features][Installing optional features]] 23 - [[#installing-pdf-tools-elisp-code][Installing pdf-tools elisp code]] 24 - [[#updating-pdf-tools][Updating pdf-tools]] 25 - [[#features][Features]] 26 - [[#view-and-navigate-pdfs][View and Navigate PDFs]] 27 - [[#keybindings-for-navigating-pdf-documents][Keybindings for navigating PDF documents]] 28 - [[#keybindings-for-manipulating-display-of-pdf][Keybindings for manipulating display of PDF]] 29 - [[#annotations][Annotations]] 30 - [[#keybindings-for-working-with-annotations][Keybindings for working with Annotations]] 31 - [[#working-with-auctex][Working with AUCTeX]] 32 - [[#keybindings-for-working-with-auctex][Keybindings for working with AUCTeX]] 33 - [[#miscellaneous-features][Miscellaneous features]] 34 - [[#keybindings-for-miscellaneous-features-in-pdf-tools][Keybindings for miscellaneous features in PDF tools]] 35 - [[#easy-help-for-pdf-tools-features][Easy Help for PDF Tools features]] 36 - [[#configuring-pdf-tools-features][Configuring PDF Tools features]] 37 - [[#known-problems][Known problems]] 38 - [[#linum-mode][linum-mode]] 39 - [[#display-line-numbers-mode][display-line-numbers-mode]] 40 - [[#auto-revert][auto-revert]] 41 - [[#sublimity][sublimity]] 42 - [[#text-selection-is-not-transparent-in-pdfs-ocred-with-tesseract][Text selection is not transparent in PDFs OCRed with Tesseract]] 43 - [[#key-bindings-in-pdf-tools][Key-bindings in PDF Tools]] 44 - [[#tips-and-tricks-for-developers][Tips and Tricks for Developers]] 45 - [[#turn-on-debug-mode][Turn on debug mode]] 46 - [[#run-emacs-lisp-tests-locally][Run Emacs lisp tests locally]] 47 - [[#run-server-compilation-tests-locally][Run server compilation tests locally]] 48 - [[#add-a-dockerfile-to-automate-server-compilation-testing][Add a Dockerfile to automate server compilation testing]] 49 - [[#issue-template-for-bug-reports][Issue Template for Bug Reports]] 50 - [[#describe-the-bug][Describe the bug]] 51 - [[#steps-to-reproduce-the-behaviour][Steps To Reproduce the behaviour:]] 52 - [[#what-is-the-expected-behaviour][What is the expected behaviour?]] 53 - [[#desktop][Desktop]] 54 - [[#your-pdf-tools-install][Your pdf-tools install]] 55 - [[#additional-context][Additional context]] 56 - [[#faqs][FAQs]] 57 - [[#pdfs-are-not-rendering-well][PDFs are not rendering well!]] 58 - [[#what-emacs-versions-does-pdf-tools-support][What Emacs versions does pdf-tools support?]] 59 - [[#i-want-to-add-support-for-pdf-tools-on-my-fav-os-how-do-i-do-that][I want to add support for pdf-tools on "My Fav OS". How do I do that?]] 60 - [[#i-am-on-a-macbook-m1-and-pdf-tools-installation-fails-with-a-stack-trace][I am on a Macbook M1 and pdf-tools installation fails with a stack-trace]] 61 - [[#i-am-a-developer-making-changes-to-the-pdf-tools-source-code][I am a developer, making changes to the pdf-tools source code]] 62 63 * About PDF Tools 64 :PROPERTIES: 65 :CREATED: [2021-12-29 Wed 18:34] 66 :ID: 5a884389-6aec-498a-90d5-f37168809b4f 67 :EXPORT_FILE_NAME: index 68 :END: 69 PDF Tools is, among other things, a replacement of DocView for PDF files. The key difference is that pages are not pre-rendered by, say, ~ghostscript~ and stored in the file-system, but rather created on-demand and stored in memory. 70 71 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. 72 73 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. [[https://www.dailymotion.com/video/x2bc1is][Watch this video for a detailed demo!]] 74 75 * Installing pdf-tools 76 :PROPERTIES: 77 :CREATED: [2021-12-29 Wed 18:34] 78 :ID: 6ceea50c-cbaa-4d8a-b450-8067c5e8c9da 79 :NEURON_DIRTREE_DISPLAY: false 80 :END: 81 Installing this package via NonGNU ELPA or MELPA or any of the other package managers is straightforward and should just work! You should not require any manual changes. The documentation below is *only if you are installing from source*, or for troubleshooting / debugging purposes. 82 83 ~pdf-tools~ requires a server ~epdfinfo~ to run against, which it will try to compile and build when it is activated for the first time. The following steps need to be followed *in this order*, to install ~pdf-tools~ and ~epdfinfo~ correctly: 84 85 - [[brain-child:e305cd0a-e798-4c2b-af27-21bcd936c1c9][Installing the epdfinfo server]] 86 - [[brain-child:32c4fc3b-b4ea-43bd-b92c-bdf2d3831fcf][Installing pdf-tools elisp code]] 87 88 ** Installing the epdfinfo server 89 :PROPERTIES: 90 :CREATED: [2021-12-29 Wed 18:34] 91 :ID: e305cd0a-e798-4c2b-af27-21bcd936c1c9 92 :END: 93 If you install ~pdf-tools~ via NonGNU ELPA or MELPA, *you don't need to worry about this separate server installation at all*. 94 95 Note: You'll need GNU Emacs \ge 26.3 and some form of a GNU/Linux OS. Other operating systems are not officially supported, but ~pdf-tools~ is known to work on many of them. 96 97 The ~epdfinfo~ install script takes care of installing all the necessary pre-requisites on supported operating systems (see list below). See the section on [[id:A34704B9-1B51-4614-8806-C4059F7B42D5][I want to add support for ~pdf-tools~ on =My Fav OS=. How do I do that?]] to learn how to add your favorite Operating System to this list. 98 99 Similarly, package-managers are not officially supported, but ~pdf-tools~ is known to be available on some of them. See the section on [[id:fb5cef15-fed4-4dec-a443-52f7c00c7831][Installing the ~epdfinfo~ server from package managers]] to avoid manual installation of server / server prerequisites. 100 101 Installation Instructions for ~epdfinfo~: 102 #+begin_src sh 103 $ git clone https://github.com/vedang/pdf-tools 104 $ cd /path/to/pdf-tools 105 $ make -s # If you don't have make installed, run ./server/autobuild and it will install make 106 #+end_src 107 108 This should give you no error and should compile the ~epdfinfo~ server. If you face a problem, please report on the issue tracker! 109 110 The following Operating Systems / package managers are supported. *Note*: The package manager used to install pre-requisites should be installed on your OS for the script to work: 111 112 - Debian-based systems (~debian~, ~ubuntu~): ~apt-get~ 113 - Fedora: ~dnf~ 114 - macOS: ~brew~ 115 - Windows (MSYS2/ MingW): ~pacman~ 116 - NixOS: ~nix-shell~ 117 - openSUSE (Tumbleweed and Leap): ~zypper~ 118 - Void Linux: ~xbps-install~ 119 - Apline Linux: ~apk~ 120 - FreeBSD: ~pkg~ 121 - OpenBSD: ~pkg_add~ 122 - NetBSD: ~pkgin~ 123 - Arch Linux: ~pacman~ 124 - Gentoo: ~emerge~ 125 - CentOS: ~yum~ 126 127 *** Installing the epdfinfo server from package managers 128 :PROPERTIES: 129 :CREATED: [2022-02-13 Sun 23:10] 130 :ID: fb5cef15-fed4-4dec-a443-52f7c00c7831 131 :END: 132 ~pdf-tools~ can be directly installed from the package manager on some operating systems. Note that the packages available on these package managers are not maintained by the author and might be outdated. 133 134 - Debian: https://packages.debian.org/buster/elpa-pdf-tools-server 135 - Ubuntu: https://packages.ubuntu.com/impish/elpa-pdf-tools-server 136 - MSYS2 / MINGW (Windows): https://packages.msys2.org/package/mingw-w64-x86_64-emacs-pdf-tools-server?repo=mingw64 137 - FreeBSD: https://repology.org/metapackages/?search=pdf-tools&inrepo=freebsd 138 139 *** Installing the epdfinfo server from source on Windows (+ Gotchas) 140 :PROPERTIES: 141 :CREATED: [2021-12-29 Wed 18:34] 142 :ID: d14e01ff-9bd5-47ee-86fc-859b4499d5d7 143 :END: 144 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. 145 146 1. [[https://www.msys2.org/][install MSYS2]] and update the package database and core packages using the instructions provided. 147 2. Open ~mingw64~ shell (*Note:* You must use ~mingw64.exe~ and not ~msys2.exe~) 148 3. Compile the ~epdfinfo~ server using Installation steps described in [[id:e305cd0a-e798-4c2b-af27-21bcd936c1c9][Installing the ~epdfinfo~ server]] 149 4. This should produce a file ~server/epdfinfo.exe~. Copy this file into the ~pdf-tools/~ installation directory in your Emacs. 150 5. Make sure Emacs can find ~epdfinfo.exe~. Either add the MINGW install location (e.g. ~C:/msys2/mingw64/bin~) to the system path with ~setx PATH "C:\msys2\mingw64\bin;%PATH%"~ or set Emacs's path with ~(setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv "PATH")))~. 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. 151 6. ~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. Please use MSYS2. 152 153 *** Installing the epdfinfo server from source on macOS (+ Gotchas) 154 :PROPERTIES: 155 :CREATED: [2022-10-11 Tue 11:42] 156 :ID: 60CBCD65-5654-400A-913F-8B31901D071C 157 :END: 158 On macOS, ~autobuild~ adjusts ~PKG_CONFIG_PATH~ so that ~pdf-tools~ can find some of the keg-only packages installed by ~brew~. It is recommended that you review the output logs printed by ~brew~ during the installation process to also export the relevant paths to the appropriate ENV variables. 159 160 *** Common installation gotchas 161 :PROPERTIES: 162 :CREATED: [2022-10-11 Tue 11:04] 163 :ID: 3F4C0FDF-6AC0-4845-BA2D-ED7C2F40D894 164 :END: 165 In case you decide to install ~libpoppler~ from source, make sure to run its configure script with the ~--enable-xpdf-headers~ option. 166 167 *** Installing optional features 168 :PROPERTIES: 169 :CREATED: [2022-10-11 Tue 11:15] 170 :ID: 97FC4447-B567-457F-A498-7CCA74DD5657 171 :END: 172 One feature -- following links of a PDF document by plain keystrokes -- requires ~imagemagick~'s convert utility. This requirement is optional, the installation process will detect if you have ~imagemagick~ installed or not. 173 ** Installing pdf-tools elisp code 174 :PROPERTIES: 175 :CREATED: [2021-12-29 Wed 18:34] 176 :ID: 32c4fc3b-b4ea-43bd-b92c-bdf2d3831fcf 177 :END: 178 ~pdf-tools~ requires ~tablist~ package (>= version 0.70) to be installed, for it to work correctly. Please make sure that the latest version of ~tablist~ is installed. 179 180 We have already run the steps necessary to install ~pdf-tools~ as part of [[id:e305cd0a-e798-4c2b-af27-21bcd936c1c9][the server installation]]! These are: 181 #+BEGIN_SRC sh 182 $ git clone https://github.com/vedang/pdf-tools 183 $ cd /path/to/pdf-tools 184 $ make -s 185 #+END_SRC 186 187 If the ~make~ command 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 188 #+begin_src sh 189 $ make install-package 190 #+end_src 191 or executing the Emacs command 192 #+begin_src elisp 193 M-x package-install-file RET pdf-tools-${VERSION}.tar RET 194 #+end_src 195 196 You can test if the package has been installed correctly, by running 197 #+begin_src elisp 198 M-x pdf-info-check-epdfinfo RET 199 #+end_src 200 201 To complete the installation process, you need to activate the package by putting the code below somewhere in your ~.emacs~. Alternatively, and if you care about startup time, you may want to use the loader version instead. 202 #+begin_src elisp 203 (pdf-tools-install) ; Standard activation command 204 (pdf-loader-install) ; On demand loading, leads to faster startup time 205 #+end_src 206 207 Once the Installation process is complete, check out [[id:19a3daea-6fa6-4ac3-9201-d2034c46ad8c][Easy Help for PDF Tools features]] and [[id:8dccd685-18b8-4c98-977a-0fe2d66b724c][Configuring PDF Tools features]] to get started! 208 ** Updating pdf-tools 209 :PROPERTIES: 210 :CREATED: [2021-12-29 Wed 18:34] 211 :ID: 9dd62314-f5ad-4bd4-83fa-8e28343e3d9c 212 :END: 213 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, run ~make distclean~ and then reinstall the package. Follow the steps described in [[id:32c4fc3b-b4ea-43bd-b92c-bdf2d3831fcf][Installing pdf-tools elisp code]]. 214 215 This also applies when updating via MELPA / NonGNU ELPA (except for running the ~make distclean~ step). 216 217 * Features 218 :PROPERTIES: 219 :CREATED: [2021-12-29 Wed 18:34] 220 :ID: 555b4a2a-7881-49ac-a066-7e3f10034ca4 221 :END: 222 + View :: View PDF documents in a buffer with DocView-like bindings. [[id:18d362e1-a1a3-4c51-9d45-04e2c53d8c0c][More information here]]. 223 + Isearch :: Interactively search PDF documents like any other buffer, either for a string or a PCRE. 224 + Occur :: List lines matching a string or regexp in one or more PDF documents. 225 + 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. 226 + 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. [[id:5fff6471-a933-46d7-8ae9-b2fa4a9de952][More information here]]. 227 + Attachments :: Save files attached to the PDF-file or list them in a dired buffer. 228 + Outline :: Use ~imenu~ or a special buffer (=M-x pdf-outline=) to examine and navigate the PDF's outline. 229 + SyncTeX :: Jump from a position on a page directly to the TeX source and vice versa. 230 + Virtual :: Use a collection of documents as if it were one, big single PDF. 231 + Misc :: 232 - Display PDF's metadata. 233 - Mark a region and kill the text from the PDF. 234 - Keep track of visited pages via a history. 235 - Apply a color filter for reading in low light conditions. 236 ** View and Navigate PDFs 237 :PROPERTIES: 238 :CREATED: [2021-12-30 Thu 18:25] 239 :ID: 18d362e1-a1a3-4c51-9d45-04e2c53d8c0c 240 :END: 241 PDFView Mode is an Emacs PDF viewer. It displays PDF files as PNG images in Emacs buffers. PDFs are navigable using DocView-like bindings. Once you have installed ~pdf-tools~, opening a PDF in Emacs will automatically trigger this mode. 242 *** Keybindings for navigating PDF documents 243 :PROPERTIES: 244 :CREATED: [2021-12-30 Thu 18:25] 245 :ID: 01864499-2286-4e64-91f5-f8133f53ec61 246 :END: 247 | Navigation | | 248 |-----------------------------------------------+-------------------------| 249 | Scroll Up / Down by Page-full | ~space~ / ~backspace~ | 250 | Scroll Up / Down by Line | ~C-n~ / ~C-p~ | 251 | Scroll Right / Left | ~C-f~ / ~C-b~ | 252 | First Page / Last Page | ~<~, ~M-<~ / ~>~, ~M->~ | 253 | Next Page / Previous Page | ~n~ / ~p~ | 254 | Incremental Search Forward / Backward | ~C-s~ / ~C-r~ | 255 | Occur (list all lines containing a phrase) | ~M-s o~ | 256 | Jump to Occur Line | ~RETURN~ | 257 | Pick a Link and Jump | ~F~ | 258 | Incremental Search in Links | ~f~ | 259 | History Back / Forwards | ~l~ / ~r~ | 260 | Display Outline | ~o~ | 261 | Jump to Section from Outline | ~RETURN~ | 262 | Jump to Page | ~M-g g~ | 263 | Store position / Jump to position in register | ~m~ / ~'~ | 264 |-----------------------------------------------+-------------------------| 265 | | | 266 Note that ~pdf-tools~ renders the PDF as images inside Emacs. This means that all the keybindings of ~image-mode~ work on individual PDF pages as well. 267 | Image Mode | | 268 |------------------------+---------------------------------------------| 269 | image-scroll-right | ~C-x >~ / ~<remap> <scroll-right>~ | 270 | image-scroll-left | ~C-x <~ / ~<remap> <scroll-left>~ | 271 | image-scroll-up | ~C-v~ / ~<remap> <scroll-up>~ | 272 | image-scroll-down | ~M-v~ / ~<remap> <scroll-down>~ | 273 | image-forward-hscroll | ~C-f~ / ~right~ / ~<remap> <forward-char>~ | 274 | image-backward-hscroll | ~C-b~ / ~left~ / ~<remap> <backward-char>~ | 275 | image-bob | ~<remap> <beginning-of-buffer>~ | 276 | image-eob | ~<remap> <end-of-buffer>~ | 277 | image-bol | ~<remap> <move-beginning-of-line>~ | 278 | image-eol | ~<remap> <move-end-of-line>~ | 279 | image-scroll-down | ~<remap> <scroll-down>~ | 280 | image-scroll-up | ~<remap> <scroll-up>~ | 281 | image-scroll-left | ~<remap> <scroll-left>~ | 282 | image-scroll-right | ~<remap> <scroll-right>~ | 283 |------------------------+---------------------------------------------| 284 | | | 285 286 *** Keybindings for manipulating display of PDF 287 :PROPERTIES: 288 :CREATED: [2021-12-30 Thu 18:33] 289 :ID: 73a18ea8-aa21-48d4-9d8b-dc64e3601000 290 :END: 291 | Display | | 292 |------------------------------------------+-----------------| 293 | Zoom in / Zoom out | ~+~ / ~-~ | 294 | Fit Height / Fit Width / Fit Page | ~H~ / ~W~ / ~P~ | 295 | Trim Margins (set slice to bounding box) | ~s b~ | 296 | Reset Margins | ~s r~ | 297 | Reset Zoom | ~0~ | 298 | Rotate Page | ~R~ | 299 |------------------------------------------+-----------------| 300 301 ** Annotations 302 :PROPERTIES: 303 :CREATED: [2021-12-30 Thu 16:58] 304 :ID: 5fff6471-a933-46d7-8ae9-b2fa4a9de952 305 :END: 306 ~pdf-tools~ supports working with PDF Annotations. You can display and list text and markup annotations (like squiggly, highlight), 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. 307 *** Keybindings for working with Annotations 308 :PROPERTIES: 309 :CREATED: [2021-12-30 Thu 17:08] 310 :ID: 243b3843-b912-430b-884a-641304755b92 311 :END: 312 | Annotations | | 313 |--------------------------------------+----------------------------------------------------| 314 | List Annotations | ~C-c C-a l~ | 315 | Jump to Annotations from List | ~SPACE~ | 316 | Mark Annotation for Deletion | ~d~ | 317 | Delete Marked Annotations | ~x~ | 318 | Unmark Annotations | ~u~ | 319 | Close Annotation List | ~q~ | 320 | Enable/Disable Following Annotations | ~C-c C-f~ | 321 |--------------------------------------+----------------------------------------------------| 322 | Add and Edit Annotations | Select region via Mouse selection. | 323 | | Then left-click context menu OR keybindings below | 324 |--------------------------------------+----------------------------------------------------| 325 | Add a Markup Annotation | ~C-c C-a m~ | 326 | Add a Highlight Markup Annotation | ~C-c C-a h~ | 327 | Add a Strikeout Markup Annotation | ~C-c C-a o~ | 328 | Add a Squiggly Markup Annotation | ~C-c C-a s~ | 329 | Add an Underline Markup Annotation | ~C-c C-a u~ | 330 | Add a Text Annotation | ~C-c C-a t~ | 331 |--------------------------------------+----------------------------------------------------| 332 | Highlight an arbitrary region | Section region with Mouse Drag (Hold down Meta and | 333 | | drag). Then ~C-c C-a h~ to highlight that region. | 334 |--------------------------------------+----------------------------------------------------| 335 | | | 336 337 ** Working with AUCTeX 338 :PROPERTIES: 339 :CREATED: [2021-12-30 Thu 18:37] 340 :ID: 698bdbad-e5f1-4958-b61e-9ed12d4b1234 341 :END: 342 *** Keybindings for working with AUCTeX 343 :PROPERTIES: 344 :CREATED: [2021-12-30 Thu 18:37] 345 :ID: ab7872c1-edd6-465d-9d1d-b621db6364a3 346 :END: 347 | Syncing with AUCTeX | | 348 |-----------------------------------------------+-------------| 349 | Refresh File (e.g., after recompiling source) | ~g~ | 350 | Jump to PDF Location from Source | ~C-c C-g~ | 351 | Jump Source Location from PDF | ~C-mouse-1~ | 352 353 ** Miscellaneous features 354 :PROPERTIES: 355 :CREATED: [2021-12-30 Thu 18:37] 356 :ID: bbefb49d-fca8-4d4f-9d16-4a4ad1946d89 357 :END: 358 *** Keybindings for miscellaneous features in PDF tools 359 :PROPERTIES: 360 :CREATED: [2021-12-30 Thu 18:35] 361 :ID: 9148deff-dd5a-46be-a48f-cd2f96b7ce19 362 :END: 363 | Miscellaneous | | 364 |-----------------------------------------------+-----------| 365 | Print File | ~C-c C-p~ | 366 367 ** Easy Help for PDF Tools features 368 :PROPERTIES: 369 :CREATED: [2021-12-29 Wed 13:49] 370 :ID: 19a3daea-6fa6-4ac3-9201-d2034c46ad8c 371 :END: 372 #+begin_src elisp 373 M-x pdf-tools-help RET 374 #+end_src 375 376 Run =M-x pdf-tools-help= inside Emacs, as shown above. It will list all the features provided by ~pdf-tools~ as well as the key-bindings for these features. 377 378 ** Configuring PDF Tools features 379 :PROPERTIES: 380 :CREATED: [2021-12-29 Wed 13:51] 381 :ID: 8dccd685-18b8-4c98-977a-0fe2d66b724c 382 :END: 383 Once you have read through the features provided by ~pdf-tools~, you probably want to customize the behavior of the features as per your requirements. Full customization of features is available by running the following: 384 #+begin_src elisp 385 M-x pdf-tools-customize RET 386 #+end_src 387 388 * Known problems 389 :PROPERTIES: 390 :CREATED: [2021-12-29 Wed 18:29] 391 :ID: 4baf936a-2454-41c9-99db-177133ee9568 392 :END: 393 394 ** linum-mode 395 :PROPERTIES: 396 :CREATED: [2021-12-29 Wed 18:34] 397 :ID: 73625d02-d472-4e7d-9805-db6d3b60e0ff 398 :END: 399 ~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. 400 401 ** display-line-numbers-mode 402 :PROPERTIES: 403 :CREATED: [2022-01-03 Mon 08:31] 404 :ID: f178ba41-0f5a-4d22-b4a8-889af1af566e 405 :END: 406 This mode is an alternative to ~linum-mode~ and is available since Emacs 26. ~pdf-tools~ does not work well with it. For example, it makes horizontal navigation (such as ~C-f~, ~C-b~, ~C-x <~ or ~C-x >~ ) in a document impossible. 407 408 ** auto-revert 409 :PROPERTIES: 410 :CREATED: [2021-12-29 Wed 18:34] 411 :ID: 24b671c6-c242-4983-9d11-38421d2752e9 412 :END: 413 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. 414 415 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. 416 #+BEGIN_SRC emacs-lisp 417 (add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer) 418 #+END_SRC 419 420 ** sublimity 421 :PROPERTIES: 422 :CREATED: [2021-12-29 Wed 18:34] 423 :ID: 4766d18a-c02a-456d-8398-701bbea3ee80 424 :END: 425 L/R scrolling breaks while zoomed into a pdf, with usage of sublimity smooth scrolling features 426 427 ** Text selection is not transparent in PDFs OCRed with Tesseract 428 :PROPERTIES: 429 :CREATED: [2022-09-19 Mon 18:50] 430 :ID: C3A4A7C0-6BBB-4923-AD39-3707C8482A76 431 :END: 432 433 In such PDFs the selected text becomes hidden behind the selection; see [[https://github.com/vedang/pdf-tools/issues/149][this issue]], which also describes the workaround in detail. The following function, which depends on the [[https://github.com/orgtre/qpdf.el][qpdf.el]] package, can be used to convert such a PDF file into one where text selection is transparent: 434 #+begin_src elisp 435 (defun my-fix-pdf-selection () 436 "Replace pdf with one where selection shows transparently." 437 (interactive) 438 (unless (equal (file-name-extension (buffer-file-name)) "pdf") 439 (error "Buffer should visit a pdf file.")) 440 (unless (equal major-mode 'pdf-view-mode) 441 (pdf-view-mode)) 442 ;; save file in QDF-mode 443 (qpdf-run (list 444 (concat "--infile=" 445 (buffer-file-name)) 446 "--qdf --object-streams=disable" 447 "--replace-input")) 448 ;; do replacements 449 (text-mode) 450 (read-only-mode -1) 451 (while (re-search-forward "3 Tr" nil t) 452 (replace-match "7 Tr" nil nil)) 453 (save-buffer) 454 (pdf-view-mode)) 455 #+end_src 456 Note that this overwrites the PDF file visited in the buffer from which it is run! To avoid this replace the ~--replace-input~ with ~(concat "--outfile=" (file-truename (read-file-name "Outfile: ")))~. 457 458 * Key-bindings in PDF Tools 459 :PROPERTIES: 460 :CREATED: [2021-12-29 Wed 18:34] 461 :ID: fa99285a-437e-4be4-9a65-426db019019f 462 :END: 463 - [[brain-child:01864499-2286-4e64-91f5-f8133f53ec61][Keybindings for navigating PDF documents]] 464 - [[brain-child:243b3843-b912-430b-884a-641304755b92][Keybindings for working with Annotations]] 465 - [[brain-child:73a18ea8-aa21-48d4-9d8b-dc64e3601000][Keybindings for manipulating display of PDF]] 466 - [[brain-child:ab7872c1-edd6-465d-9d1d-b621db6364a3][Keybindings for working with AUCTeX]] 467 - [[brain-child:9148deff-dd5a-46be-a48f-cd2f96b7ce19][Keybindings for miscellaneous features in PDF tools]] 468 469 * Tips and Tricks for Developers 470 :PROPERTIES: 471 :CREATED: [2021-12-29 Wed 18:34] 472 :ID: fd64c10c-4ea5-4ece-8d95-b723098dd4f6 473 :END: 474 ** Turn on debug mode 475 :PROPERTIES: 476 :CREATED: [2021-12-29 Wed 18:34] 477 :ID: 100fc888-7064-4dd3-9db4-c84a7e8f4af0 478 :END: 479 #+begin_src elisp 480 M-x pdf-tools-toggle-debug RET 481 #+end_src 482 Toggling debug mode prints information about various operations in the ~*Messages*~ buffer, and this is useful to see what is happening behind the scenes 483 484 ** Run Emacs lisp tests locally 485 :PROPERTIES: 486 :CREATED: [2022-05-09 Mon 21:27] 487 :ID: 1CBE7325-A5A1-479B-9A98-BEEFBAC9D8FF 488 :END: 489 You can go to the ~pdf-tools~ folder and run ~make test~ to run the ERT tests and check if the changes you have made to the code break any of the tests. 490 491 The tests are written in ERT, which is the built-in testing system in Emacs. However, they are run using ~Cask~ which you will have to install first, if you don't have it already. You can install ~Cask~ by following the instructions on their site at https://github.com/cask/cask 492 ** Run server compilation tests locally 493 :PROPERTIES: 494 :CREATED: [2022-07-20 Wed 16:42] 495 :ID: 5327945D-9D92-4462-8172-7237DEF4C359 496 :END: 497 You can go to the ~pdf-tools~ folder and run ~make server-test~ to check if the changes you have made to the server code break compilation on any of the supported operating systems. 498 499 The tests build ~Podman~ images for all supported operating systems, so you will have to install ~Podman~ first, if you don't have already. You can install ~Podman~ by following the instructions on their site at https://podman.io/getting-started/installation 500 501 Podman is compatible with Docker, so if you already have ~docker~ installed, you should be able to ~alias podman=docker~ on your shell and run the tests, without having to install Docker. (Note: I have not tested this) 502 503 ** Add a Dockerfile to automate server compilation testing 504 :PROPERTIES: 505 :CREATED: [2022-07-20 Wed 16:52] 506 :ID: A401543C-308B-4175-8212-5B78CD6C8389 507 :END: 508 The ~server/test/docker~ folder contains Dockerfile templates used for testing that the ~epdfinfo~ server compiles correctly on various operating systems ([[id:5327945D-9D92-4462-8172-7237DEF4C359][more details here]]). 509 510 To see the list of operating systems where compilation testing is supported, run ~make server-test-supported~. To see the list of operating systems where testing is unsupported, run ~make server-test-unsupported~. To add support, look into the ~server/test/docker/templates~ folder (~ubuntu~ files are a good example to refer to) 511 512 ** Issue Template for Bug Reports 513 :PROPERTIES: 514 :CREATED: [2022-12-02 Fri 13:30] 515 :ID: F563A2A4-FCF8-4F04-94CA-19E80E4841A6 516 :END: 517 Please use the 'Bug Report' issue template when reporting bugs. The template is as follows: 518 519 *** Describe the bug 520 A clear and concise description of what the bug is. 521 522 *** Steps To Reproduce the behaviour: 523 1. Go to '...' 524 2. Click on '....' 525 3. Scroll down to '....' 526 4. See error 527 528 *** What is the expected behaviour? 529 A clear and concise description of what you expected to happen. 530 531 *** Desktop 532 Please complete the following information: 533 534 - OS: [eg: MacOS Catalina] 535 - Emacs Version: [This should be the output of =M-x emacs-version= ] 536 - Poppler Version: [eg: output of ~brew info poppler~ and similarly for other OSs] 537 538 *** Your pdf-tools install 539 Please complete the following information: 540 - ~pdf-tools~ Version: [ =M-x package-list-packages= -> Search for ~pdf-tools~ -> Hit Enter and copy all the details that pop up in the Help buffer] 541 - ~pdf-tools~ customization / configuration that you use: 542 543 *** Additional context 544 - If you are reporting a crash, please try and add the Backtrace / Stacktrace of the crash. 545 - If you are reporting a bug, please try and attach an example PDF file where I can reproduce the bug. 546 - If you can attach screenshots or recordings, that is a great help 547 - Please try reproducing the bug yourself on Vanilla Emacs before reporting the problem. 548 549 * FAQs 550 :PROPERTIES: 551 :CREATED: [2021-12-30 Thu 22:04] 552 :ID: 3be6abe7-163e-4c3e-a7df-28e8470fe37f 553 :END: 554 ** Epdfinfo has stopped working! 555 :PROPERTIES: 556 :CREATED: [2023-06-10 Sat 23:25] 557 :ID: 9B5F797F-9BB3-45D9-B364-D4E5F13222BF 558 :END: 559 Have you upgraded ~poppler~ recently? This can cause ~epdfinfo~ to stop working, since it was compiled with the previous version of ~poppler~. Just run =M-x pdf-tools-install= and this should be fixed. 560 561 ** PDFs are not rendering well! 562 :PROPERTIES: 563 :CREATED: [2021-12-30 Thu 22:04] 564 :ID: 20ef86be-7c92-4cda-97ec-70a22484e689 565 :END: 566 ~pdf-tools~ version ~1.1.0~ release changed the default value of ~pdf-view-use-scaling~ to ~t~ (previously, it was ~nil~). This has been done keeping in mind that most modern monitors are HiDPI screens, so the default configuration should cater to this user. If you are not using a HiDPI screen, you might have to change this value to ~nil~ in your configuration 567 568 #+begin_src elisp 569 (setq pdf-view-use-scaling nil) 570 #+end_src 571 572 to scale the images correctly when rendering them. 573 574 ** What Emacs versions does pdf-tools support? 575 :PROPERTIES: 576 :CREATED: [2022-01-02 Sun 10:12] 577 :ID: f44c66e6-402d-4154-b806-6bb4180a0a5b 578 :END: 579 ~pdf-tools~ supports the 3 latest versions of Emacs major releases. At the moment of this writing, this means that the minimum supported Emacs version is ~26.3~. 580 581 ** I want to add support for pdf-tools on "My Fav OS". How do I do that? 582 :PROPERTIES: 583 :CREATED: [2022-04-25 Mon 21:50] 584 :ID: A34704B9-1B51-4614-8806-C4059F7B42D5 585 :END: 586 I'm working on automating ~pdf-tools~ installation as much as possible, in order to improve the installation experience. If you want to add support for a new / currently unsupported Operating System, please modify the ~server/autobuild~ script. Say you want to support a new Operating System called MyFavOS. You need to do the following work: 587 588 1. Search for the ~Figure out where we are~ section. Here, add a call to ~os_myfavos~ right below ~handle_options~ at the end of the existing call chain. Here we try and pick up the correct Operating System and install the relevant dependencies. 589 2. Add handling for the ~--os~ argument in ~os_argument~ for ~myfavos~, so that the appropriate function can be called to install pre-requisites. ~--os~ is the argument that we pass to the script from the command-line to indicate which OS we are on. 590 3. Create a ~os_myfavos~ function. This function checks if we are running on MyFavOS. If we are running on MyFavOS, it sets up ~PKGCMD~, ~PKGARGS~ and ~PACKAGES~ variables so that the appropriate package manager can install the dependencies as part of the rest of the ~autobuild~ script. 591 4. If you are adding support for your favorite operating system, consider adding automated testing support as well, to help me ensure that ~epdfinfo~ continues to compile correctly. See [[id:A401543C-308B-4175-8212-5B78CD6C8389][Add a Dockerfile to automate server compilation testing]] for more details. 592 593 The idea here is to make the ~server/autobuild~ file the single place from which installation can happen on any Operating System. This makes building ~pdf-tools~ dead simple via the ~Makefile~. 594 595 This seems like a lot of work, but it is not. If you need a reference, search for ~os_gentoo~ or ~os_debian~ in the ~server/autobuild~ file and see how these are setup and used. The functions are used to install dependencies on Gentoo and Debian respectively, and are simple to copy / change. 596 597 When you make your changes, please be sure to test [[id:1CBE7325-A5A1-479B-9A98-BEEFBAC9D8FF][the elisp changes]] as well as [[id:5327945D-9D92-4462-8172-7237DEF4C359][the server code changes]] as described in the linked articles. 598 599 ** I am on a Macbook M1 and pdf-tools installation fails with a stack-trace 600 :PROPERTIES: 601 :CREATED: [2022-05-09 Mon 20:29] 602 :ID: 96D389D8-DD23-4FB0-996C-2D6F70A76BB2 603 :END: 604 There have been a number of issues around ~pdf-tools~ installation problems on M1. =M-x pdf-tools-install= throws the following stack trace: 605 #+begin_example 606 1 warning generated. 607 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 608 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 609 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 610 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 611 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 612 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 613 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 614 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 615 Undefined symbols for architecture x86_64: 616 #+end_example 617 618 This happens because M1 architecture is =ARM64=, whereas the Emacs App you are using has been compiled for the =x86_64= architecture. The way to solve this problem is to install a version of Emacs which has been compiled for the M1. As of today, [2022-05-09 Mon], the latest version of Emacs available on https://emacsformacosx.com/ is natively compiled and you will not face these issues on it. Please remove your current Emacs App and install it from https://emacsformacosx.com/. 619 620 Thank you. 621 622 PS: How do I know if the Emacs I'm running has been compiled correctly? 623 624 You can see this by opening the =Activity Monitor=, selecting =Emacs=, clicking on the =Info= key, and then clicking on =Sample=. The =Code Type= field in the Sample output will show you how your Application has been compiled. Here is the output for EmacsForMacOSX (you can see that it's =ARM64=): 625 #+begin_example 626 Sampling process 61824 for 3 seconds with 1 millisecond of run time between samples 627 Sampling completed, processing symbols... 628 Analysis of sampling Emacs-arm64-11 (pid 61824) every 1 millisecond 629 Process: Emacs-arm64-11 [61824] 630 Path: /Applications/Emacs.app/Contents/MacOS/Emacs-arm64-11 631 Load Address: 0x1007f0000 632 Identifier: org.gnu.Emacs 633 Version: Version 28.1 (9.0) 634 Code Type: ARM64 635 Platform: macOS 636 #+end_example 637 638 If your Emacs is compiled for x86, the =Code Type= will be =x86_64=. 639 640 ** I am a developer, making changes to the pdf-tools source code 641 :PROPERTIES: 642 :CREATED: [2022-05-09 Mon 21:31] 643 :ID: 2D173424-C211-4474-B0D0-83F4381CAFFA 644 :END: 645 Thank you for taking the time to contribute back to the code. You may find some useful notes in the [[id:fd64c10c-4ea5-4ece-8d95-b723098dd4f6][Tips and Tricks for Developers]] section. Please be sure to check it out!