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.”
- Searching and slicing with
occur. - Show document headings in outline buffer.
- Manipulate annotations.
- Fit PDF to screen.
- Arrow annotations
- EPUB support
After installing pdf-tools from the instructions in the sections below, the vimura server can be installed using:
pip install --user vimura-serverAfter 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).
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.
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/pdfthen follow instructions below.
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.
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 toSPC 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.
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.)
If you use Emacs editing style, check the key bindings at the pdf-tools page.
| 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 |
[ | History back |
] | History forward |
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.
| 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 a | Create highlight annotation (using the keyboard) |
SPC m a d | Delete annotation (using the keyboard) |
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 |
| Key binding | Description |
|---|---|
S-tab | Expand all trees (Cycle trees for >= Emacs 28) |
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.
| Key binding | Description |
|---|---|
d | Mark for deletion |
x | Apply action for marked items |
u | Unmark item |
q | Quit |
| Key binding | Description |
|---|---|
q | Quit |
g | Refresh buffer |
r | Refresh buffer |
SPC m t f | Toggle follow mode (next-error-follow-minor-mode) |