How to use pdf-tools (pdf-view-mode) in emacs?

Question

pdf-tools includes pdf-view-mode which offers several features not present in doc-view-mode (see end of question).

Can pdf-view-mode be used as a replacement for doc-view-mode generally, or does it have to be "tool" by tool?

In either case, is it necessary to edit emacs source to use pdf-tools in gnus, eww and orgmode or are their system-wide settings that can be employed?

--- Features of pdf-tools here for convenience; see github site for details ---

1. Seems faster than doc-view
2. Resolution usually better since not being rendered as a png
3. Nice search, and can even search for all occurrences of a phrase
4. Can add text annotations, and highlighting, underlining, and the like
5. Can create imenus for pdf parts
6. Can treat several pdfs as a single "virtual" pdf
7. Can integrate with latex to see latex source and pdf side by side and jump from one to the other at the equivalent locations (e.g. select \section{A section} in LaTeX and got that section in pdf.

Answer 1

Switching from docview to pdf-tools happens 'automatically' when you install pdf-tools. Once you've done this, any time Emacs tries to open a pdf in Emacs, it will use pdf-tools. However, some packages will call out to the operating system, or use different config within Emacs, to decide if they should use Emacs or another program to open a pdf. So there is some 'tool-by-tool' configuration required to get all Emacs packages to use pdf-tools.

If you want your pdfs opened in the same instance of Emacs, you need to have it running in daemon mode (i.e., start it with emacs --daemon), or call (server-start) in your init so that emacsclient will work.

Org-mode links

Out of the box, org-mode doesn't know about pdf-tools. However, you can add support for opening org links to pdf files with org-pdfview, which is available as a package on MELPA. Once it's installed, you can activate it with the following code in your .emacs:

(eval-after-load 'org '(require 'org-pdfview))

(add-to-list 'org-file-apps 
             '("\\.pdf\\'" . (lambda (file link)
                                     (org-pdfview-open link))))

Doing this will provide a new completion target for adding links via C-c C-l, pdfview:, with support for jumping to specific pages. Full links use the format:

[[pdfview:/path/to/myfile.pdf::42][My file Description]]

Interleave Mode & PDF annotations

Interleave mode provides support for presenting "your PDF side by side with an Org Mode buffer with your notes." This is an alternative to using the annotations embedded in a pdf (which you can do with pdf-tools). Instead, you end up with an org-mode file with all your annotations, which links to the page in the pdf that the annotations are associated with.

Gnus

As I mentioned in my comment, gnus uses mailcap to open attachments. To configure this, you need the following in your .mailcap file:

application/pdf; emacsclient %s

EWW

EWW also uses mailcap, so modify your .mailcap file as per Gnus above.

AucTeX

For AucTeX, there are a number of relevant options:

• viewers are specified via the variable TeX-view-program-selection: find the entry for output-pdf and select "PDF Tools" for the value.
• to use SyncTex, you need to:
  • set TeX-source-correlate-mode, either interactively by calling that function via M-x, or by setting the variable permanently via M-x customize-variable.
  • make sure TeX-source-correlate-method includes (pdf . synctex)

With this in place, from your tex source file C-c C-g should display the corresponding section of the pdf.

ESS

Customize the variable ess-pdf-viewer-pref to emacsclient.

xdg-open

On Linux, some packages will call the external program xdg-open to open pdf files. This will use your system-wide settings to determine which program to use. This is a system-wide change, so other programs will send pdf documents to Emacs when you've set this up. So if you don't want, e.g., Firefox, to do this, you won't want to make these changes.

To set emacsclient to open pdfs system-wide via xdg-open:

• create a file in ~/.local/share/applications/emacsclient.desktop with the contents:

[Desktop Entry]
Name=Emacs Client
Exec=emacsclient %u
Icon=emacs-icon
Type=Application
Terminal=false
MimeType=application/pdf;

• from the command line, issue:

xdg-mime default emacsclient.desktop application/pdf

You can test that this worked with xdg-open your-document.pdf - it should open your-document.pdf in Emacs.

w3m

w3m first checks the variable w3m-doc-view-content-types, and if it sees "application/pdf" there, it will open pdfs in doc-view. This is a customizable variable, so remove the "application/pdf" entry using the customization interface.

Without an entry in w3m-doc-view-content-types, w3m next checks the variable w3m-content-type-alist for entries that match "application/pdf". Customize the entry to read

[INS] [DEL] Type: application/pdf
  Regexp: ( ) Not specified
          (*) String: \.pdf\'
  Viewer: ( ) Not specified
          (*) External viewer:
                Command: emacsclient
                Arguments:
                  [INS] [DEL] file
                  [INS]

You could also use an emacs function (presumably find-file or similar), rather than an external call to emacsclient, but I couldn't figure out the syntax for that.