[elpa] externals/org-remark d07f158dfe 125/173: add:refactor: org-remark-source-path, org-remark-notes-track-file

[ELPA Syncer]

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

    add:refactor: org-remark-source-path, org-remark-notes-track-file
---
 org-remark-convert-legacy.el |  1 -
 org-remark.el                | 96 ++++++++++++++++++++++++++++----------------
 2 files changed, 62 insertions(+), 35 deletions(-)

diff --git a/org-remark-convert-legacy.el b/org-remark-convert-legacy.el
index 48ef8c0261..442aa17ed4 100644
--- a/org-remark-convert-legacy.el
+++ b/org-remark-convert-legacy.el
@@ -99,4 +99,3 @@ solely by Org-marginalia."
 (provide 'org-remark-convert-legacy)
 
 ;;; org-remark-convert-legacy.el ends here
-
diff --git a/org-remark.el b/org-remark.el
index 363a51ed17..d021a3072f 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -4,7 +4,7 @@
 
 ;; Author: Noboru Ota <me@nobiot.com>
 ;; URL: https://github.com/nobiot/org-remark
-;; Version: 1.0.0-rc
+;; Version: 0.1.0
 ;; Created: 22 December 2020
 ;; Last modified: 16 January 2022
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
@@ -86,7 +86,7 @@ for more detail and expected elements of the list."
 name."
   :type 'string)
 
-(defcustom org-remark-use-org-id t
+(defcustom org-remark-use-org-id nil
   "Define if Org-remark use Org-ID to link back to the main note."
   :type 'boolean)
 
@@ -289,9 +289,7 @@ load the highlights"
           (unless (functionp fn) (setq fn #'org-remark-mark))
           (funcall fn beg end id 'load-only)))))
   ;; Tracking
-  (when org-remark-global-tracking-mode
-    (add-to-list 'org-remark-files-tracked
-                 (abbreviate-file-name (buffer-file-name))))
+  (org-remark-notes-track-file (buffer-file-name))
   (setq org-remark-loaded t))
 
 (defun org-remark-save ()
@@ -311,15 +309,14 @@ in the current buffer.  Each highlight is represented by 
an overlay."
   (interactive)
   (org-remark-housekeep)
   (org-remark-highlights-sort)
-  (let ((path (abbreviate-file-name (buffer-file-name))))
+  (let ((path (buffer-file-name)))
     (dolist (h org-remark-highlights)
       (let ((beg (overlay-start h))
             (end (overlay-end h))
             (props (overlay-properties h)))
         (org-remark-single-highlight-save path beg end props)))
     ;; Tracking
-    (when org-remark-global-tracking-mode
-      (add-to-list 'org-remark-files-tracked path))))
+    (org-remark-notes-track-file path)))
 
 (defun org-remark-next ()
   "Move to the next highlight, if any.
@@ -574,7 +571,7 @@ passed.  If so, no new ID gets generated."
      ;; Adding overlay to the buffer does not set the buffer modified. You
      ;; cannot use `undo' to undo highlights, either.
      (unless load-only
-       (org-remark-single-highlight-save (abbreviate-file-name 
(buffer-file-name))
+       (org-remark-single-highlight-save (buffer-file-name)
                                          beg end
                                          (overlay-properties ov)
                                          
(org-remark-single-highlight-get-title)))
@@ -598,41 +595,49 @@ non-nil.  Returns nil otherwise, or when no Org-ID is 
found."
 
 (defun org-remark-single-highlight-save (path beg end props &optional title)
   "Save a single HIGHLIGHT in the marginal notes file.
-The marginal notes file is specified by PATH.
-
-BEG . END . PROPS
 
 Return t.
 
-For the first highlight for the current buffer, this function
-will create a new H1 headline for it at the bottom of the
-marginal notes buffer.
+PATH specifies the source/main file with which the marginal notes
+file is associated.
+
+BEG and END specify the range of the highlight being saved.  It
+is the highlight overlay's start and end.
+
+PROPS are the highlight overlay's properties.  Not all the
+properties will be added as headline properties.  Refer to
+`org-remark-notes-set-properties'.
+
+For the first highlight of the current buffer, this function will
+create a new H1 headline for it at the bottom of the marginal
+notes buffer with TITLE as its headline text.
 
 If it is a new highlight, this function will create a new H2
-headline with the TITLE as its headline text at the end of the H1
-headline for the current buffer.
+headline with the highlighted text as its headline text at the
+end of the H1 headline for the current buffer.
 
 If headline with the same ID already exists, update its position
 and other \"org-remark-*\" properties (CATEGORY is the exception
-and gets updated as well) from the highlight overlay.  The
-headline text will be kept intact, because the user might have
-changed it to their needs.
+and gets updated as well) from the highlight overlay.  For
+update, the headline text will be kept intact, because the user
+might have changed it to their needs.
 
-This function will also add a normal file link in the H2 headline
-entry back to the current buffer with serach option
-\"::line-number\".
+This function will also add a normal file link as property
+\"org-remark-lilnk\" of the H2 headline entry back to the current
+buffer with serach option \"::line-number\".
 
 ORGID can be passed to this function.  If user option
-`org-remark-use-org-id' is non-nil, this function will create a
-link back to the source via an Org-ID link with using ORGID
-instead of the normal file link.
-
-When a new marginal notes file is created and
-`org-remark-use-org-id' is non-nil, this function adds ID
-property to the file level.  This can be helpful with other
-packages such as Org-roam's backlink feature."
+`org-remark-use-org-id' is non-nil, this function will add an
+Org-ID link in the body text of the headline, linking back to the
+source with using ORGID.
+
+When a new marginal notes file is to be created and
+`org-remark-use-org-id' is non-nil, this function will also add
+an Org-ID property to the file level.  This can be helpful with
+other packages such as Org-roam's backlink feature."
   ;;`org-with-wide-buffer is a macro that should work for non-Org file'
-  (let* ((id (plist-get props 'org-remark-id))
+  (let* ((path (org-remark-source-path path))
+         (id (plist-get props 'org-remark-id))
          (text (org-with-wide-buffer (buffer-substring-no-properties beg end)))
          (orgid (org-remark-single-highlight-get-org-id beg))
          ;; FIXME current-line - it's not always at point
@@ -723,7 +728,7 @@ Minimal properties are:
 - org-remark-source-end :: END
 
 For PROPS, if the property name is CATEGORY \(case-sensitive\) or
-prefixed with org-remark- set them to to headline's property
+prefixed with \"org-remark-\" set them to to headline's property
 drawer."
   (org-set-property org-remark-prop-source-beg
                     (number-to-string beg))
@@ -744,7 +749,7 @@ drawer."
 Each highlight is a list in the following structure:
     (id (beg . end) label)"
   (when-let ((notes-buf (find-file-noselect org-remark-notes-file-path))
-             (source-path (abbreviate-file-name (buffer-file-name))))
+             (source-path (org-remark-source-path (buffer-file-name))))
     ;; TODO check if there is any relevant notes for the current file
     (let ((highlights))
       (with-current-buffer notes-buf
@@ -892,6 +897,29 @@ Case 2. The overlay points to no buffer
       (setq org-remark-highlights (delete ov org-remark-highlights))))
   t)
 
+(defun org-remark-source-path (path)
+  "Covert PATH either to absolute or relative for marginal notes files.
+Returns the standardized path.  Currently, it's only a place
+holder and uses `abbreviate-file-name' to return an absolute
+path."
+  ;; TODO
+  ;; A place holder for enhancemnet after the release of v1.0.0
+  ;; Potentially support relative path.
+  ;; No capacity to test this properly at the moment.
+  ;; 
+  ;; (if org-remark-notes-relative-directory
+  ;;     (funcall org-remark-notes-path-function path 
org-remark-notes-relative-directory)
+  ;;   (funcall org-remark-notes-path-function path)))
+  (abbreviate-file-name path))
+
+(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))))
+
 (defun org-remark-empty-buffer-p ()
   "Return t when the current buffer is empty."
   (when (= 0 (buffer-size)) t))