/pdf-layer

Private layer including 'image-roll' support for pdf-tools

Primary LanguageEmacs Lisp

PDF layer

img/pdf.png

Table of Contents

Description

This layer enables support for PDF with the pdf-tools package and adds image-roll support. Additionally, it adds support for the alternative vimura-server, providing additional features like arrow annotations and EPUB support.

According to the official repository:

“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.”

Features:

  • Searching and slicing with occur.
  • Show document headings in outline buffer.
  • Manipulate annotations.
  • Fit PDF to screen.
  • Arrow annotations
  • EPUB support

Install

Vimura server

After installing pdf-tools from the instructions in the sections below, the vimura server can be installed using:

pip install --user vimura-server

After installing the vimura server, you can use it via M-x pdf-tools-toggle-server. The vimura server provides extra features like EPUB support (just open an EPUB file after activating the server), and arrow annotations (using C-M-mouse-drag-1).

Prerequisites

Linux is the only operating system officially supported, but it’s possible to use pdf-tools on macOS as well, and possibly on other Unix flavors.

You’ll need to install a few libraries. Check the instructions on pdf-tools page. Note that compiling from source might not be necessary, as the documentation states.

If you use a Debian based system such as Ubuntu, you can skip this step, as pdf-tools installation asks whether you want it to try to download automatically all dependencies using apt-get.

Clone

Simply clone this repo to a directory named pdf in your .emacs.d/private directory using the following command:

git clone git@github.com:dalanicolai/pdf-layer.git ~/.emacs.d/private/pdf

then follow instructions below.

Dotfile

After installing the dependencies, add this to your ~/.spacemacs.

(setq-default dotspacemacs-configuration-layers '(pdf))

After that, syncronize your configuration with SPC f e R. This will pop up a window showing the compilation process.

If everything goes right, the compilation won’t display any error and you will be able to see PDFView (instead of DocView) on the spaceline after opening a pdf file.

If the compilation run successfully but you get Error (use-package): pdf-tools :config: No executable `epdfinfo' found, try restarting Spacemacs (issue).

If the compilation does not run successfully, you should confirm whether all dependencies are properly installed and run the command pdf-tools-install.

Usage

From within a pdf buffer, press c to activate displaying on an image-roll. Use SPC m . to activate the pdf-tools transient state. The key bindings that the transient displays can be also accessed using SPC m. The navigation key bindings can be used directly.

Try out opening the outline (O). The outline window shows the structure of the pdf, displaying all headings.

You can set annotations by selecting regions and right clicking on the buffer. Additionally, all annotation related functions can be accessed with SPC m a.

Searching with occur can be done by using pdf-occur (SPC m s s).

Tips:

  • You’ll probably want to use pdf-view-set-slice-from-bounding-box (bound to SPC m s b) This command trims the blank parts of the lateral margins, making the useful portion larger.
  • The layer uses the package pdf-view-restore to store and restore last-visited

pages. By default the information is stored in the directory of the viewed document (so it can get lost if you use e.g. Calibre / calibredb.el for your document management). If you would like the information to get stored in a different location then set the variable pdf-view-restore-filename to the path of the filename to use. Alternatively you can (additionally) use Emacs its bookmarks system to store and revisit (SPC f b for both) any location manually.

Known Issues

Due to image-mode=’s behaviour, the =pdf-tools buffer might go back to the first page after switching windows. If this happens, you can quickly go back to the previous page in history with pdf-history-backward (`` in Evil state and B in Emacs state.)

Key bindings

If you use Emacs editing style, check the key bindings at the pdf-tools page.

PDF View

Key bindingDescription
Navigation
M-SPC or s-M-SPCpdf-tools transient state
0/$Left/right full scroll
JMove to next page
KMove to previous page
uScroll page up
dScroll page down
ggGo to the first page
GGo to the last page
gtGo to page
glGo to label (usually the line as printed)
C-uScroll up
C-dScroll down
``Go to last page in the history
[History back
]History forward
mSet mark
'Go to mark
yYank selected region
Search
/Search forward
?Search backward
Actions
oFollow link
OShow outline
rRefresh file
Zoom
+/-Zoom in/out
zrReset zoom

For evil users: Note that the search keys activate isearch, which works differently from the default Evil search. To go to the next match, use C-s.

Leader keys

Key bindingDescription
Slicing
SPC m s mSet slice using mouse
SPC m s bSet slice from bounding box
SPC m s rReset slice
Annotations
SPC m a aCreate highlight annotation (using the keyboard)
SPC m a dDelete annotation (using the keyboard)
SPC m a DDelete annotation (select it with mouse)
SPC m a aList all attachments in a dired buffer
SPC m a hHighlight visual selection
SPC m a lList all annotations
SPC m a mAdd markup annotation to visual selection
SPC m a oStrikeout visual selection
SPC m a sAdd squiggly to visual selection
SPC m a tAdd annotation text
SPC m a uUnderline to visual selection
Fit image to window
SPC m f wFit width to window
SPC m f hFit height to window
SPC m f pFit page to window
Other
SPC m nToggle night view mode
SPC m sRun pdf-occur
SPC m pDisplay print version

Outline buffer mode

Key bindingDescription
S-tabExpand all trees (Cycle trees for >= Emacs 28)
RETFollow link
M-RETFollow link and close outline window
oGo to pdf view window
``Move to the heading correspondent to the current page
''Move to the heading correspondent to the current page
fGo to selected heading without leaving outline buffer
FEnable follow mode
qQuit
QQuit and kill outline buffer

Note that you can use also typical Vim keys such as j and G.

Annotation list mode

Key bindingDescription
dMark for deletion
xApply action for marked items
uUnmark item
qQuit

Occur mode

Key bindingDescription
qQuit
gRefresh buffer
rRefresh buffer
SPC m t fToggle follow mode (next-error-follow-minor-mode)