branch: externals/org-remark
commit 68c5dcc8a9351ed479f673541f37046eff436f4c
Author: Noboru Ota <m...@nobiot.com>
Commit: Noboru Ota <m...@nobiot.com>
chg: `org-remark-global-tracking-mode' has been simplified.
.org-remark-tracking file is no longer necessary and can be safely
deleted from the user's Emacs configuraiton directory if present.
Automatic activation of `org-remark-mode' is done by looking the
presence of a marginal notes file for current buffer open.
`org-remark-global-tracking-mode' itself is still relevant and
recommended to be setup as was previously in the user manual.
---
NEWS | 10 ++++
org-remark-global-tracking.el | 131 +++++++++++++++++-------------------------
org-remark.el | 86 +++++----------------------
3 files changed, 77 insertions(+), 150 deletions(-)
diff --git a/NEWS b/NEWS
index f56b685568..5129b129aa 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,15 @@
Current development version
+ - chg: `org-remark-global-tracking-mode' has been simplified.
+
+ .org-remark-tracking file is no longer necessary and can be safely
+ deleted from the user's Emacs configuraiton directory if present.
+ Automatic activation of `org-remark-mode' is done by looking the
+ presence of a marginal notes file for current buffer open.
+
+ `org-remark-global-tracking-mode' itself is still relevant and
+ recommended to be setup as was previously in the user manual.
+
- add: Option to use relative links from the marginal notes back to the
source
Adding user option org-remark-source-path-function. The default is
diff --git a/org-remark-global-tracking.el b/org-remark-global-tracking.el
index 3974260cd0..e4efdb7d61 100644
--- a/org-remark-global-tracking.el
+++ b/org-remark-global-tracking.el
@@ -5,7 +5,7 @@
;; Author: Noboru Ota <m...@nobiot.com>
;; URL: https://github.com/nobiot/org-remark
;; Created: 15 August 2021
-;; Last modified: 17 January 2022
+;; Last modified: 31 January 2022
;; Package-Requires: ((emacs "27.1") (org "9.4"))
;; Keywords: org-mode, annotation, writing, note-taking, marginal notes
@@ -31,23 +31,30 @@
(declare-function org-remark-mode "org-remark")
-(defcustom org-remark-tracking-file
- (abbreviate-file-name
- (expand-file-name ".org-remark-tracking" user-emacs-directory))
- "Define file path to save the files `org-remark' tracks.
-When `org-remark-global-tracking-mode' is active, opening a file
-saved in `org-remark-tracking-file' automatically loads highlights."
- :group 'org-remark
- :type 'file)
+(defcustom org-remark-notes-file-path "marginalia.org"
+ "Define the file path to store the location of highlights and write
annotations.
+It can be either a string or function.
+
+If it is a string, it should be a file path to the marginal notes
+file. The default is \"marginalia.org\". It will be one marginal
+notes file per directory. Ensure that it is an Or file.
-(defvar org-remark-files-tracked nil
- "List of files being tracked by `org-remark-global-tracking-mode'.")
+If it is a function, the default function is
+`org-remark-notes-file-path-function'. It returns a file name
+like this: \"FILE-notes.org\" by adding \"-notes.org\" as a
+suffix to the file name without the extension."
+ :group 'org-remark
+ :type '(choice
+ (file "marginalia.org")
+ (function org-remark-notes-file-path-function)))
;;;###autoload
(define-minor-mode org-remark-global-tracking-mode
- "Track files saved in `org-remark-tracking-file'.
-When opening any of them, automatically activates `org-remark-mode'
-locally for the file opened."
+ "Automatically activates local minor mode `org-remark-mode'.
+When this global minor mode is active, a function added to
+`find-file-hook' will look for a marginal notes file for the file
+as defined by `org-remark-notes-file-path'. If it is found and
+readable, the function automatically activates `org-remark'."
:init-value nil
:lighter " ormk-auto"
:global t
@@ -55,74 +62,44 @@ locally for the file opened."
(cond
(org-remark-global-tracking-mode
;; Activate
- ;; Prioritise the new `org-remark-tracking-file' over the legacy one
- (when-let (tracking-file (or (when (file-exists-p
- org-remark-tracking-file)
- org-remark-tracking-file)
- (when (file-exists-p
- (org-remark-legacy-tracking-file-get))
- (org-remark-legacy-tracking-file-get))))
- (org-remark-tracking-load tracking-file))
- ;; `org-remark-tracking-save' should be added to kill hook even when no
- ;; tracking file existed before -- this would indicate first time use of
- ;; tracking; the files tracked in the memory needs to persist in the file.
- (add-hook 'find-file-hook #'org-remark-tracking-auto-on)
- (add-hook 'kill-emacs-hook #'org-remark-tracking-save))
+ (add-hook 'find-file-hook #'org-remark-auto-on))
(t
;; Deactivate
- (setq org-remark-files-tracked nil)
- (remove-hook 'find-file-hook #'org-remark-tracking-auto-on)
- (remove-hook 'kill-emacs-hook #'org-remark-tracking-save))))
+ (remove-hook 'find-file-hook #'org-remark-auto-on))))
;;;; Private Functions
-(defun org-remark-tracking-auto-on ()
- "Activate `org-remark-mode' when file is being tracked.
-The files being tracked are loaded on to
-`org-remark-files-tracked'. Refer to
-`org-remark-tracking-load'."
- (when (and org-remark-files-tracked
- (member (abbreviate-file-name (buffer-file-name))
- org-remark-files-tracked))
- (unless (featurep 'org-remark) (require 'org-remark))
- (org-remark-mode +1)))
-
-(defun org-remark-tracking-load (tracking-file)
- "Load files being tracked from TRACKING-FILE.
-It has one filename each line. The filename is obtrained with
-`abbreviated-file-names'. This function reloads the content of
-the file regardless if it is already done in this Emacs session
-or not."
- (with-temp-buffer
- (condition-case nil
- (progn
- (insert-file-contents tracking-file)
- (setq org-remark-files-tracked
- (split-string (buffer-string) "\n"))))))
-
-(defun org-remark-tracking-save ()
- "Save files being tracked in `org-remark-tracking-file'.
-Files with marginal notes are tracked with variable
-`org-remark-files-tracked'."
- (interactive)
- (when org-remark-files-tracked
- ;; Save to the new Org-remark tracking file. No need to keep the old file
any
- ;; longer, ignore the legacy file path.
- (with-temp-file org-remark-tracking-file
- (insert (mapconcat 'identity org-remark-files-tracked "\n")))))
-
-(defun org-remark-legacy-tracking-file-get ()
- "Return the path to the legacy tracking file.
-This function is used to automate conversion from the legacy
-Org-marginalia to the new Org-remark. For this purpose, this
-function assumes the user has not customised the default tracking
-file name \".org-marginalia-tracking\" placed their
-`user-emacs-directory'. If personalized, it is reasonable to
-expect the user is able to to also customize
-`org-remark-tracking-file'."
- (abbreviate-file-name (expand-file-name
- ".org-marginalia-tracking"
- user-emacs-directory)))
+(defun org-remark-auto-on ()
+ "Automatically activates `org-remark-mode' for current buffer when relevant.
+This function is meant to be addd to `find-file-hook' by
+`org-remark-global-tracking-mode'."
+ (when-let (notes-file (org-remark-notes-get-file-path))
+ (when (file-readable-p notes-file)
+ (unless (featurep 'org-remark) (require 'org-remark))
+ (org-remark-mode +1))))
+
+(defun org-remark-notes-get-file-path ()
+ "Return the file path to the marginal notes for current buffer.
+This function looks at customization variable
+`org-remark-notes-file-path'. If it is a string, return it as
+the file path. If it is a function, evaluate it to return the
+value."
+ (if-let ((fn (when (functionp org-remark-notes-file-path)
+ org-remark-notes-file-path)))
+ (funcall fn)
+ ;; If not funciton, assume string and return it as the file path
+ org-remark-notes-file-path))
+
+(defun org-remark-notes-file-path-function ()
+ "Return a marginal notes file name for the current buffer.
+
+This is the default function for the customizing variable
+`org-remark-notes-file-path' for its funciton option.
+
+When the current buffer is visiting a FILE, the name of marginal
+notes file will be \"FILE-notes.org\", adding \"-notes.org\" as a
+suffix to the file name without the extension."
+ (concat (file-name-sans-extension (buffer-file-name)) "-notes.org"))
(provide 'org-remark-global-tracking)
diff --git a/org-remark.el b/org-remark.el
index f9655a6597..2eeb0187cc 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -62,22 +62,6 @@
Set to nil if you prefer for it not to."
:type 'boolean)
-(defcustom org-remark-notes-file-path "marginalia.org"
- "Define the file path to store the location of highlights and write
annotations.
-It can be either a string or function.
-
-If it is a string, it should be a file path to the marginal notes
-file. The default is \"marginalia.org\". It will be one marginal
-notes file per directory. Ensure that it is an Or file.
-
-If it is a function, the default function is
-`org-remark-notes-file-path-function'. It returns a file name
-like this: \"FILE-notes.org\" by adding \"-notes.org\" as a
-suffix to the file name without the extension."
- :type '(choice
- (file "marginalia.org")
- (function org-remark-notes-file-path-function)))
-
(defcustom org-remark-notes-display-buffer-action
`((display-buffer-in-side-window)
(side . left)
@@ -249,19 +233,14 @@ recommended to turn it on as part of Emacs initialization.
(org-remark-mode
;; Activate
(org-remark-highlights-load)
- (add-hook 'after-save-hook #'org-remark-save nil t)
- (add-hook 'kill-buffer-hook #'org-remark-tracking-save nil t)
- ;; Tracking
- (org-remark-notes-track-file (buffer-file-name)))
+ (add-hook 'after-save-hook #'org-remark-save nil t))
(t
;; Deactivate
(when org-remark-highlights
(dolist (highlight org-remark-highlights)
(delete-overlay highlight)))
(setq org-remark-highlights nil)
- (org-remark-tracking-save)
- (remove-hook 'after-save-hook #'org-remark-save t)
- (remove-hook 'kill-buffer-hook #'org-remark-tracking-save t))))
+ (remove-hook 'after-save-hook #'org-remark-save t))))
;; Org-remark Menu
@@ -347,8 +326,7 @@ This function will apply face `org-remark-highlighter' to
the selected region.
When this function is used interactively, it will generate a new
ID, always assuming it is working on a new highlighted text
-region, and Org-remark will start tracking the highlight's
-location in the current buffer.
+region.
A Org headline entry for the highlght will be created in the
marginal notes file specified by
@@ -389,11 +367,6 @@ marginal notes file. The expected values are nil, :load
and
This function is automatically called when you save the current
buffer via `after-save-hook'.
-When `org-remark-global-tracking-mode' is on, this function also
-adds current buffer to variable `org-remark-files-tracked' so that
-next time you visit this file, `org-remark-mode' can be
-automatically turned on to load the highlights.
-
`org-remark-highlights' is the local variable that tracks every highlight
in the current buffer. Each highlight is represented by an overlay."
(interactive)
@@ -404,9 +377,7 @@ in the current buffer. Each highlight is represented by an
overlay."
(let ((beg (overlay-start h))
(end (overlay-end h))
(props (overlay-properties h)))
- (org-remark-highlight-save path beg end props)))
- ;; Tracking
- (org-remark-notes-track-file path)))
+ (org-remark-highlight-save path beg end props)))))
(defun org-remark-open (point &optional view-only)
"Open marginal notes file for highlight at POINT.
@@ -513,13 +484,13 @@ the sequence like so:
(defun org-remark-toggle ()
"Toggle showing/hiding of highlights in current buffer.
- If you would like to hide/show the highlights in the current
- buffer, it is recommended to use this command instead of
- `org-remark-mode'. This command only affects the display of the
- highlights and their locations are still kept tracked.
- Toggling off ~org-remark-mode~ stops this tracking completely,
- which will likely result in inconsistency between the marginal
- notes file and the current main buffer."
+If you would like to hide/show the highlights in the current
+buffer, it is recommended to use this command instead of
+`org-remark-mode'. This command only affects the display of the
+highlights and their locations are still kept tracked. Toggling
+off `org-remark-mode' stops this tracking completely, which will
+likely result in inconsistency between the marginal notes file
+and the current main buffer."
(interactive)
(if org-remark-highlights-hidden
(org-remark-highlights-show)
@@ -582,7 +553,7 @@ confirmation and will remove the highlight and deletes the
entry
in the marginal notes buffer.
This command is identical with passing a universal argument to
-`org-remark-remove'. "
+`org-remark-remove'."
(interactive "d")
(org-remark-remove point :delete))
@@ -825,29 +796,6 @@ source with using ORGID."
;;;;; org-remark-notes
;; Work on marginal notes
-(defun org-remark-notes-get-file-path ()
- "Return the file path to the marginal notes for current buffer.
-This function looks at customization variable
-`org-remark-notes-file-path'. If it is a string, return it as
-the file path. If it is a function, evaluate it to return the
-value."
- (if-let ((fn (when (functionp org-remark-notes-file-path)
- org-remark-notes-file-path)))
- (funcall fn)
- ;; If not funciton, assume string and return it as the file path
- org-remark-notes-file-path))
-
-(defun org-remark-notes-file-path-function ()
- "Return a marginal notes file name for the current buffer.
-
-This is the default function for the customizing variable
-`org-remark-notes-file-path' for its funciton option.
-
-When the current buffer is visiting a FILE, the name of marginal
-notes file will be \"FILE-notes.org\", adding \"-notes.org\" as a
-suffix to the file name without the extension."
- (concat (file-name-sans-extension (buffer-file-name)) "-notes.org"))
-
(defun org-remark-notes-remove (id &optional delete)
"Remove the highlight entry for ID for current buffer.
By default, it deletes only the properties of the entry keeping
@@ -876,7 +824,7 @@ Return t if an entry is removed or deleted."
;; This does not display the location correctly
(display-buffer ibuf
org-remark-notes-display-buffer-action)
- (y-or-n-p "Highlight removed but notes exist. \
+ (y-or-n-p "Highlight removed but notes exist. \
Do you really want to delete the notes?"))
;; If there is no content, it's OK
t))
@@ -937,14 +885,6 @@ drawer."
(org-set-property p v))))
t)
-(defun org-remark-notes-track-file (path)
- "Add PATH to `org-remark-files-tracked' when relevant.
-It works only when `org-remark-global-tracking-mode' is on. For
-the global tracking purpose, the path must be an absolute path."
- (when org-remark-global-tracking-mode
- (add-to-list 'org-remark-files-tracked
- (abbreviate-file-name path))))
-
;;;;; org-remark-highlights
;; Work on all the highlights in the current buffer
