Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/weirdNox/org-noter

Emacs document annotator, using Org-mode
https://github.com/weirdNox/org-noter

annotate convenience documents elisp emacs interleaved notes org-mode pdf sync

Last synced: 3 months ago
JSON representation

Emacs document annotator, using Org-mode

Awesome Lists containing this project

README 

        
[[https://melpa.org/#/org-noter][file:https://melpa.org/packages/org-noter-badge.svg]]

[[https://stable.melpa.org/#/org-noter][file:https://stable.melpa.org/packages/org-noter-badge.svg]]

* Org-noter - A synchronized, Org-mode, document annotator

After using Sebastian Christ's amazing [[https://github.com/rudolfochrist/interleave][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 [[http://orgmode.org/][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 @@html:@@i@@html:@@ 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. [[#diff][View some differences here.]]



Org-noter is compatible with [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Document-View.html][DocView]], [[https://github.com/politza/pdf-tools][PDF Tools]], and [[https://github.com/wasamasa/nov.el][Nov.el]]. 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.



** Features

- Easy to use annotation interface :: Just press @@html:@@i@@html:@@ in the

     document buffer and annotate away!



- Keep your notes in sync with the document :: When you take a note by pressing

     @@html:@@i@@html:@@, 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-location~ is 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, [[#custom][read more here]].



- Keep your notes organized :: You may arrange your notes however you want! You can create groups and

     nest notes (and even nest documents inside other documents)!



- Annotate ~org-attach~'ed files :: If you have any attached files, it will let you choose one as

     the document to annotate.



Many of these features are demonstrated in the screencast, so take a look if you are

confused!



** Installation

*** MELPA

This package is [[https://melpa.org/#/org-noter][available from MELPA]], so if you want to install it and have added MELPA to

your package archives, you can run

@@html:@@M-x@@html:@@ ~package-install~ @@html:@@RET@@html:@@ ~org-noter~



*** Manual installation

You can also install it manually, using =package.el=.

1. Download =org-noter.el=

2. Open it

3. Run @@html:@@M-x@@html:@@ ~package-install-from-buffer~ @@html:@@RET@@html:@@



** Usage

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 @@html:@@M-x@@html:@@ ~org-noter~ inside!

  On the first run, it will ask you for the path of the document and save it in a

  property. By default, it will also let you annotate an attached file [[https://orgmode.org/manual/Attachments.html][(org-attach documentation)]].



This will open a new dedicated frame where you can use [[#keys][the keybindings described here]].



More generally, there are two modes of operation. You may run

@@html:@@M-x@@html:@@ ~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 :: Run @@html:@@M-x@@html:@@ ~org-noter~ when viewing a

                   document (eg. PDF, epub...).



                   This will try to find the respective notes file automatically. It will

                   search in all parent folders and some specific folders set by you. See

                   ~org-noter-default-notes-file-names~ and ~org-noter-notes-search-path~

                   for more information.



There is, of course, more information in the docstrings of each command.



** Screencast

[[https://www.youtube.com/watch?v=Un0ZRXTzufo][Watch the screencast here!]]



Note that this package has had some updates since this screencast was made, so, while the

core functionality is the same, there may be some UX and feature differences.



The files used to make this screencast are shipped with the package, so you can try this

package even without creating the notes.



** Customization @@html:@@

There are two kinds of customizations you may do:

1. Global settings, affecting every session

2. Document-specific settings, which override the global settings



The *global settings* are changed with either the [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Easy-Customization.html#Easy-Customization][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 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* (check the docstrings to learn how to make the changes

permanent, or revert to the default):

- You may set a start location for this document, by using ~org-noter-set-start-location~.



- To automatically resume from where you left, use ~org-noter-set-auto-save-last-location~.



- With ~org-noter-set-notes-window-behavior~, you may change /when/ the notes window pops

  up.



- With ~org-noter-set-notes-window-location~, you may change /where/ the notes window pops

  up.



- ~org-noter-set-doc-split-fraction~ will ask you for the fraction of the frame that the document window

  occupies when split.



- ~org-noter-set-hide-other~ will toggle whether or not it should hide headings not

  related to the executed action.



- ~org-noter-set-closest-tipping-point~ will set the closest note tipping point. Also

  check the docstring of the variable ~org-noter-closest-tipping-point~ in order to better

  understand the tipping point.



** Keybindings and commands @@html:@@

:PROPERTIES:

:CUSTOM_ID: keys

:END:

| Key                                | Description                | Where?                    |

| @@html:@@i@@html:@@     | Insert note                | Document buffer           |

| @@html:@@M-i@@html:@@   | Insert precise note        | Document buffer           |

| @@html:@@q@@html:@@     | Kill session               | Document buffer           |

| @@html:@@M-p@@html:@@   | Sync previous page/chapter | Document and notes buffer |

| @@html:@@M-.@@html:@@   | Sync current page/chapter  | Document and notes buffer |

| @@html:@@M-n@@html:@@   | Sync next page/chapter     | Document and notes buffer |

| @@html:@@C-M-p@@html:@@ | Sync previous notes        | Document and notes buffer |

| @@html:@@C-M-.@@html:@@ | Sync selected notes        | Document and notes buffer |

| @@html:@@C-M-n@@html:@@ | Sync next notes            | Document and notes buffer |



You can use the usual keybindings to navigate the document

(@@html:@@n@@html:@@, @@html:@@p@@html:@@,

@@html:@@SPC@@html:@@, ...).



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 or

annotations (or both!) 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.



** Why a rewrite from scratch? Why not contribute to the existing Interleave package?

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!



*** Non-exhaustive list of differences from Interleave @@html:@@

:PROPERTIES:

:CUSTOM_ID: diff

:END:

**** New features

- Each session is isolated, which means that it has its own frame with indirect buffers

  - Makes it possible to have several sessions simultaneously open

  - Doesn't narrow the original buffer, which continues completely accessible

- Has precise notes (attached to a section of a page)

- Also supports nov.el

- Skeleton extraction (outline and/or annotations)

- Being able to use the closest previous note when no notes are present on the current

  page

- Closing all notes not related to the notes present in the current view

- Possibility of overriding some global settings in each document or session



**** Some annoyances fixed

- 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.



*** Changes to make in order to be compatible with documents created by Interleave

This package only works like the multi-pdf mode of Interleave - you can't open a session

without having a parent headline.



For compatibility with existing notes made with Interleave, you can do one of two things:

- Change the following property names inside the your documents:

  | Old                    | New              |

  |------------------------+------------------|

  | =INTERLEAVE_PDF=       | =NOTER_DOCUMENT= |

  | =INTERLEAVE_PAGE_NOTE= | =NOTER_PAGE=     |



- Set these variables on your init file:

  #+BEGIN_SRC emacs-lisp

(setq org-noter-property-doc-file "INTERLEAVE_PDF"

      org-noter-property-note-location "INTERLEAVE_PAGE_NOTE")

  #+END_SRC



** Acknowledgments

I must thank [[https://github.com/rudolfochrist][Sebastian]] for the original idea and inspiration. Also, many thanks to everyone who

contributed more ideas, reported bugs and submitted PRs :)