After using Sebastian Christ’s amazing Interleave package for some time, I got some ideas on how I could improve upon it, usability and feature-wise. So I created this package from scratch with those ideas in mind!
Org-Noter’s purpose is to let you create notes that are kept in sync when you scroll through the document, but that are external to it - the notes themselves live in an Org-mode file. As such, this leverages the power of Org-mode (the notes may have outlines, latex fragments, babel, etc…) while acting like notes that are made inside the document. Also, taking notes is very simple: just press i and annotate away!
Note: While this is similar to interleave, it is not intended to be a clone;
therefore, not every feature of the original mode is available! You may prefer using the
original, because this is a different take on the same idea. View some differences here.
Org-noter is compatible with DocView, PDF Tools, and Nov.el (very experimental!). These modes make it possible to annotate PDF, EPUB, Microsoft Office, DVI, PS, and OpenDocument.
On a personal note, if you annotate and read lots of PDFs, give PDF Tools a try! It is great.
- Easy to use annotation interface
- Just press i in the document buffer and annotate away!
- Keep your notes in sync with the document
- When you take a note by pressing i, it saves the location where you took it so it is able to show you the notes while you scroll, automatically!
- Easy navigation
- You may navigate your document as usual, seeing the notes buffer scroll and show you the respective notes; however, you may also navigate by notes, only seeing annotated pages/chapters.
- Isolated interface
- Each session has its own frame and the document and notes buffers are indirect buffers to the original ones. Killing any of these things will terminate your annotation session.
- Simultaneous sessions
- You may open as many annotation sessions as you wish, at the same time! The root heading of each document will be made read-only to prevent you from deleting a heading from an open session.
- Resume annotating from where you left
- When
org-noter-auto-save-last-locationis non-nil, it will save the last location you visited and pick it up when you start another session! You may also set this per-document, read more here. - Keep your notes organized
- You may arrange your notes however you want; you may even group them together inside headings!
Many of these features are demonstrated in the screencast, so take a look if you are confused!
This package is available from MELPA, so if you want to install it and have added MELPA to
your package archives, you can run
M-x package-install RET org-noter
You can also install it manually, using package.el.
- Download
org-noter.el - Open it
- Run M-x
package-install-from-bufferRET
If you want to give it a try without much trouble:
- Just have an Org file where you want the notes to go
- Create a root heading to hold the notes
- Run M-x
org-noterinside! On the first run, it will ask you for the path of the document and save it in a property.
This will open a new dedicated frame where you can use the keybindings described here.
More generally, there are two modes of operation. You may run
M-x org-noter:
- Inside a heading in an Org notes file
- This will associate that heading with a document and open a session with it. This mode is the one described in the example above.
- In a document (PDF, EPUB, …)
- This will try to find the respective notes file
automatically. To use this mode, open a document (eg. a PDF) and run
M-x
org-noter, then follow the instructions in the minibuffer.
There is, of course, more information in the docstrings of each command.
The files used to make this screencast are shipped with the package, so you can try it even without creating the notes.
There are two kinds of customizations you may do:
- Global settings, affecting every session
- Document-specific settings, which override the global settings
The global settings are changed with either the customization interface from Emacs or
directly in your init file. To find which settings are available, you may use the
customization interface or you may just read org-noter.el.
The best way to set document-specific settings is by using the utility commands provided (list below). In order to use them, you need an open a session. The commands may change the settings for that session only (not surviving restarts), or for every session with that document.
List of utility commands:
- You may set a start location for this document, by using
org-noter-set-start-location. - If, instead, you want to automatically resume from where you left, use
org-noter-set-auto-save-last-location. With a prefix argument, it removes the local setting and uses the default. - With
org-noter-set-notes-window-behavior, you may change when the notes window pops up for this session. With a prefix argument, it becomes persistent for this document. - With
org-noter-set-notes-window-location, you may change where the notes window pops up for this session. With a prefix argument, it becomes persistent for this document. org-noter-set-hide-otherwill toggle whether or not it should hide headings not related to the executed action for this session. Check the docstring for more information.
| Key | Description | Where? |
| i | Insert note | Document buffer |
| M-i | Insert precise note | Document buffer |
| q | Kill session | Document buffer |
| M-p | Sync previous page/chapter | Document and notes buffer |
| M-. | Sync current page/chapter | Document and notes buffer |
| M-n | Sync next page/chapter | Document and notes buffer |
| C-M-p | Sync previous notes | Document and notes buffer |
| C-M-. | Sync selected notes | Document and notes buffer |
| C-M-n | Sync next notes | Document and notes buffer |
You can use the usual keybindings to navigate the document (n, p, SPC, …).
There are two types of sync commands:
- To sync a page/chapter, means it will find the [previous|current|next] page/chapter and show the corresponding notes for that page/chapter; as such, it will always pop up the notes buffer, if it does not exist. This type of command is in relation to the current page/chapter in the document.
- To sync the notes, means it will find the [previous|current|next] notes and go to the corresponding location on the document. So, you need to have the notes window open, because this type of commands is in relation to the selected notes (ie, where the cursor is).
When using PDF Tools, the command org-noter-create-skeleton imports the PDF outline as
notes, and it may be used, for example, as a starting point.
You may also want to check the docstrings of the functions associated with the keybindings, because there is some extra functionality in some.
Doing a refactor on a foreign codebase takes a long time because of several factors, like introducing the ideas to the owner (with which he may even disagree), learning its internals, proposing pull requests, more back and forth in code review, etc…
Besides, I like doing things from scratch, not only because it expands my skills, but also because it is something I find very rewarding!
Note that this list is not exhaustive!There are new features, such as each session having its own frame and the possibility of having several sessions simultaneously (even of the same document and/or from the same notes file!). Aside from that, using indirect buffers is also great, because the narrowing is only applied in the indirect one, not on the original, so you may continue working on the rest of the buffer when interleaving.
Also, this is as if you always used the multi-pdf mode of the original - you can’t open a session without having a parent headline.
For compatibility with existing notes made with Sebastian’s Interleave, you must change the following variables like this:
(setq org-noter-property-doc-file "INTERLEAVE_PDF"
org-noter-property-note-location "INTERLEAVE_PAGE_NOTE")One of the reasons of rewriting from scratch is to fix some bugs, like:
- Notes not sorted
- Notes not synced when executing different page change commands, eg. goto-page or beginning-of-buffer
- Sometimes it would start narrowing other parts of the buffer, giving errors when trying to go to notes.
I must thank Sebastian for the original idea and the inspiration!