213 lines
10 KiB
Org Mode
213 lines
10 KiB
Org Mode
#+TITLE: PDF layer
|
||
|
||
#+TAGS: layer|reader
|
||
|
||
[[file:img/pdf.png]]
|
||
|
||
* Table of Contents :TOC_5_gh:noexport:
|
||
- [[#description][Description]]
|
||
- [[#features][Features:]]
|
||
- [[#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 PDF with 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
|
||
|
||
** 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 macOS 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))
|
||
#+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 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 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 |
|
||
| ~C-o~ or ~[~ | History back |
|
||
| ~C-i~ or ~]~ | History forward |
|
||
|----------------------+-------------------------------------------|
|
||
| *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 |
|