branch: externals/org-remark
commit bc051adab9ff4973370fb8e2e5da43a020681ee7
Author: Noboru Ota <m...@nobiot.com>
Commit: Noboru Ota <m...@nobiot.com>
doc: Add some clarification to readme, etc.
---
README.org | 22 +++++++----
marginalia.org | 34 ++++++++++++++++-
org-marginalia.el | 112 +++++++++++++++++++++++++++++++-----------------------
3 files changed, 110 insertions(+), 58 deletions(-)
diff --git a/README.org b/README.org
index f46f8beebf..9db936cfa1 100644
--- a/README.org
+++ b/README.org
@@ -6,18 +6,22 @@
# Note: I use the readme template that alphapapa shares on his GitHub repo
<https://github.com/alphapapa/emacs-package-dev-handbook#template>. It works
with the org-make-toc <https://github.com/alphapapa/org-make-toc> package,
which automatically updates the table of contents.
-Org-marginalia lets you highlight text, and write margin notes (marginalia)
for any text file in a separate Org file.
+Org-marginalia lets you highlight text, and write margin notes (marginalia)
for any text file in a separate Org file. Refer to the screenshots below for a
teaser of what it can do.
+
+Technically, it implements the highlighting feature solely with text
properties, and avoids overlays. This is done in light of oft-mentioned
performance degradation with the latter.
+
+Personally I have never experienced such performance issues with overlays;
nevertheless, given that we might have many highlighted text regions in a
single file, I thought I would take this as an opportunity to take advantage of
text properties.
* Screenshots
[[./resources/images/2020-12-22T141331-OM-screen-shot-01.png]]
-*Figure 1*. Left: main note; Right: margin notes in a marginalia file
+*Figure 1*. Left: main note with some text highlighted in green; Right: margin
notes in a marginalia file
[[./resources/images/2020-12-22T141331-OM-screen-shot-02.png]]
*Figure 2*. It automatically adds the standard Org Mode link to margin notes,
so it works well with Org-roam's backlinks
[[./resources/images/2020-12-22T141331-OM-screen-shot-03.png]]
-*Figure 3*. Main note can be any text files. Left: an ~.el~ file; Right:
marginalia file
+*Figure 3*. Main note can be any text files. Left: an ~.el~ file with a
highlight; Right: marginalia file
* Contents :noexport:
:PROPERTIES:
@@ -40,9 +44,11 @@ Org-marginalia lets you highlight text, and write margin
notes (marginalia) for
:END:
** Manual
-This package is not available on MELPA. Manual installation is required.
Ensure to have Org Mode 9.4 or later (tested on 9.4.2). This package uses
~org-collect-keywords~, which does not exist in an earlier version.
+This package is not available on MELPA. Manual installation is required.
+
+Ensure to have Org Mode 9.4 or later (tested on 9.4.2). This package uses
~org-collect-keywords~, which does not exist in an earlier version.
-Then store =org-marginalia.el= in your load-path, and put this in your init
file:
+Store =org-marginalia.el= in your load-path, and put this in your init file:
#+BEGIN_SRC emacs-lisp
(require 'org-marginalia)
@@ -114,9 +120,9 @@ Initial alpha release. I consider it to be the minimal
viable scope.
* Credits
To create this package, I was inspired by the following packages. I did not
copy any part of them, but borrowed some ideas from them -- e.g. saving the
margin notes in a separate file.
-- [[https://github.com/jkitchin/ov-highlight][ov-highlight]] :: John Kitchin's
(author of Org-ref). Great UX for markers with hydra. Saves the marker info and
comments directly within the Org file as Base64 encoded string. It uses overlays
-- [[https://github.com/bastibe/annotate.el][Annotate.el]] :: Bastian
Bechtold's (author of Org-journal). Unique display of annotations right next to
(or on top of) the text. It seems to be designed for very short annotations,
and perhaps for code review (programming practice); I have seen recent issues
reported when used with variable-pitch fonts (prose).
--
[[https://github.com/tkf/org-mode/blob/master/contrib/lisp/org-annotate-file.el][Org-annotate-file]]
:: Part of Org's contrib library. It seems to be designed to annotate a whole
file in a separate Org file, rather than specific text items
+- [[https://github.com/jkitchin/ov-highlight][Ov-highlight]] :: John Kitchin's
(author of Org-ref). Great UX for markers with hydra. Saves the marker info and
comments directly within the Org file as Base64 encoded string. It uses
overlays with using `ov` package.
+- [[https://github.com/bastibe/annotate.el][Annotate.el]] :: Bastian
Bechtold's (author of Org-journal). Unique display of annotations right next to
(or on top of) the text. It seems to be designed for very short annotations,
and perhaps for code review (programming practice); I have seen recent issues
reported when used with variable-pitch fonts (prose).
+-
[[https://github.com/tkf/org-mode/blob/master/contrib/lisp/org-annotate-file.el][Org-annotate-file]]
:: Part of Org's contrib library. It seems to be designed to annotate a whole
file in a separate Org file, rather than specific text items.
- [[https://github.com/IdoMagal/ipa.el][InPlaceAnnotations (ipa-mode)]] :: It
looks similar to Annotate.el above
* Feedback
diff --git a/marginalia.org b/marginalia.org
index c7a33694e3..0d5f673e89 100644
--- a/marginalia.org
+++ b/marginalia.org
@@ -10,8 +10,8 @@
** Screenshots
:PROPERTIES:
:marginalia-id: 1306ba7f
-:marginalia-source-beg: 494
-:marginalia-source-end: 505
+:marginalia-source-beg: 1007
+:marginalia-source-end: 1018
:END:
[[file:~/local-repos/org-marginalia/README.org][Org-marginalia]]
@@ -44,3 +44,33 @@ For listing, built-in `tabulated-list-mode` exists.
Additionallly, hierarchy.el,
** g . ,end) highlights))))))
[[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
+
+** ion
+:PROPERTIES:
+:marginalia-id: 3cf97a37
+:marginalia-source-beg: 14321
+:marginalia-source-end: 14325
+:END:
+[[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
+
+** ;;;; Requirements
+:PROPERTIES:
+:marginalia-id: c16e73f8
+:marginalia-source-beg: 5565
+:marginalia-source-end: 5582
+:END:
+[[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
+(defun om/list-highlights-positions ()
+ "This is an empty function definition to be replaced by a real one later.
+The actual definition is done in the private function section of
+this file, as it is a utility function. This empty declation is
+necessary in to avoid the macro expansion from failing for
+`seq-find'.")
+
+** nts
+:PROPERTIES:
+:marginalia-id: f55e13ab
+:marginalia-source-beg: 5579
+:marginalia-source-end: 5582
+:END:
+[[file:~/local-repos/org-marginalia/org-marginalia.el][org-marginalia]]
diff --git a/org-marginalia.el b/org-marginalia.el
index 9fa0b3a0bf..24b1cb094d 100644
--- a/org-marginalia.el
+++ b/org-marginalia.el
@@ -1,11 +1,11 @@
-;;; org-marginalia.el --- Write margin notes for any text file in Org Mode
-*- lexical-binding: t; -*-
+;;; org-marginalia.el --- Highlight text, write margin notes for any text file
in Org Mode -*- lexical-binding: t; -*-
;; Copyright (C) 2020 Noboru Ota
;; Author: Noboru Ota <m...@nobiot.com>
;; URL: https://github.com/nobiot/org-marginalia
;; Version: 0.0.2
-;; Last modified: 2020-12-23T105737
+;; Last modified: 2020-12-23T135735
;; Package-Requires: ((emacs "27.1") (org "9.4"))
;; Keywords: org-mode, annotation, writing, note-taking, margin-notes
@@ -48,44 +48,56 @@
;;;; Usage
-;; - =org-marginalia-mode= :: Org-marginalia is a local minor mode. Toggle it
-;; on/off with using =org-marginalia-mode=. On activating, it loads your saved
-;; highlighters from the marginalia file, and enables automatic saving of
-;; highlighters. The automatic saving is achieved via function =om/save=
-;; added to =after-save-hook=.
-
-;; - =om/mark= :: Select a region of text, and call =om/mark= (bound to =C-c n
-;; m= by default) to highlight the region. It will generate a new ID, and
-;; start tracking the location -- so you can edit text around the marked text.
-;; Do not copy and paste as it will disappear and it is a bit tricky to
-;; recover the highlighter. To create a new margin note entry in the
-;; marginalia file, save the buffer.
-
-;; - =om/save= :: By default, Org-marginalia creates or updates the
-;; highlighter's location and text inside automatically in the marginalia
-;; file. You can manually call =om/save= to manually do it (automatic
-;; process also call this command).
-
-;; - =om/open= :: Move your cursor on the highlighted text, and call
-;; =om/open= to open the relevant margin notes in a separate window.
-;; Your cursor should move to the marginalia buffer narrowed to the relevant
-;; margin notes entry. You can edit the margin notes as a normal Org file.
-;; Once you have done editing, you can simply save and close the buffer (kill
-;; or close the window) as per your normal workflow. Technically, the
-;; marginalia buffer is a cloned indirect buffer of the marginalia file.
-
-;; - =om/load= :: This command open the marginalia file and load the saved
-;; highlights onto current buffer. If there is no margin notes for it, it will
-;; output a message in the echo. Highlights tracked locally by this packages
-;; cannot persist when you kill the buffer, or quit Emacs. When you re-launch
-;; Emacs, ensure to turn on =org-marginalia-mode= to load the highlights. Load
-;; is automatically done when you activate the minor mode.
+;; - =org-marginalia-mode= ::
+;; Org-marginalia is a local minor mode. Toggle it on/off with using
+;; =org-marginalia-mode=. On activating, it loads your saved highlighters from
+;; the marginalia file, and enables automatic saving of highlighters. The
+;; automatic saving is achieved via function =om/save= added to
+;; =after-save-hook=.
+
+;; - =om/mark= (C-c n m by default) ::
+;; Select a region of text, and call =om/mark= (bound to =C-c n m= by default)
+;; to highlight the region. It will generate a new ID, and start tracking the
+;; location -- so you can edit text around the marked text. Do not copy and
+;; paste as it will disappear and it is a bit tricky to recover the
+;; highlighter. To create a new margin note entry in themarginalia file, save
the buffer.
+
+;; - =om/save= ::
+;; By default, Org-marginalia creates or updates the highlighter's location
+;; and text inside automatically in the marginalia file. You can manually call
+;; =om/save= to manually do it (automatic process also call this command).
+
+;; - =om/open= (C-c o by default) ::
+;; Move your cursor on the highlighted text, and call =om/open= to open the
+;; relevant margin notes in a separate window. Your cursor should move to the
+;; marginalia buffer narrowed to the relevant margin notes entry. You can edit
+;; the margin notes as a normal Org file. Once you have done editing, you can
+;; simply save and close the buffer (kill or close the window) as per your
+;; normal workflow. Technically, the marginalia buffer is a cloned indirect
+;; buffer of the marginalia file.
+
+;; - =om/load= ::
+;; This command open the marginalia file and load the saved highlights onto
+;; current buffer. If there is no margin notes for it, it will output a
+;; message in the echo. Highlights tracked locally by this packages cannot
+;; persist when you kill the buffer, or quit Emacs. When you re-launch Emacs,
+;; ensure to turn on =org-marginalia-mode= to load the highlights. Load is
+;; automatically done when you activate the minor mode.
;; - =om/remove= ::
;; This command removes the highlight at point. It will remove the highlight,
;; and remove the properties from the marginalia, but will keep the headline
;; and notes in tact.
+;; - =om/next= (C-c n ] by default) ::
+;; Move to the next highlight if any. If there is none below the cursor, and
+;; there is a highlight above, loop back to the top one.
+
+;; - =om/prev= (C-c n [ by default) ::
+;; Move to the previous highlight if any. If there is none above the cursor,
+;; and there is a highlight below, loop back to the bottom one.
+
+
;;;; Customizing
;; - Highlighter face can be changed via `om/highlighter'
@@ -154,8 +166,8 @@ separate Org file"
(defcustom om/notes-file-path "marginalia.org"
"Specify the file path for the marginalia.org file.
-The default is \"./marginalia.org\", thus one marginalia file per
-directory. Ensure that it is an Org file."
+The default is \"./marginalia.org\", thus one marginalia file per directory.
+Ensure that it is an Org file."
:type 'string
:group 'org-marginalia)
@@ -163,11 +175,13 @@ directory. Ensure that it is an Org file."
(defvar-local om/highlights '()
"Keep track of all the highlights.
-It is a local variable. On save-buffer, kill-buffer, or
-kill-emacs, the marker will be persisted in the filesystem.
-Each highlight is also an alist of this type:
+It is a local variable, and is a list of multiple highlights.
+Each highlight is an alist of this structure:
+
(id beg-marker . end-marker)
-The text inside the markers can change, too.")
+
+On save-buffer each highlight will be persisted in the marginalia file
+(defined by `om/notes-file-path').")
(defvar om/last-notes-buffer nil
"Stores the cloned indirect buffer for the margin notes.
@@ -183,12 +197,11 @@ It is meant to exist only one of these in each Emacs
session.")
;;;###autoload
(define-minor-mode org-marginalia-mode
- "Toggle Org-marginalia minor mode.
-It is a local minior mode to lets you write margin notes for any
-text file in Org Mode.
+ "Highlight text, write margin notes for any text file in Org Mode.
-It loads your saved highlighters from the marginalia file, and
-enables automatic saving of highlights.
+This command toggles Org-marginalia local minor mode. On
+activation, it loads your saved highlights from the marginalia
+file, and enables automatic saving of highlights.
The automatic saving is achieved via function `om/save' added
to `after-save-hook'.
@@ -217,9 +230,12 @@ the mode, `toggle' toggles the state."
;;;###autoload
(defun om/mark (beg end &optional id)
- "Highlight the selected region (BEG and END) when used interactively.
-It will generate a new ID, and start tracking the location, but
-will not create a marginalia entry yet. Call `om/save' to
+ "Highlight the selected region (BEG and END).
+When used interactively. it will generate a new ID, always
+assuming it is a new highlighted text region, and start tracking
+the higlight's location, so that you can edit the text around.
+
+It will not create a marginalia entry yet. Call `om/save' to
create a new entry (it is automatic with `after-save-hook').
When this function is called from Elisp, ID can be optionally
