[elpa] externals/org-remark f7cd8d0bbd 1/3: add: two new user options for links between main and notes files

[ELPA Syncer]

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

    add: two new user options for links between main and notes files
    
    - 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
           file-relative-name.
    
    - add: Adding a new option to org-remark-notes-file-path to use a function
    
           Its 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.
---
 NEWS          | 14 +++++++++
 org-remark.el | 94 +++++++++++++++++++++++++++++++++++++++++------------------
 2 files changed, 80 insertions(+), 28 deletions(-)

diff --git a/NEWS b/NEWS
index 02e972699f..f56b685568 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,17 @@
+Current development version
+
+  - 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
+         file-relative-name.
+
+  - add: Adding a new option to org-remark-notes-file-path to use a function
+
+         Its 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.
+
+
 Version 0.2.0
   - add: org-remark-delete
   - rm: Adding Org-ID automatically to file level when file is empty
diff --git a/org-remark.el b/org-remark.el
index 96486034a4..f9655a6597 100644
--- a/org-remark.el
+++ b/org-remark.el
@@ -6,7 +6,7 @@
 ;; URL: https://github.com/nobiot/org-remark
 ;; Version: 0.2.0
 ;; Created: 22 December 2020
-;; Last modified: 30 January 2022
+;; Last modified: 31 January 2022
 ;; Package-Requires: ((emacs "27.1") (org "9.4"))
 ;; Keywords: org-mode, annotation, writing, note-taking, marginal-notes
 
@@ -64,9 +64,19 @@ Set to nil if you prefer for it not to."
 
 (defcustom org-remark-notes-file-path "marginalia.org"
   "Define the file path to store the location of highlights and write 
annotations.
-The default is one file per directory.  Ensure that it is an Org
-file."
-  :type 'file)
+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)
@@ -84,10 +94,23 @@ for more detail and expected elements of the list."
 name."
   :type 'string)
 
+(defcustom org-remark-source-path-function #'file-relative-name
+  "Define the function that returns the file path to the main file.
+The main (source) file is the file for which `org-remark' creates
+highlights and marginal notes.
+
+When relative path is used, it is relative from the
+`default-directory' of the source file (current buffer)."
+  :type '(choice
+          (const :tag "Relative path" file-relative-name)
+          (const :tag "Abbreviated absolute path" abbreviate-file-name)
+          (function :tag "Other function")))
+
 (defcustom org-remark-use-org-id nil
   "Define if Org-remark use Org-ID to link back to the main note."
   :type 'boolean)
 
+
 
 ;;;; Variables
 
@@ -96,8 +119,8 @@ name."
 It is a local variable and is a list of overlays.  Each overlay
 represents a highlighted text region.
 
-On `save-buffer' each highlight will be save in the notes file at
-`org-remark-notes-file-path'.")
+On `save-buffer' each highlight will be saved in the notes file at
+the path returned by `org-remark-notes-get-file-path'.")
 
 (defvar-local org-remark-highlights-hidden nil
   "Keep hidden/shown state of the highlights in current buffer.")
@@ -328,8 +351,9 @@ region, and Org-remark will start tracking the highlight's
 location in the current buffer.
 
 A Org headline entry for the highlght will be created in the
-marginal notes file specified by `org-remark-notes-file-path'.
-If the file does not exist yet, it will be created.
+marginal notes file specified by
+`org-remark-notes-get-file-path'.  If the file does not exist
+yet, it will be created.
 
 When this function is called from Elisp, ID can be
 optionally passed, indicating to Org-remark that it is to load an
@@ -361,7 +385,6 @@ marginal notes file.  The expected values are nil, :load and
 
 (defun org-remark-save ()
   "Save all the highlights tracked in current buffer to notes file.
-Variable`org-remark-notes-file-path' defines the file path.
 
 This function is automatically called when you save the current
 buffer via `after-save-hook'.
@@ -390,11 +413,10 @@ in the current buffer.  Each highlight is represented by 
an overlay."
 The marginal notes will be narrowed to the relevant headline to
 show only the highlight at point.
 
-This function creates a cloned indirect buffer of the marginal
-notes file \(`org-remark-notes-file-path'\).  You can edit
-marginal notes file as a normal Org file.  Once you have done
-editing, you can simply save and kill the buffer or keep it
-around.
+This function creates a cloned indirect buffer for the marginal
+notes file.  You can edit it as a normal Org buffer.  Once you
+have done editing, you can simply save and kill the buffer or
+keep it around.
 
 The marginal notes file gets displayed by the action defined by
 `org-remark-notes-display-buffer-action' (by default in a side
@@ -654,7 +676,7 @@ marginal notes file.  The expected values are nil, :load and
 :change.
 
 A Org headline entry for the highlght will be created in the
-marginal notes file specified by `org-remark-notes-file-path'.
+marginal notes file specified by `org-remark-notes-get-file-path'.
 If the file does not exist yet, it will be created.
 
 When this function is called from Elisp, ID can be optionally
@@ -753,7 +775,7 @@ source with using ORGID."
          ;; FIXME current-line - it's not always at point
          (line-num (org-current-line beg)))
     ;; TODO Want to add a check if save is applicable here.
-    (with-current-buffer (find-file-noselect org-remark-notes-file-path)
+    (with-current-buffer (find-file-noselect (org-remark-notes-get-file-path))
       ;; If it is a new empty marginalia file
       (when (featurep 'org-remark-convert-legacy) 
(org-remark-convert-legacy-data))
       (org-with-wide-buffer
@@ -803,6 +825,29 @@ 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
@@ -852,7 +897,7 @@ only one of the marginal notes buffer per session."
   ;; Compare the target marginal notes buffer and current marginal notes 
buffer.
   ;; The latter needs to be transcluded to the base buffer of an indirect
   ;; buffer.
-  (let ((cbuf (find-file-noselect org-remark-notes-file-path))
+  (let ((cbuf (find-file-noselect (org-remark-notes-get-file-path)))
         (ibuf (when (buffer-live-p org-remark-last-notes-buffer)
                 org-remark-last-notes-buffer)))
     (unless (eq (buffer-base-buffer ibuf) cbuf)
@@ -927,10 +972,11 @@ load the highlights"
         (funcall fn beg end id :load)))))
 
 (defun org-remark-highlights-get ()
-  "Return a list of highlights from `org-remark-notes-file-path'.
+  "Return a list of highlights from the marginal notes file path.
+The file path is returned by `org-remark-notes-get-file-path'.
 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))
+  (when-let ((notes-buf (find-file-noselect (org-remark-notes-get-file-path)))
              (source-path (org-remark-source-path (buffer-file-name))))
     ;; TODO check if there is any relevant notes for the current file
     ;; This can be used for adding icon to the highlight
@@ -1069,15 +1115,7 @@ Case 2. The overlay points to no buffer
 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))
+  (funcall org-remark-source-path-function path))
 
 (defun org-remark-region-or-word ()
   "Return beg and end of the active region or of the word at point.