[elpa] externals/org-remark 8e067b1813 11/67: refactor(save): -highlight-save -> -highlight-add

[ELPA Syncer]

branch: externals/org-remark
commit 8e067b18134466a6eb5bc01069d1b7ae222a87db
Author: Noboru Ota <me@nobiot.com>
Commit: Noboru Ota <me@nobiot.com>

    refactor(save): -highlight-save -> -highlight-add
    
    'org-remark-highlight-save' was refactored as part of fixing the
    notes-sync issues, so that the function does not save the buffer any
    longer.  Saving the notes buffer to file is done separately.
    
    To reflect this change explicitly, the function name is now
    changed (obsoleting the previous '-highlight-save' name).
---
 org-remark-eww.el |   2 +-
 org-remark-nov.el |  97 ++++++++++++++++++++---------------
 org-remark.el     | 151 +++++++++++++++++++++++++++++-------------------------
 3 files changed, 139 insertions(+), 111 deletions(-)

diff --git a/org-remark-eww.el b/org-remark-eww.el
index 1dde594380..240117ff27 100644
--- a/org-remark-eww.el
+++ b/org-remark-eww.el
@@ -6,7 +6,7 @@
 ;;          Noboru Ota <me@nobiot.com>
 ;; URL: https://github.com/nobiot/org-remark
 ;; Created: 23 December 2022
-;; Last modified: 10 January 2023
+;; Last modified: 11 January 2023
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, note-taking, marginal-notes, wp
 
