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

#+TITLE: pdf-tools layer

[[file:img/pdf.png]]

* Table of Contents                                        :TOC_4_gh:noexport:
 - [[#description][Description]]
 - [[#install][Install]]
   - [[#prerequisites][Prerequisites]]
   - [[#dotfile][Dotfile]]
 - [[#usage][Usage]]
 - [[#known-issues][Known Issues]]
 - [[#key-bindings][Key bindings]]
   - [[#pdf-view][PDF View]]
   - [[#leader-keys][Leader keys]]
   - [[#outline-buffer-mode][Outline buffer mode]]
   - [[#annotation-list-mode][Annotation list mode]]
   - [[#occur-mode][Occur mode]]

* Description
This layer enables support for the [[https://github.com/politza/pdf-tools][pdf-tools]] package.

According to the official repository:

#+begin_quote
"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."
#+end_quote

Examples of features that =pdf-tools= provides:
- Use =occur= in the pdf file;
- Show all headings in a outline buffer;
- Manipulate annotations.

* 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 [[https://github.com/politza/pdf-tools#server-prerequisites][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=.

#+begin_src emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(pdf-tools))
#+end_src

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 ([[https://github.com/politza/pdf-tools/issues/31][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 [[https://github.com/politza/pdf-tools#some-keybindings][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 |