Month: October 2017

View and annotate PDFs in Emacs with PDF-tools

The pdf-tools packages allows you to read and annotate PDF documents in Emacs. The installation process is described on the github page, but on my Mac, I needed to install poppler (I used macports) and add 

export PKG_CONFIG_PATH=/opt/local/lib/pkgconfig

to my zshrc. Then after installing the package in Emacs with the following code 

(use-package pdf-tools
 :pin manual ;; manually update
 :config
 ;; initialise
 (pdf-tools-install)
 ;; open pdfs scaled to fit page
 (setq-default pdf-view-display-size 'fit-page)
 ;; automatically annotate highlights
 (setq pdf-annot-activate-created-annotations t)
 ;; use normal isearch
 (define-key pdf-view-mode-map (kbd "C-s") 'isearch-forward))

I ran M-x pdf-tools-install, ignored an error message about epdfinfo and then restarted emacs, and all was well.

I use the :pin manual option in use-package to stop pdf-tools being automatically updated when I update the rest of my packages, since it would need the installation command and restart each time it updated.

There are lots of nice features in pdf-tools but I’ll just mention the ones I use most often. You can search pdf files like normal buffers, but the enhanced search tool swiper doesn’t work with pdf-tools so I set C-s to call the normal isearch when in this mode.

You can also make annotations in pdf-tools and I set my configuration above so that when an annotation (like highlighting some text) is created, a buffer opens prompting for a text note to go with the annotation. So for example, to highlight a comment on some text I

  1. Select the text in the pdf (mouse required for this unfortunately)
  2. Use C-c C-a h to highlight it yellow
  3. Type some notes in the annotation buffer that pops up and use C-c C-c to complete the annotation.

Other useful annotations are C-c C-a t and then mouse click to add a text note somewhere to the pdf page, C-c C-a o to strike-through text, and C-c C-a D and then click to delete an annotation.

Saving the pdf buffer as normal saves all the annotations, and they will be readable in any PDF viewer so this works well when collaborating with the unenlightened!

Advertisement

Tree-style directory views in dired with dired-subtree

By default, Emacs’ file browser/manager dired usually presents you with a flat list of files in a given directory. Entering a subdirectory then opens a new buffer with the listing of the subdirectory. Sometimes you might want to be able to see the contents of the subdirectory and the current directory in the same view. Many GUI file browsers visualise this with a tree structure with nodes that can be expanded or collapsed. In Emacs there is a built-in function dired-insert-subdir that inserts a listing of the subdirectory under the cursor, at the bottom of the current buffer instead of in a new buffer, but I’ve never found that very helpful.

The dired-subtree package (part of the magnificent dired hacks) improves on this by allowing you to expand subdirectories in place, like a tree structure. To install the package, use the following code: 

(use-package dired-subtree
  :config
  (bind-keys :map dired-mode-map
             ("i" . dired-subtree-insert)
             (";" . dired-subtree-remove)))

This sets up the keybinds so that in dired, hitting i on a subdirectory expands it in place with an indented listing. You can expand sub-subdirectories in the same way, and so on. Hitting ; inside an expanded subdirectory collapses it.

Happily, some of my other favourite tools from dired hacks like dynamically narrowing the directory listing or copying and pasting files work as you would want in these expanded subdirectories.