* This is a refactor of the c1-g* fork done collaboratively by [[https://github.com/petermao/org-noter][petermao]] and [[https://github.com/dmitrym0/org-noter-plus-djvu][dmitrym0]]
In essence, this is close to the original weirdNox (Gonçalo Santos) version that you find on MELPA with the refactoring that c1-g implemented.
djvu and epub support have also been advanced by c1-g, but we have not tested any of that code. See [[https://github.com/c1-g/org-noter-plus-djvu/blob/master/README.org][Charlie Gordon's README]] ([[file:docs/README-djvu.org]] in this repo).
Prior to our work, the main new feature for PDF users was 2-D precise notes (introduced by Ahmed Shariff, which can be inserted in two ways:
Standard notes can also be inserted in two ways:
** Stock vs refactored note insertion
more consistent use of selected text in title or body
more consistent primary default title (short-selected-text)
more consistent secondary default title ("Notes for page
avoids having different notes with the same heading
In Stock org-noter, repeated TAB's give multiple notes. In this refactor, new notes in the same location with the same title are not made, but selected text is added to the note body. For now, precise notes are excepted from this rule.
long text-selections are enclosed in #+BEGIN_QUOTE...#+END_QUOTE
short text-selections are enclosed in ``...'' (LaTeX style) when they are not used as the title of the note.
short/long text-selections are differentiated by the custom variable =org-noter-max-short-selected-text-length= (default: 80 char)
In Stock org-noter, long selections are those with more than 3 lines.
NEW: Highlighting of selected text
Default setting is customizable, see =org-noter-highlight-selected-text=. Calling insertions with a non-nil prefix (eg, =C-u=) toggles this setting for individual note insertions.
NEW: multicolumn precise-notes defined by property NUM_COLUMNS
Implements issue #153 in weirdNox/org-noter by adding =org-noter-pdf-convert-to-location-cons= to =org-noter--convert-to-location-cons-hook=, where a "virtual" vertical location is calculated by dividing the page into equal width columns. This is not a perfect solution, and is probably best for low-integer numbers of columns, since the page is just divided evenly into =NUM_COLUMNS= vertical strips.
This can be set using =org-set-property-and-value=, but eventually we will write a user function to prevent users from mistyping the name of the property (=NUM_COLUMNS=).
*** Stock | | insert-note =i= | precise note =M-i= | no-questions =C-i, TAB= | |-----------------+--------------------------------+---------------------------+-------------------------| | title prompt? | Y | Y | N | | default title 1 | prior note by location | selected-text | N/A | | default title 2 | "Notes for page #" | "Notes for page # x y" | "Notes for page #" | | new note | with new title | always | always | | body | selected-text on existing note | selected-text (> 3 lines) | none | |-----------------+--------------------------------+---------------------------+-------------------------|
* Refactored | | insert-note | precise note | no-questions | |---------------------+---------------------------+---------------------------+---------------------------| | title prompt? | Y | Y | N | | default title 1 | short-selected-text | short-selected-text | short-selected-text | | default title 2 | "Notes for page #" | "Notes for page # x y" | "Notes for page #" | | new note | with new title | always | with new title | | body | selected-text (not title) | selected-text (not title) | selected-text (not title) | |---------------------+---------------------------+---------------------------+---------------------------| | highlight selection | user setting/toggle | user setting/toggle | user setting/toggle | * Customizations Out of respect for the existing user base of =org-noter=, almost all of the user-interface features of this fork remain the same those of as the original =org-noter=. However, users may be interested in our variations on the theme of Gonçalos Santos. Peter's mods In order of frequency, I use precise notes the most, standard notes next and no-questions notes the least, so I have bound keys to reflect those preferences with =i= for precise notes, =TAB= for standard notes; for no-questions (no-prompt) notes, =I= is for precise notes and =M-i= for standard notes.:
(with-eval-after-load 'org-noter
(define-key org-noter-doc-mode-map (kbd "i") 'org-noter-insert-precise-note)
(define-key org-noter-doc-mode-map (kbd "C-i") 'org-noter-insert-note)
(define-key org-noter-doc-mode-map (kbd "I") 'org-noter-insert-precise-note-toggle-no-questions)
(define-key org-noter-doc-mode-map (kbd "M-i") 'org-noter-insert-note-toggle-no-questions))
#+end_src
For navigation, I use =..-sync-..-note= more than =..-sync-..-page-..=, so I
bound the =note= commands to the easier-to-type =M-[p.n]= bindings and the
less-used =page-..= commands to the harder-to-type =C-M-[p.n]= bindings.
#+begin_src elisp
(with-eval-after-load 'org-noter
(define-key org-noter-doc-mode-map (kbd "M-p") 'org-noter-sync-prev-note)
(define-key org-noter-doc-mode-map (kbd "M-.") 'org-noter-sync-current-note)
(define-key org-noter-doc-mode-map (kbd "M-n") 'org-noter-sync-next-note)
(define-key org-noter-doc-mode-map (kbd "C-M-p") 'org-noter-sync-prev-page-or-chapter)
(define-key org-noter-doc-mode-map (kbd "C-M-.") 'org-noter-sync-current-page-or-chapter)
(define-key org-noter-doc-mode-map (kbd "C-M-n") 'org-noter-sync-next-page-or-chapter)
(define-key org-noter-notes-mode-map (kbd "M-p") 'org-noter-sync-prev-note)
(define-key org-noter-notes-mode-map (kbd "M-.") 'org-noter-sync-current-note)
(define-key org-noter-notes-mode-map (kbd "M-n") 'org-noter-sync-next-note)
(define-key org-noter-notes-mode-map (kbd "C-M-p") 'org-noter-sync-prev-page-or-chapter)
(define-key org-noter-notes-mode-map (kbd "C-M-.") 'org-noter-sync-current-page-or-chapter)
(define-key org-noter-notes-mode-map (kbd "C-M-n") 'org-noter-sync-next-page-or-chapter))
#+end_src
In the original code, the tooltip arrow on PDFs is *Orange-Red on White*,
which works fine when the arrow is always on the left side of the page. I
found that with the 2D precise notes introduced by Ahmed Shariff, I sometime
had trouble locating the arrow as I navigated through my notes. The *Black
on Cyan* color-scheme that I use is more jarring, hence easier to locate.
#+begin_src elisp
(with-eval-after-load 'org-noter
(setq org-noter-arrow-background-color "cyan"
org-noter-arrow-foreground-color "black"))
#+end_src* Dmitry's mods * Features New
Use pdf-view-current-pagelabel to use the page label instead of page in default titles
new function/hook =...-pretty-print-location-for-title=
Customizable tooltip arrow colors
Text-selection higlighting: customizable default behavior, toggle =...-highlight-selected-text= with =C-u= prefix on note-insertion commands.
Rudimentary support for multicolumn PDFs with inheritable =NUM_COLUMNS= property. See =...-pdf-convert-to-location-cons=
*** Wishlist
Bind M-
Make background of arrow transparent (see org-noter--show-arrow) maybe https://emacs.stackexchange.com/questions/45588/how-to-make-tooltip-background-transparent
Dedicated insert-selected-text-into-page-note
Internationalize precise notes to handle right-to-left languages. ** Bugs *** to fix
Sometimes (when?) M-p doesn't pick up the containing note-at-point right away (or at all), requiring user to manually type in the (existing) title
With NUM_COLUMNS > 1, point in notes document doesn't land in the correct place
With NUM_COLUMNS > 1, columns don't necessarily start at horizontal positions k/NUM_COLUMNS for k \in {1,..,NUM_COLUMNS}. We need to write a user interface that builds a list of horizontal fractions to delimit the columns.
*** fixed
vertically stacked doc/notes layout fixed
=org-noter-sync-next-page-or-chapter= navigation fixed
Navigating up from a nested precise note lands in the prior note at the next level up (eg level 3 -> level 2). page notes behave properly.
[file:org-noter-core.el:2179]
=(org-element-property :begin (org-noter--get-containing-element))= returns
the begin of the element one level up when the current note location is of
the form (<page#>
It will be one of these two:
*** start-stop
*** layout
*** note-insertion
*** navigation-display
*** other