dotemacs

README (17099B)

---

 #+TITLE:     PDF Tools README
 #+AUTHOR:    Andreas Politz
 #+EMAIL:     politza@fh-trier.de
 #+Maintainer: Vedang Manerikar
 #+Maintainer_Email: vedang.manerikar@gmail.com
 
 [[https://app.circleci.com/pipelines/github/vedang/pdf-tools][https://circleci.com/gh/vedang/pdf-tools.svg?style=svg]]
 [[https://stable.melpa.org/#/pdf-tools][http://stable.melpa.org/packages/pdf-tools-badge.svg]]
 [[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]]
 
 ** About this package
    PDF Tools is, among other things, a replacement of DocView for PDF
    files.  The key difference is that pages are not pre-rendered by
    e.g. ghostscript and stored in the file-system, but rather created
    on-demand and stored in memory.
 
    This rendering is performed by a special library named, for
    whatever reason, poppler, running inside a server program.  This
    program is called ~epdfinfo~ and its job is to successively
    read requests from Emacs and produce the proper results, i.e. the
    PNG image of a PDF page.
 
    Actually, displaying PDF files is just one part of PDF Tools.
    Since poppler can provide us with all kinds of information about a
    document and is also able to modify it, there is a lot more we can
    do with it. [[http://www.dailymotion.com/video/x2bc1is_pdf-tools-tourdeforce_tech?forcedQuality%3Dhd720][Watch]]
 
    Please read also about [[#known-problems][known problems.]]
 
 ** Features
    + View :: View PDF documents in a buffer with DocView-like
              bindings.
    + Isearch :: Interactively search PDF documents like any other
                 buffer, either for a string or a PCRE.
    + Occur :: List lines matching a string or regexp in one or more
               PDF documents.
    + Follow ::
     Click on highlighted links, moving to some part of a different
     page, some external file, a website or any other URI.  Links may
     also be followed by keyboard commands.
    + Annotations :: Display and list text and markup annotations (like
                     underline), edit their contents and attributes
                     (e.g. color), move them around, delete them or
                     create new ones and then save the modifications
                     back to the PDF file.
    + Attachments :: Save files attached to the PDF-file or list them
                     in a dired buffer.
    + Outline :: Use imenu or a special buffer to examine and navigate
                 the PDF's outline.
    + SyncTeX :: Jump from a position on a page directly to the TeX
                 source and vice versa.
    + Virtual ::
     Use a collection of documents as if it were one, big single PDF.
 
    + Misc ::
      - Display PDF's metadata.
      - Mark a region and kill the text from the PDF.
      - Keep track of visited pages via a history.
      - Apply a color filter for reading in low light conditions.
 
 ** Installation
    The package may be installed via MELPA and it will try to build the
    server part when it is activated the first time.  Though the next
    section regarding build-prerequisites is still relevant, the rest
    of the installation instructions assume a build from within a git
    repository. (The MELPA package has a different directory
    structure.)
 
 *** Server prerequisites
     You'll need GNU Emacs \ge 24.3 and some form of a GNU/Linux OS.
     Other operating systems are currently not supported (patches
     welcome).  The following instructions assume a Debian-based
     system. (The prerequisites may be installed automatically on this
     kind of systems, see [[#compilation][Compilation]] .)
 
     First make sure a suitable build-system is installed.  We need at
     least a C/C++ compiler (both ~gcc~ and ~g++~), ~make~, ~automake~
     and ~autoconf~.
 
     Next we need to install a few libraries PDF Tools depends on, some
     of which are probably already on your system.
 #+begin_src sh
   $ sudo aptitude install libpng-dev zlib1g-dev
   $ sudo aptitude install libpoppler-glib-dev
   $ sudo aptitude install libpoppler-private-dev
 #+end_src
     On some older Ubuntu systems, the final command will possibly give
     an error.  This should be no problem, since in some versions this
     package was contained in the main package ~libpoppler-dev~.  Also
     note, that ~zlib1g-dev~ was for a long time called ~libz-dev~,
     which it still may be on your system.
 
     Debian wheezy comes with libpoppler version 0.18, which is pretty
     old.  The minimally required version is 0.16, but some features of
     PDF Tools depend on a more recent version of this library.  See
     the following table for what they are and what version they
     require.
 
     | You want to ...                           | Required version |
     |-------------------------------------------+------------------|
     | ... create and modify text annotations.   | \ge 0.19.4       |
     | ... search case-sensitive.                | \ge 0.22         |
     | ... create and modify markup annotations. | \ge 0.26         |
     |-------------------------------------------+------------------|
 
     In case you decide to install libpoppler from source, make sure
     to run its configure script with the ~--enable-xpdf-headers~
     option.
 
     Finally there is one feature (following links of a PDF document by
     plain keystrokes) which requires imagemagick's convert utility.
     This requirement is optional and you may install it like so:
 #+begin_src sh
   $ sudo aptitude install imagemagick
 #+end_src
 **** Compiling on macOS
      Although macOS is not officially supported, it has been reported
      to have been successfully compiled.  You will need to install
      poppler which you can get with Homebrew via
 #+BEGIN_SRC sh
   $ brew install poppler automake
 #+END_SRC
 
      You will also have to help ~pkg-config~ find some libraries by
      setting ~PKG_CONFIG_PATH~, e.g.
 #+BEGIN_SRC sh
   $ export PKG_CONFIG_PATH=/usr/local/Cellar/zlib/1.2.8/lib/pkgconfig:/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig
 #+END_SRC
      or likewise within Emacs using `setenv`.
 
      After that, compilation should proceed as normal.
 **** FreeBSD
      Although not officially supported, it has been reported that
      pdf-tools work well on FreeBSD.  Instead of building pdf-tools, you
      can install one of the OS packages with, e.g.
 #+BEGIN_SRC sh
   $ pkg install pdf-tools-emacs26
 #+END_SRC
      To see the current list of pdf-tools packages for FreeBSD visit
      [[https://repology.org/metapackages/?search=pdf-tools&inrepo=freebsd][the Repology list]].
 
      To build pdf-tools from either MELPA or directly from the source
      repository, install the dependencies with
 #+BEGIN_SRC sh
   $ pkg install autotools gmake poppler-glib
 #+END_SRC
 
      If you choose not to install from MELPA, you must substitute
     ~gmake~ for ~make~ in the instructions below.
 **** Compiling on CentOS
      It is possible to compile pdf-tools on CentOS. Install poppler the dependencies with:
 #+BEGIN_SRC sh
   $ yum install poppler-devel poppler-glib-devel
 #+END_SRC
 
 **** Compiling on Fedora
 #+BEGIN_SRC sh
   $ sudo dnf install make automake autoconf gcc gcc-c++ ImageMagick libpng-devel zlib-devel poppler-glib-devel
 #+END_SRC
 
 **** Compiling on Alpine Linux
 #+BEGIN_SRC sh
   $ apk add build-base g++ gcc automake autoconf libpng-dev glib-dev poppler-dev
 #+END_SRC
 
 **** Compiling on Windows
      PDF Tools can be built and used on Windows using the MSYS2
      compiler. This will work with native (not cygwin) Windows builds of
      emacs. This includes the standard binaries provided by the GNU
      project, those available as MSYS2 packages and numerous third-party
      binaries. It has been tested with Emacs 25.1. Instructions are
      provided under [[#compilation-and-installation-on-windows][Compilation and installation on Windows]], below.
      PDF Tools will successfully compile using Cygwin, but it will not be
      able to open PDFs properly due to the way binaries compiled with Cygwin
      handle file paths.
 
 *** Compilation
     :PROPERTIES:
     :CUSTOM_ID: compilation
     :END:
     Now it's time to compile the source.
 #+begin_src sh
     $ cd /path/to/pdf-tools
     $ make install-server-deps # optional
     $ make -s
 #+end_src
     The ~make install-server-deps~ command will try to install all
     necessary programs and libraries to build the package, though
     it'll only work, if ~sudo~ and ~apt-get~ are available.
 
     This should compile the source code and create a Emacs Lisp
     Package in the root directory of the project. The configure script
     also tells you at the very end, which features, depending on the
     libpoppler version, will be available.  These commands should give
     no error, otherwise you are in trouble.
 **** Compilation and installation on Windows
      :PROPERTIES:
      :CUSTOM_ID: compilation-and-installation-on-windows
      :END:
       If using the GNU binaries for Windows, support for PNG and zlib
       must first be installed by copying the appropriate dlls into
       emacs' ~bin/~ directory. Most third-party binaries come with this
       already done.
 
       First, install [[http://www.msys2.org/][install MSYS2]] and update
       the package database and core packages using the instructions
       provided. Then, to compile PDF tools itself:
 
       1. Open msys2 shell
 
       2. Update and install dependencies, skipping any you already have
          #+BEGIN_SRC sh
          $ pacman -Syu
          $ pacman -S base-devel
          $ pacman -S mingw-w64-x86_64-toolchain
          $ pacman -S mingw-w64-x86_64-zlib
          $ pacman -S mingw-w64-x86_64-libpng
          $ pacman -S mingw-w64-x86_64-poppler
          $ pacman -S mingw-w64-x86_64-imagemagick
          #+END_SRC
 
       3. Install PDF tools in Emacs, but do not try to compile the
          server. Instead, get a separate copy of the source somewhere
          else.
          #+BEGIN_SRC sh
          $ git clone https://github.com/politza/pdf-tools
          #+END_SRC
 
       4. Open ~mingw64~ shell (*Note:* You must use ~mingw64.exe~ and not ~msys2.exe~)
 
       5. Compile pdf-tools
          #+BEGIN_SRC sh
          $ cd /path/to/pdf-tools
          $ make -s
          #+END_SRC
 
       6. This should produce a file ~server/epdfinfo.exe~. Copy this file
          into the ~pdf-tools/~ installation directory in your Emacs.
 
       7. Start Emacs and activate the package.
          #+BEGIN_SRC
          M-x pdf-tools-install RET
          #+END_SRC
 
       8. Test.
          #+BEGIN_SRC
          M-x pdf-info-check-epdfinfo RET
          #+END_SRC
 
       If this is successful, ~(pdf-tools-install)~ can be added to Emacs'
       config. Note that libraries from other GNU utilities, such as Git
       for Windows, may interfere with those needed by PDF Tools.
       ~pdf-info-check-epdinfo~ will succeed, but errors occur when trying
       to view a PDF file. This can be fixed by ensuring that the MSYS
       libraries are always preferred in Emacs:
 
  #+BEGIN_SRC emacs-lisp
  (setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv "PATH")))
  #+END_SRC
 
 *** Elisp prerequisites
     This package depends on the following Elisp packages, which should
     be installed before installing the PDF Tools package.
 
     | Package   | Required version                 |
     |-----------+----------------------------------|
     | [[https://elpa.gnu.org/packages/let-alist.html][let-alist]] | >= 1.0.4 (comes with Emacs 25.2) |
     | [[http://melpa.org/#/tablist][tablist]]   | >= 0.70                          |
     |-----------+----------------------------------|
 
 *** Installing
     If ~make~ produced the ELP file ~pdf-tools-${VERSION}.tar~ you are
     fine.  This package contains all the necessary files for Emacs
     and may be installed by either using
 #+begin_src sh
     $ make install-package
 #+end_src
     or executing the Emacs command
 #+begin_src elisp
   M-x package-install-file RET pdf-tools-${VERSION}.tar RET
 #+end_src
 
   To complete the installation process, you need to activate the
   package by putting
 #+begin_src elisp
   (pdf-tools-install)
 #+end_src
   somewhere in your ~.emacs~.  Alternatively, and if you care about
   start-up time, you may want to use
 #+begin_src elisp
   (pdf-loader-install)
 #+end_src
   instead.  Next you probably want to take a look at the various
   features of what you've just installed.  The following two commands
   might be of help for doing so.
 #+begin_src elisp
   M-x pdf-tools-help RET
   M-x pdf-tools-customize RET
 #+end_src
 
 *** Updating
     Some day you might want to update this package via ~git pull~ and
     then reinstall it.  Sometimes this may fail, especially if
     Lisp-Macros are involved and the version hasn't changed.  To avoid
     this kind of problems, you should delete the old package via
     ~list-packages~, restart Emacs and then reinstall the package.
 
     This also applies when updating via package and MELPA.
 
 ** Known problems
     :PROPERTIES:
     :CUSTOM_ID: known-problems
     :END:
 
 *** linum-mode
     PDF Tools does not work well together with ~linum-mode~ and
     activating it in a ~pdf-view-mode~, e.g. via ~global-linum-mode~,
     might make Emacs choke.
 
 *** auto-revert
     Autorevert works by polling the file-system every
     ~auto-revert-interval~ seconds, optionally combined with some
     event-based reverting via [[https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html][file notification]].  But this currently
     does not work reliably, such that Emacs may revert the PDF-buffer
     while the corresponding file is still being written to (e.g. by
     LaTeX), leading to a potential error.
 
     With a recent [[https://www.gnu.org/software/auctex/][AUCTeX]] installation, you might want to put the
     following somewhere in your dotemacs, which will revert the PDF-buffer
     *after* the TeX compilation has finished.
 #+BEGIN_SRC emacs-lisp
   (add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer)
 #+END_SRC
 
 *** sublimity
     L/R scrolling breaks while zoomed into a pdf, with usage of sublimity smooth scrolling features
 
 ** Some keybindings
 
 | Navigation                                 |                       |
 |--------------------------------------------+-----------------------|
 | Scroll Up / Down by Page-full              | ~space~ / ~backspace~ |
 | Scroll Up / Down by Line                   | ~C-n~ / ~C-p~         |
 | Scroll Right / Left                        | ~C-f~ / ~C-b~         |
 | Top of Page / Bottom of Page               | ~<~ / ~>~             |
 | Next Page / Previous Page                  | ~n~ / ~p~             |
 | First Page / Last Page                     | ~M-<~ / ~M->~         |
 | Incremental Search Forward / Backward      | ~C-s~ / ~C-r~         |
 | Occur (list all lines containing a phrase) | ~M-s o~               |
 | Jump to Occur Line                         | ~RETURN~              |
 | Pick a Link and Jump                       | ~F~                   |
 | Incremental Search in Links                | ~f~                   |
 | History Back / Forwards                    | ~B~ / ~N~             |
 | Display Outline                            | ~o~                   |
 | Jump to Section from Outline               | ~RETURN~              |
 | Jump to Page                               | ~M-g g~               |
 
 | Display                                  |                 |
 |------------------------------------------+-----------------|
 | Zoom in / Zoom out                       | ~+~ / ~-~       |
 | Fit Height / Fit Width / Fit Page        | ~H~ / ~W~ / ~P~ |
 | Trim Margins (set slice to bounding box) | ~s b~           |
 | Reset Margins                            | ~s r~           |
 | Reset Zoom                               | 0               |
 
 | Annotations                   |                                                 |
 |-------------------------------+-------------------------------------------------|
 | List Annotations              | ~C-c C-a l~                                     |
 | Jump to Annotations from List | ~SPACE~                                         |
 | Mark Annotation for Deletion  | ~d~                                             |
 | Delete Marked Annotations     | ~x~                                             |
 | Unmark Annotations            | ~u~                                             |
 | Close Annotation List         | ~q~                                             |
 | Add and Edit Annotations      | via Mouse selection and left-click context menu |
 
 | Syncing with AUCTeX                    |             |
 |----------------------------------+-------------|
 | Jump to PDF Location from Source | ~C-c C-g~   |
 | Jump Source Location from PDF    | ~C-mouse-1~ |
 
 | Miscellaneous                                 |           |
 |-----------------------------------------------+-----------|
 | Refresh File (e.g., after recompiling source) | ~g~       |
 | Print File                                    | ~C-c C-p~ |
 
 # Local Variables:
 # mode: org
 # End: