spacemacs/layers/+tools/pdf-tools/README.org

pdf-tools layer

• Description
  • Features:
• Install
  • Prerequisites
  • Dotfile
• Usage
• Known Issues
• Key bindings
  • PDF View
  • Leader keys
  • Outline buffer mode
  • Annotation list mode
  • Occur mode

Description

This layer enables support for the pdf-tools package.

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.

Install

Prerequisites

Linux is the only operating system officially supported, but it's possible to use pdf-tools on OS X 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.

Dotfile

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

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

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

Use SPC m . to activate the pdf-tools transient state. The keybindings that the transient displays can be also accessed using SPC m. The navigation keybindings 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 last visited page is not saved across Emacs sessions. If you want save it, use the bookmarks commands on SPC j b to save and go to a bookmark.

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 Binding	Description
Navigation
M-SPC or s-M-SPC	pdf-tools transient state
0/$	Left/right full scroll
J	Move to next page
K	Move to previous page
u	Scroll page up
d	Scroll page down
gg	Go to the first page
G	Go to the last page
gt	Go to page
gl	Go to label (usually the line as printed)
C-u	Scroll up
C-d	Scroll down
``	Go to last page in the history
m	Set mark
'	Go to mark
y	Yank selected region
Search
/	Search forward
?	Search backward
Actions
o	Follow link
O	Show outline
r	Refresh file
Zoom
+/-	Zoom in/out
zr	Reset 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 Binding	Description
Slicing
SPC m s m	Set slice using mouse
SPC m s b	Set slice from bounding box
SPC m s r	Reset slice
Annotations
SPC m a D	Delete annotation (select it with mouse)
SPC m a a	List all attachments in a dired buffer
SPC m a h	Highlight visual selection
SPC m a l	List all annotations
SPC m a m	Add markup annotation to visual selection
SPC m a o	Strikeout visual selection
SPC m a s	Add squiggly to visual selection
SPC m a t	Add annotation text
SPC m a u	Underline to visual selection
Fit image to window
SPC m f w	Fit width to window
SPC m f h	Fit height to window
SPC m f p	Fit page to window
Other
SPC m n	Toggle night view mode
SPC m s	Run pdf-occur
SPC m p	Display print version

Outline buffer mode

Key Binding	Description
S-tab	Expand all trees
RET	Follow link
M-RET	Follow link and close outline window
o	Go to pdf view window
``	Move to the heading correspondent to the current page
''	Move to the heading correspondent to the current page
f	Go to selected heading without leaving outline buffer
F	Enable follow mode
q	Quit
Q	Quit and kill outline buffer

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

Annotation list mode

Key Binding	Description
d	Mark for deletion
x	Apply action for marked items
u	Unmark item
q	Quit

Occur mode

Key Binding	Description
q	Quit
g	Refresh buffer
r	Refresh buffer