diff --git a/org-remark-nov.el b/org-remark-nov.el
index d32531c854..e265bbb48f 100644
--- a/org-remark-nov.el
+++ b/org-remark-nov.el
@@ -1,8 +1,33 @@
-;; -*- lexical-binding: t; -*-
+;;; org-remark-nov.el --- Compatibility with nov-mode -*- lexical-binding: t; 
-*-
+
+;; URL: https://github.com/nobiot/org-remark
+;; Created: 9 January 2023
+;; Last modified: 11 January 2023
+
+;;; Commentary:
+
+;;; Code:
+
+(require 'nov)
+;;(declare-function org-remark-auto-on "org-remark-global-tracking")
+(declare-function org-remark-highlights-load "org-remark")
+(defvar org-remark-notes-headline-functions)
+
+;; TODO add a minor mode to let user switch these hooks on and off.
+(add-hook 'org-remark-source-find-file-name-functions 
#'org-remark-get-epub-source)
+(add-hook 'org-remark-highlight-link-to-source-functions #'org-remark-nov-link)
+;; When users turn the page (document in nov-mode's terminology)
+;; `nov-mode' will erase the current buffer and render the new document
+;; content in the same buffer.  This means the highlights currently
+;; displayed get removed; the ones for the new document need to be
+;; loaded document after `nov-mode' renders the new document.
+(add-hook 'nov-post-html-render-hook #'org-remark-highlights-load)
+(add-to-list 'org-remark-notes-headline-functions
+  '(nov-mode . ((1 . org-remark-nov-highlight-add-book-headline-maybe)
+                (2 . org-remark-highlight-add-source-headline-maybe))))
 
-;; compatibility with org-noter
 (defun org-remark-get-epub-source ()
-  "Returns the path of the epub source from which the present session is 
initiated."
+  "Return the path of the epub source from which the present session is 
initiated."
   (when (eq major-mode 'nov-mode)
     (concat
      (file-name-nondirectory nov-file-name)
@@ -10,55 +35,45 @@
      (file-name-base (cdr (aref nov-documents nov-documents-index))))))
 
 (defun org-remark-nov-link (_filname)
-  ;; Assume the point is on the highlight in source epub buffer.
+  "Return \"nov:\" link with current point in `nov-mode' buffer.
+
+This function only works when the mode is `nov-mode'.
+
+Assume the point is on the highlight in source epub document
+buffer."
   (when (eq major-mode 'nov-mode)
     (org-store-link nil)))
 
-(add-hook 'org-remark-source-find-file-name-functions 
#'org-remark-get-epub-source)
-(add-hook 'org-remark-highlight-link-to-source-functions #'org-remark-nov-link)
-(add-hook 'nov-post-html-render-hook #'org-remark-highlights-load)
+(defun org-remark-nov-highlight-add-book-headline-maybe (level source-buf 
notes-buf)
+  "Add a book headline if not present in NOTES-BUF for epub file.
+Return the point of beginning of book headline regardless of it
+being newly added or already present.
+
+LEVEL is the headline level when one is to be added.
 
-(add-to-list 'org-remark-notes-create-entry-functions
-  '(nov-mode . ((1 . org-remark-nov-highlight-save-book-entry)
-                (2 . org-remark-highlight-save-file-entry))))
+SOURCE-BUF is a `nov-mode' buffer visiting a document within an
+epub file.
 
-(defun org-remark-nov-highlight-save-book-entry (level source-buf _notes-buf)
-  "Create the book entry if it does not exist for the epub file
-Assume the current buffer is in the notes buffer."
+Assume the current buffer is NOTES-BUF."
   (let (filename title)
     (with-current-buffer source-buf
+      ;; The nov variables are only locally set in the source buffer.
       (setq filename nov-file-name
             title (cdr (assoc 'title nov-metadata))))
     ;; Back in the notes buffer, return the point of the beginning of
     ;; the headline
-    (or (org-find-property "org-remark-nov-file" filename)
-        (progn
-          ;; If the book entry does not exist, create one at the bottom of 
notes buffer
-          (goto-char (point-max))
-          ;; Ensure to be in the beginning of line to add a new headline
-          (when (eolp) (open-line 1) (forward-line 1) (beginning-of-line))
-          (insert-char (string-to-char "*") level)
-          (insert (concat " " title "\n"))
-          (org-set-property "org-remark-nov-file" filename)
-          (org-back-to-heading) (point)))))
-
-;;; TODO move this test function to the user manual as a sample
-(defun test/simple-headline (level source-buf _notes-buf)
-  (let (filename)
-    (with-current-buffer source-buf
-      (setq filename (org-remark-source-get-file-name
-                      (org-remark-source-find-file-name))))
-    ;; Return the point of the beginning of the headline
-    (or (org-find-property "org-remark-file-name" filename)
-        (progn
-          ;; If this level of headline does not exist, create one at the bottom
-          (goto-char (point-max))
-          ;; Ensure to be in the beginning of line to add a new headline
-          (when (eolp) (open-line 1) (forward-line 1) (beginning-of-line))
-          (insert-char (string-to-char "*") level)
-          (insert (concat " " "title" "\n"))
-          (org-set-property "org-remark-file-name" filename)
-          (org-back-to-heading) (point)))))
+    (with-current-buffer notes-buf
+      (or (org-find-property "org-remark-nov-file" filename)
+          (progn
+            ;; If the book entry does not exist, create one at the bottom of 
notes buffer
+            (goto-char (point-max))
+            ;; Ensure to be in the beginning of line to add a new headline
+            (when (eolp) (open-line 1) (forward-line 1) (beginning-of-line))
+            (insert-char (string-to-char "*") level)
+            ;; Title is assumed to present but the program won't fail even if 
it is nil.
+            (insert (concat " " title "\n"))
+            (org-set-property "org-remark-nov-file" filename)
+            (org-back-to-heading) (point))))))
 
 (provide 'org-remark-nov)
 ;;; org-remark-nov.el ends here
diff --git a/org-remark.el b/org-remark.el
index 4e17b6e970..b362aac040 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -411,7 +411,7 @@ in the current buffer.  Each highlight is an overlay."
   (let ((notes-buf (find-file-noselect (org-remark-notes-get-file-name)))
         (source-buf (or (buffer-base-buffer) (current-buffer))))
     (dolist (h org-remark-highlights)
-      (org-remark-highlight-save h source-buf notes-buf))
+      (org-remark-highlight-add h source-buf notes-buf))
     ;;; Avoid saving the notes buffer if it is the same as the source buffer
     (if (eq source-buf notes-buf)
         (set-buffer-modified-p nil)
@@ -752,7 +752,7 @@ round-trip back to the notes file."
                 (source-buf (current-buffer))
                 ;; Get props for create and change modes
                 (notes-props
-                 (org-remark-highlight-save ov source-buf notes-buf)))
+                 (org-remark-highlight-add ov source-buf notes-buf)))
            ;; TODO generalize putting props to highlight overlay
            (when notes-props
              (unless (overlay-get ov 'help-echo)
@@ -805,11 +805,13 @@ This function assumes the current buffer is the source 
buffer."
 ;;; TODO When design finalizes, move to top of file.  Probably should
 ;;; not be a user option, and leave it to the extension developer to add
 ;;; a mode-specific entry.
-(defvar org-remark-notes-create-entry-functions
-  '((default . ((1 . org-remark-highlight-save-file-entry)))))
+(defvar org-remark-notes-headline-functions
+  '((default . ((1 . org-remark-highlight-add-source-headline-maybe)))))
 
-(defun org-remark-highlight-save (overlay source-buf notes-buf)
-  "Save a single HIGHLIGHT in the marginal notes file.
+(make-obsolete #'org-remark-highlight-save #'org-remark-highlight-add "1.3.0")
+
+(defun org-remark-highlight-add (overlay source-buf notes-buf)
+  "Add a single HIGHLIGHT in the marginal notes file.
 
 Return the highlight's data properties list (TODO refer to ...).
 
@@ -856,61 +858,70 @@ When the current source buffer is not set up for sync 
with notes,
 this function calls `org-remark-notes-setup' to prepare the notes
 buffer for automatic sync."
   (let ((notes-props)
-        (notes-create-entry-functions
-         (cdr (or (assoc-string major-mode 
org-remark-notes-create-entry-functions)
-                  (assoc-string 'default 
org-remark-notes-create-entry-functions)))))
+        (notes-headline-functions
+         (cdr (or (assoc major-mode org-remark-notes-headline-functions)
+                  (assoc 'default org-remark-notes-headline-functions)))))
     (with-current-buffer notes-buf
-      (save-restriction
-        (widen)
-        (dolist (pair notes-create-entry-functions)
+      (org-with-wide-buffer
+        (dolist (pair notes-headline-functions)
           (let ((level (car pair))
                 (fn (cdr pair)))
             (goto-char (funcall fn level source-buf notes-buf))
             (org-narrow-to-subtree)))
         (setq notes-props
-              (org-remark-highlight-save-highlight-entry overlay source-buf 
notes-buf))))
+              (org-remark-highlight-add-or-update-highlight-headline
+               overlay source-buf notes-buf))))
     ;;; Set up notes buffer for sync for the source buffer
-    (unless org-remark-source-setup-done
-      (org-remark-notes-setup notes-buf source-buf))
+    (with-current-buffer source-buf
+      (unless org-remark-source-setup-done
+        (org-remark-notes-setup notes-buf source-buf)))
     ;;; Return notes-props
     notes-props))
 
-(defun org-remark-highlight-save-file-entry (level source-buf _notes-buf)
-  ".
-Return point of file entry.
-Assume the current buffer is NOTES-BUF."
-  (let (filename title)
+(defun org-remark-highlight-add-source-headline-maybe (level source-buf 
notes-buf)
+  "Add a new source headline if not yet present in NOTES-BUF.
+Return the point of beginning of source headline regardless of it
+being newly added or already presented.
+
+SOURCE-BUF is the source buffer that contains highlights.
 
+Assume the current buffer is NOTES-BUF."
+  (let (source-name title)
     (with-current-buffer source-buf
-      (setq filename (org-remark-source-get-file-name
+      (setq source-name (org-remark-source-get-file-name
                       (org-remark-source-find-file-name)))
       (setq title (org-remark-highlight-get-title)))
-
-    (when (featurep 'org-remark-convert-legacy) 
(org-remark-convert-legacy-data))
-
-    (or (org-find-property
-         org-remark-prop-source-file filename)
-        (progn
-          ;; If file-headline does not exist, create one at the bottom
-          (goto-char (point-max))
-          ;; Ensure to be in the beginning of line to add a new headline
-          (when (eolp) (open-line 1) (forward-line 1) (beginning-of-line))
-          (insert (concat (insert-char (string-to-char "*") level)
-                          " " title "\n"))
-          (org-set-property org-remark-prop-source-file filename)
-          (org-back-to-heading) (point)))))
-
-(defun org-remark-highlight-save-highlight-entry (overlay source-buf 
_notes-buf)
-  ".
-Return notes-props Assume the current buffer is NOTES-BUF and
-point is placed on the beginning of file-headline (one level up)."
+    (with-current-buffer notes-buf
+      ;; Transparent org-marginalia data conversion to org-remark
+      (when (featurep 'org-remark-convert-legacy) 
(org-remark-convert-legacy-data))
+      ;; Return the beginning point of the headline. Create if not present
+      (or (org-find-property
+           org-remark-prop-source-file source-name)
+          (progn
+            ;; If file-headline does not exist, create one at the bottom
+            (goto-char (point-max))
+            ;; Ensure to be in the beginning of line to add a new headline
+            (when (eolp) (open-line 1) (forward-line 1) (beginning-of-line))
+            (insert-char (string-to-char "*") level)
+            (insert (concat " " title "\n"))
+            (org-set-property org-remark-prop-source-file source-name)
+            (org-back-to-heading) (point))))))
+
+(defun org-remark-highlight-add-or-update-highlight-headline (hightlight 
source-buf notes-buf)
+  "Add a new HIGHLIGHT headlne to the NOTES-BUF or update it.
+Return notes-props as a property list.
+
+HIGHLIGHT is an overlay from the SOURCE-BUF.
+
+Assume the current buffer is NOTES-BUF and point is placed on the
+beginning of source-headline, which should be one level up."
   ;; Add org-remark-link with updated line-num as a property
   (let (title beg end props id text filename line-num link orgid)
     (with-current-buffer source-buf
       (setq title (org-remark-highlight-get-title)
-            beg (overlay-start overlay)
-            end (overlay-end overlay)
-            props (overlay-properties overlay)
+            beg (overlay-start highlight)
+            end (overlay-end highlight)
+            props (overlay-properties highlight)
             id (plist-get props 'org-remark-id)
             text (org-with-wide-buffer (buffer-substring-no-properties beg 
end))
             filename (org-remark-source-get-file-name
@@ -923,32 +934,34 @@ point is placed on the beginning of file-headline (one 
level up)."
                     'org-remark-highlight-link-to-source-functions filename))
             orgid (org-remark-highlight-get-org-id beg))
       (when link (plist-put props "org-remark-link" link)))
-
-    (let ((id-headline (org-find-property org-remark-prop-id id))
-          ;; Assume point is at the beginning of the parent headline
-          (level (1+ (org-current-level))))
-      (if id-headline
-          (progn
-            (goto-char id-headline)
-            ;; Update the existing headline and position properties
-            ;; Don't update the headline text when it already exists
-            ;; Let the user decide how to manage the headlines
-            ;; (org-edit-headline text)
-            (org-remark-notes-set-properties beg end props))
-        ;; No headline with the marginal notes ID property. Create a new one
-        ;; at the end of the file's entry
-        (org-narrow-to-subtree)
-        (goto-char (point-max))
-        ;; Ensure to be in the beginning of line to add a new headline
-        (when (eolp) (open-line 1) (forward-line 1) (beginning-of-line))
-        ;; Create a headline
-        ;; Add a properties
-        (insert (concat (insert-char (string-to-char "*") level)
-                        " " text "\n"))
-        (org-remark-notes-set-properties beg end props)
-        (when (and orgid org-remark-use-org-id)
-          (insert (concat "[[id:" orgid "]" "[" title "]]"))))
-      (list :body (org-remark-notes-get-body)))))
+    ;;; Make it explicit that we are now in the notes-buf, though it is
+    ;;; functionally redundant.
+    (with-current-buffer notes-buf
+      (let ((highlight-headline (org-find-property org-remark-prop-id id))
+            ;; Assume point is at the beginning of the parent headline
+            (level (1+ (org-current-level))))
+        (if highlight-headline
+            (progn
+              (goto-char id-headline)
+              ;; Update the existing headline and position properties
+              ;; Don't update the headline text when it already exists
+              ;; Let the user decide how to manage the headlines
+              ;; (org-edit-headline text)
+              (org-remark-notes-set-properties beg end props))
+          ;; No headline with the marginal notes ID property. Create a new one
+          ;; at the end of the file's entry
+          (org-narrow-to-subtree)
+          (goto-char (point-max))
+          ;; Ensure to be in the beginning of line to add a new headline
+          (when (eolp) (open-line 1) (forward-line 1) (beginning-of-line))
+          ;; Create a headline
+          ;; Add a properties
+          (insert (concat (insert-char (string-to-char "*") level)
+                          " " text "\n"))
+          (org-remark-notes-set-properties beg end props)
+          (when (and orgid org-remark-use-org-id)
+            (insert (concat "[[id:" orgid "]" "[" title "]]"))))
+        (list :body (org-remark-notes-get-body))))))
 
 (defun org-remark-highlight-load (highlight)
   "Load a single HIGHLIGHT to the source buffer.