TLDR: These are personal notes on org-noter, a package I've recently discovered for writing Org notes that are kept in sync with documents such as pdf, Epub and Word. It's a useful tool for tracking research papers and writing comments on textbooks.

Why

Most pdf reading tools allow for annotation and highlighting. Research literature management tools, such as Mendeley, have the advantage that notes are always synced with documents, saved in the cloud and shared across devices, but the drawback is that the interface to write notes is usually primitive, and notes are cumbersome to search and share. Ideally one wants a note-taking solution with all the benefits but none of the drawbacks. Searching and sharing is easy if notes are kept in plain text documents, such as with Emacs' Org-Mode. Plain text files are also easy to backup in the cloud, and can be edited in any text editor. What is missing from the vanilla Org-mode solution, the syncing between notes and documents, is exactly what Org Noter provides.

How to set it up

For clarity, I will refer to document as being any research paper that I wish to annotate. I call file the plain text file written in Org, where notes are kept.

Any Org file can be used for notes. On any Org file, running M-x org-noter will prompt for a path to document one wishes to annotate, or open the document associated with an existing annotation. On any document, running M-x org-noter will search for possible Org files that are already tracking the document and then either jump to existing notes, or prompt for a file.

Installation

Setting up org-noter starts with the installation. The easiest way being a call to use-package.

(use-package org-noter
  :after org
  :ensure t)

For Spacemacs users, add org-noter to dotspacemacs-additional-packages, to avoid downloading org-noter at every startup.

Configuration

Org noter defines a default note file, where new headings are included for documents that do not have a file associated with them. By default this file is called Notes.org. Because I don't like files that start with capitals, I rename it to notes.org. Org noter also requires a search path (or multiple) to search for document notes when M-x org-noter is called from a pdf document. By default, that is ~/Documents, but I prefer to have it in a dedicated version controlled directory ~/org/Research-Notes.

(setq org-noter-default-notes-file-names '("notes.org")
      org-noter-notes-search-path '("~/org/Research-Notes/notes"))

For aesthetic reasons I like to keep an empty line between headings and content in Org files. To tell org-noter to do that when creating new notes, I set:

(setq org-noter-separate-notes-from-heading t)

Other configuration options can be found under M-x customize-group org-noter. Both installation and configuration can be grouped together under a single call to use-package:

(use-package org-noter
    :after org
    :ensure t
    :config (setq org-noter-default-notes-file-names '("notes.org")
                  org-noter-notes-search-path '("~/org/Research-Notes")
                  org-noter-separate-notes-from-heading t))

Usage

As mentioned previously, org-noter keeps notes and documents in sync. That means that we can call org-noter from either notes and documents, and the package will initiate the “sync”. Once we call M-x org-noter, we start a “annotation session”. What this means is that document and org file are opened side-by-side, both in indirect buffers, and the indirect org file buffer is narrowed down to a heading specific to the document. The heading is tagged with a property NOTER_DOCUMENT, specifying the path to the document. Killing any of these indirect buffers will cause the org-noter “session” to terminate.

To get an overview of how things work, there's a screencast available from the maintainer (unfortunately with no auxiliary explanation so if not familiar with the package one has to use a bit of imagination to put all the pieces together).

Using an org-noter session is simple. Within a session, we may at any given time press i within the document buffer to create a new subheading in the note file and jump to it. When done, we jump back to the document and continue reading, or quit the session with q. To navigate between notes within the same document, org-noter binds C-M-p and C-M-n in both buffers of a session. To navigate between document pages, org-noter binds M-p and M-n, also in both document and file buffers. It's recommended to use these keybindings instead of the default ones so that org-noter can keep locations in the document and file synced.

It is possible to have multiple sessions simultaneously, as each session fires a new Emacs frame.

Combining org-noter and org-ref

With org-noter and org-ref installed, I find it easier to add a reference from the org-ref insert cite-link interface C-c ] in the current Org file I'm working with, then pressing RET with the cursor on top of the citation link and open the document with PDFView from the PDFtools package. On a file with multiple references, I can also jump to the notes adding the following to org-ref-helm-user-candidates:

(defun org-ref-noter-at-point ()
      "Open the pdf for bibtex key under point if it exists."
      (interactive)
      (let* ((results (org-ref-get-bibtex-key-and-file))
             (key (car results))
             (pdf-file (funcall org-ref-get-pdf-filename-function key)))
        (if (file-exists-p pdf-file)
            (progn
              (find-file-other-window pdf-file)
              (org-noter))
          (message "no pdf found for %s" key))))

(add-to-list 'org-ref-helm-user-candidates 
             '("Org-Noter notes" . org-ref-noter-at-point))

I know that org-ref also has its own “notes” mechanism, but I haven't set it up so I cannot give a detailed comparison. The difference I see is that org-ref does not provide a sync to the pdf, but it adds all of the research paper information as extra org properties and gives the heading a more meaningful name.

It is, though, possible to have org-ref and org-noter configured to target the same notes files by setting the appropriate org-ref variables:

(setq org-ref-bibliography-notes "~/org/Research-Notes/notes.org")
(setq org-ref-notes-function #'org-ref-notes-function-one-file)

It should also be possible to tweak org-ref to add a NOTER_DOCUMENT property upon creation of a note, so we could start org-noter right away. Perhaps this has even been done already, but I haven't searched around.

Managing multiple documents

When calling org-noter from a document that does not have notes associated with it yet, org-noter will either create a new note at the default document notes.org or prompts for a filename (if called with an universal argument). I prefer to keep notes separately in different documents, so I call C-u M-x org-noter and accept the default suggestion, which is a file with the same name as the pdf but with .org extension. I'm thinking of experimenting with a “notes as captures for later refiling” workflow, but I haven't played around with org-noter so long to decide on a definite workflow yet.

As a warning about managing multiple documents, it is important to keep in mind is that the org-noter sync is based on filenames, and although changing names of the org files is OK as long as they are situated within the search directory, changing the name of the pdf document will break the sync.

In Mendeley, I organise pdf filenames as FirstAuthorLastName_Year.pdf, so I've committed to sticking to this personal convention.

Comments

It bugs me that pdftools, despite all of its merits, does not support retina on MacOS, so reading documents without zooming is a bit annoying. To make the experience somewhat more pleasant I use golden-ratio, but it's more of a workaround than a proper solution.

Org-noter also messes a bit with window switching muscle memory because it opens a new frame. I hardly use more than 1 frame, as I have more of a layouts workflow.

In general, much to explore before I make it a complete part of my workflow, but looks promising so far.