• BETTER ALTERNATIVE: VIMURA SERVER A better alternative to this mode is to use the [[https://pypi.org/project/vimura-server/][vimura server]]. To use the server with pdf-tools, install the [[https://github.com/dalanicolai/pdf-tools/tree/production][production branch of my pdf-tools fork]]. After you have installed the vimura server and the =production= branch of the pdf-tools fork, a command =pdf-tools-toggle-server= should be available. Use this command to switch to the =vimura= server. When using the vimura server you can add annotations using =C-M mouse-drag-1= (Ctrl-Alt left-button drag).

• pymupdf-mode.el Extend pdf-tools annotation capabilities via [[https://pymupdf.readthedocs.io/en/latest/][pymupdf]]

pymupdf-mode launches a python REPL in a comint buffer and imports the [[https://pymupdf.readthedocs.io/en/latest/][pymupdf]] library. Subsequently it uses elisp to send python commands to the comint buffer. At the moment it mainly provides a template for the user that can be completely modified (i.e. customized) using the excellent [[https://pymupdf.readthedocs.io/en/latest/][pymupdf]] documentation, especially its [[https://pymupdf.readthedocs.io/en/latest/faq.html#annotations][annotation]] section. Because pdf-tools recognizes these annotations naturally, the annotations are editable with pdf-tools which is awesome! [[./pymupdf-mode-demo.gif]]

Additionally, pymupdf contains functionality to quickly edit the pdf metadata (see [[Usage]])

** Comment The script has been tested on GNU/linux only, but it should work on any platform where python is installed.

The script is just a hack and things can act a little weird if not used in the correct way, especially when mixing pymupdf annotations with pdf-tools annotation functionality (although not much can go wrong).

** Related [[https://github.com/dalanicolai/pdf-continuous-scroll-mode.el][pdf-continuous-scroll-mode]] (HACK) \ [[https://github.com/dalanicolai/djvu2.el][djvu2]] (Experimental)

• Installation First install pymupdf by typing ~pip3 install pymupdf~ in a terminal. Although you could just clone this repository and load the script =pymupdf-mode.el=, it is recommended to install this package with a quelpa recipe (although this will overwrite any customizations on any package update).

  For editing metadata, clone [[https://github.com/dalanicolai/PyMuPDF-Utilities][this PyMuPDF-Utilities repo]], and customize the =pymupdf-utilities-examples/directory=. Writing the metadata might not work well when you use the ipython interpreter, in that case set the =pymupdf-meta-shell-interpreter= to your =python3= interpreter command.

  Activate the mode from within a pdf-tools buffer using =M-x pymupdf-mode= or use a hook (see Spacemacs subsection below)

** Spacemacs Spacemacs users can install the package by adding the following lines to the list of additional packages in their dotfile (although this will overwrite any customizations on any package update):

+begin_src elisp

 (pymupdf-mode :location (recipe
                          :fetcher github
                          :repo "dalanicolai/pymupdf-mode.el"))

+end_src

Subsequently load the package by placing the following line in the user-config section of your dotfile:

+begin_src elisp

 (with-eval-after-load 'pdf-view
   (require 'pymupdf-mode))

+end_src

• Usage Load the mode manually from within a pdf-tools buffer using =M-x pymupdf-mode=. Or to activate the mode automatically when opening a pdf document in pdf-tools add the following line to your dotfile:

  +begin_src elisp

  (add-hook 'pdf-view-mode-hook 'pymupdf-mode)

  +end_src

  Use the keybindings given below to create their respective annotation. The script is just elementary, it should be very straightforward for users to customize the functionality using the [[https://pymupdf.readthedocs.io/en/latest/faq.html#annotations][pymupdf annotation documentation]].

  Also the line annotation colors are customizable via M-x customize-group RET pymupdf-annot

  After adding any annotation, the file is saved automatically so that pdf-tools will reload the file automatically and show the annotation. Then pdf-tools can be used to edit the annotation. However, because editing annotations with pdf-tools modifies the buffer (instead of the file), adding more annotations is prevented until pymupdf mode is restarted. Simply use =M-x pymupdf-restart= to continue annotating with pymupdf.

  For editing metadata, simply from a pdf document's buffer, eval =M-x pymupdf-edit-metadata=. Edit the metadata in the buffer and press =C-c C-c= to attach it to the pdf document.

** Keybindings mouse-1 is left button mouse-3 is right button | =C-S-mouse-1= | pymupdf-draw-caret | | =C-S-drag-mouse-1= | pymupdf-draw-arrow | | =C-S-drag-mouse-3= | pymupdf-draw-free-text | *** Spacemacs (pdf-view-mode) | =, t c= | toggle pymupdf-mode |