[nongnu] elpa/annotate 7f48fad362 3/3: Merge pull request #130 from cage2/add-local-notes

[ELPA Syncer]

branch: elpa/annotate
commit 7f48fad362b15546da7b015b533609a2452497b0
Merge: e982a7b74a 4e90910a2c
Author: cage2 <1257703+cage2@users.noreply.github.com>
Commit: GitHub <noreply@github.com>

    Merge pull request #130 from cage2/add-local-notes
    
    Added procedures to generate and use a single database for each annotated 
file.
---
 Changelog   |  7 +++++++
 NEWS.org    |  8 +++++++-
 README.org  | 43 ++++++++++++++++++++++++++++++++++---------
 annotate.el | 32 ++++++++++++++++++++++++++++++--
 4 files changed, 78 insertions(+), 12 deletions(-)

diff --git a/Changelog b/Changelog
index 31112ee8b9..c43e997ebb 100644
--- a/Changelog
+++ b/Changelog
@@ -1,3 +1,10 @@
+2022-05-26 cage
+
+        * annotate.el:
+
+        - added procedures to generate and use a single database for each
+        annotated file.
+
 2022-04-23 cage
 
         * annotate.el:
diff --git a/NEWS.org b/NEWS.org
index 31dc2a76a6..9b453cf142 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -1,4 +1,10 @@
-- 2022-04-23 v1.5.4 cage::
+- 2022-05-26 v1.6.0 cage ::
+
+  This version  allows users  to instruct the  program to  generate an
+  annotation  database for  each annotated  file, instead  of using  a
+  central database that contains all the annotations.
+
+- 2022-04-23 v1.5.4 cage ::
 
   This version  restored redrawing  of annotation  when the  window is
   resized.
diff --git a/README.org b/README.org
index 254bc9f4a0..707608b678 100644
--- a/README.org
+++ b/README.org
@@ -49,26 +49,51 @@ Please note that switching database,  in this context, 
means rebinding
 the  aforementioned variable  (~annotate-file~).  This  means than  no
 more than a single database can be active for each Emacs session.
 
+If an  empty annotation database  (in memory) is saved  the database
+file  is deleted  instead, if  ~annotate-database-confirm-deletion~ is
+non  nil (the  default) a  confirmation action  is asked  to the  user
+before actually remove the file from the file system.
+
+**** related customizable variable
+     - ~annotate-file~
+     - ~annotate-warn-if-hash-mismatch~
+     - ~annotate-database-confirm-deletion~
+
+*** Non centralized database
+
 To use multiple database in the same Emacs session ~annotate-file~ should be 
made
 
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer_002dLocal-Variables.html][buffer-local]],
 see:
 [[https://github.com/bastibe/annotate.el/issues/68][this thread]] and, in 
particular
 
[[https://github.com/bastibe/annotate.el/issues/68#issuecomment-728218022][this 
message]].
 
-If an  empty annotation database  (in memory) is saved  the database
-file  is deleted  instead, if  ~annotate-database-confirm-deletion~ is
-non  nil (the  default) a  confirmation action  is asked  to the  user
-before actually remove the file from the file system.
+Finally, if the customizable variable ~annotate-file-buffer-local~ is
+non-nil (default ~nil~), for each annotated file an annotation
+database is saved under the same directory that contains the annotated
+file.
+
+The name of the annotation database is built concatenating the name of
+the annotated file without the optional extension and the string value
+bound to the customizable variable
+~annotate-buffer-local-database-extension~ (default: ~notes~), example follows:
+
+| annotated file   | annotations file     |
+|------------------+----------------------|
+| /home/user/foo.c | /home/user/foo.notes |
+|------------------+----------------------|
+
+Important note: if ~/home/user/foo.notes~ exists, *will be overwritten*.
+
+**** related customizable variable
+     - ~annotate-file-buffer-local~
+     - ~annotate-buffer-local-database-extension~
+
+*** Uninstalling
 
 Users of
 [[https://github.com/emacscollective/no-littering][no-littering]]
 can take advantage of its packages generated files management.
 
-**** related customizable variable
-     - ~annotate-file~
-     - ~annotate-warn-if-hash-mismatch~
-     - ~annotate-database-confirm-deletion~
-
 ** keybindings
 
 *** ~C-c  C-a~ (function annotate-annotate)
diff --git a/annotate.el b/annotate.el
index b97a496761..cf2059b14a 100644
--- a/annotate.el
+++ b/annotate.el
@@ -7,7 +7,7 @@
 ;; Maintainer: Bastian Bechtold <bastibe.dev@mailbox.org>, cage 
<cage-dev@twistfold.it>
 ;; URL: https://github.com/bastibe/annotate.el
 ;; Created: 2015-06-10
-;; Version: 1.5.4
+;; Version: 1.6.0
 
 ;; This file is NOT part of GNU Emacs.
 
@@ -58,7 +58,7 @@
 ;;;###autoload
 (defgroup annotate nil
   "Annotate files without changing them."
-  :version "1.5.4"
+  :version "1.6.0"
   :group 'text)
 
 (defvar annotate-mode-map
@@ -82,6 +82,17 @@ See https://github.com/bastibe/annotate.el/ for 
documentation."
   "File where annotations are stored."
   :type 'file)
 
+(defcustom annotate-file-buffer-local nil
+ "If non nil (default `nil'), for each annotated file `filename', a database
+`filename.notes', containing the annotations, is generated in the
+same directory that contains `filename'."
+  :type 'string)
+
+(defcustom annotate-buffer-local-database-extension "notes"
+ "The extension appended to the annotated filename to get the
+name of the local database annotation"
+  :type 'string)
+
 (defface annotate-highlight
   '((t (:underline "coral")))
   "Face for annotation highlights.")
@@ -437,8 +448,25 @@ modified (for example a newline is inserted)."
 note that the argument `FRAME' is ignored"
   (font-lock-flush))
 
+(defun annotate--filepath->local-database-name (filepath)
+ "Generates the file path of the local database form `FILEPATH'"
+  (concat (file-name-nondirectory filepath)
+          "."
+          annotate-buffer-local-database-extension))
+
+(defun annotate--maybe-database-set-buffer-local ()
+ "Sets, if user asked to do so, the annotation database to a
+local version (i.e. a different database for each annotated file"
+  (when annotate-file-buffer-local
+    (make-local-variable 'annotate-file)
+    (when-let* ((buffer-file-path (buffer-file-name))
+                (parent-directory (file-name-directory buffer-file-path))
+                (db-name (annotate--filepath->local-database-name 
buffer-file-path)))
+      (setq-local annotate-file db-name))))
+
 (defun annotate-initialize ()
   "Load annotations and set up save and display hooks."
+  (annotate--maybe-database-set-buffer-local)
   (annotate-load-annotations)
   (add-hook 'after-save-hook                  #'annotate-save-annotations t t)
   ;; This hook  is needed to  reorganize the layout of  the annotation