[nongnu] elpa/annotate be998ca006 263/372: Merge pull request #81 from cage2/popup-annotation

[ELPA Syncer]

branch: elpa/annotate
commit be998ca00697ceb0029c7030c8f31c317c9e2fd6
Merge: 4cc32fc2fb 3e70e187b3
Author: cage2 <1257703+cage2@users.noreply.github.com>
Commit: GitHub <noreply@github.com>

    Merge pull request #81 from cage2/popup-annotation
    
    Popup annotation
---
 Changelog   |  28 +++++++++
 NEWS.org    |   4 ++
 README.org  |  45 +++++++++++++-
 annotate.el | 198 +++++++++++++++++++++++++++++++++++++++++-------------------
 4 files changed, 211 insertions(+), 64 deletions(-)

diff --git a/Changelog b/Changelog
index 1e4a97edd1..25e8def880 100644
--- a/Changelog
+++ b/Changelog
@@ -1,3 +1,31 @@
+2020-09-29
+        * README.org, annotate.el
+       - updated README;
+       - increased version;
+       - updated NEWS and Changelog.
+
+2020-09-22
+        * annotate.el
+       - added   command   'annotate-summary-of-file-from-current-pos';
+       this command shows a summary window that contains the annotation
+       in the  active buffer  that appears after  the cursor  position;
+       - added docstrings.
+
+2020-09-20
+        * annotate.el
+       - fixed indentation.
+
+2020-09-20
+        * annotate.el
+       - Using "help-echo" to print annotations instead of render it on the
+        buffer.
+       This feature is optional and can be activated using the
+        customizable variable 'annotate-use-echo-area'
+
+2020-09-20
+        * README.org
+       - Removed internal link because of issue #79.
+
 2020-08-11
        * annotate.el (annotate-annotate, annotate-load-annotation-data
                       annotate-create-annotation, 
annotate-summary-query-parse-note,
diff --git a/NEWS.org b/NEWS.org
index a67f0f5464..98f8a20ca2 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -126,3 +126,7 @@
 
 - 2020-08-11 V0.8.3 Bastian Bechtold, cage ::
   Some function now signal errors where appropriate.
+
+- 2020-09-29 V0.9.0 Bastian Bechtold, cage ::
+  Added two new styles to render the annotation: using "pop-up" style
+  or via a specializated summary window.
diff --git a/README.org b/README.org
index cf40f0b717..615ede331d 100644
--- a/README.org
+++ b/README.org
@@ -78,7 +78,8 @@ can take advantage of its packages generated files management.
     A window with a list of annotated files together with their
     annotations is shown. If ~annotate-summary-ask-query~ is non nil
     (default is ~t~) then a prompt is shown where the user can insert
-    a query to filter the annotation database, see [[Query Language]].
+    a query to filter the annotation database, see "Query Language"
+    below.
 
     The summary window allow editing and removing of annotation using
     the provided buttons.
@@ -108,6 +109,46 @@ as comments into the current buffer, like this:
      - ~annotate-integrate-highlight~
      - ~annotate-fallback-comment~
 
+* Alternative visualization of annotations
+
+For typographically difficult scenarios (or just because you prefer
+it), such as variable-width fonts or overlay-heavy modes, the default
+visualization system that renders the annotation into the buffer could
+not properly works.
+
+In this case the users can switch to a "pop-up" style annotation
+setting to a non-nil value the variable ~annotate-use-echo-area~.
+
+When such variable's value is not null, moving the mouse pointer over
+the annotated text will temporary show the annotation.
+
+The actual visuals of this "pop-up" can be different depending of your
+system's setup (see
+[[https://github.com/bastibe/annotate.el/pull/81][this pull request]]
+for a couple of examples.
+
+Another alternative way to show annotations is provided by the command:
+~annotate-summary-of-file-from-current-pos~.
+
+Calling this command will show a summary window that prints all the
+annotations related to annotated text that appears (in the active
+buffer) beyond the current cursor position.
+
+**** related customizable variable
+     - ~annotate-use-echo-area~
+
+* Other commands
+
+** annotate-switch-db
+
+This command will ask the user for a new annotation database files,
+load it and refresh all the annotations contained in each buffer where
+annotate minor mode is active.
+
+See the docstring for more information and
+[[https://github.com/bastibe/annotate.el/issues/68][this thread]]
+for a possible workflow where this command could be useful.
+
 * More documentation
 
  Please check ~M-x customize-group RET annotate~ as there is
@@ -124,7 +165,7 @@ as comments into the current buffer, like this:
 
    - Because   of  a   limitation  in   the  Emacs   display  routines
      ~scroll-down-line~ could get stuck on a annotated line. So no fix
-     can  be  provided by  the  autors  of ~annotate.el~,  a  possible
+     can  be  provided by  the  authors  of ~annotate.el~,  a  possible
      workaround is to call the command with a numeric prefix equals to
      one plus the number of  annotation text lines below the annotated
      text.
diff --git a/annotate.el b/annotate.el
index dfd1251392..17ac590901 100644
--- a/annotate.el
+++ b/annotate.el
@@ -7,7 +7,7 @@
 ;; Maintainer: Bastian Bechtold
 ;; URL: https://github.com/bastibe/annotate.el
 ;; Created: 2015-06-10
-;; Version: 0.8.3
+;; Version: 0.9.0
 
 ;; This file is NOT part of GNU Emacs.
 
@@ -58,7 +58,7 @@
 ;;;###autoload
 (defgroup annotate nil
   "Annotate files without changing them."
-  :version "0.8.3"
+  :version "0.9.0"
   :group 'text)
 
 ;;;###autoload
@@ -177,6 +177,13 @@ database is not filtered at all."
   :type  'symbol
   :group 'annotate)
 
+(defcustom annotate-use-echo-area nil
+ "Whether annotation text should apperar in the echo area only when mouse
+id positioned over the annotated text instead of positioning them in
+the the buffer (the default)."
+  :type 'boolean
+  :group 'annotate)
+
 (defconst annotate-prop-chain-position
   'position)
 
@@ -381,10 +388,14 @@ modified (for example a newline is inserted)."
   (add-hook 'window-configuration-change-hook 'font-lock-fontify-buffer  t t)
   (add-hook 'before-change-functions          'annotate-before-change-fn t t)
   (add-hook 'Info-selection-hook              'annotate-info-select-fn   t t)
-  (font-lock-add-keywords
-   nil
-   '((annotate--font-lock-matcher (2 (annotate--annotation-builder))
-                                  (1 (annotate--change-guard))))))
+  (if annotate-use-echo-area
+      (font-lock-add-keywords
+       nil
+       '((annotate--font-lock-matcher (2 (annotate--annotation-builder)))))
+    (font-lock-add-keywords
+     nil
+     '((annotate--font-lock-matcher (2 (annotate--annotation-builder))
+                                    (1 (annotate--change-guard)))))))
 
 (defun annotate-shutdown ()
   "Clear annotations and remove save and display hooks."
@@ -393,10 +404,14 @@ modified (for example a newline is inserted)."
   (remove-hook 'window-configuration-change-hook 'font-lock-fontify-buffer  t)
   (remove-hook 'before-change-functions          'annotate-before-change-fn t)
   (remove-hook 'Info-selection-hook              'annotate-info-select-fn   t)
-  (font-lock-remove-keywords
-   nil
-   '((annotate--font-lock-matcher (2 (annotate--annotation-builder))
-                                  (1 (annotate--change-guard))))))
+  (if annotate-use-echo-area
+      (font-lock-remove-keywords
+       nil
+       '((annotate--font-lock-matcher (2 (annotate--annotation-builder)))))
+    (font-lock-remove-keywords
+     nil
+     '((annotate--font-lock-matcher (2 (annotate--annotation-builder))
+                                    (1 (annotate--change-guard)))))))
 
 (defun annotate-overlay-filled-p (overlay)
   "Does this overlay contains an 'annotation' property?"
@@ -911,25 +926,27 @@ to 'maximum-width'."
                   (overlay-put ov
                                'face
                                (overlay-get first-in-chain 'face))))
-            (when (annotate-chain-last-p ov)
-              (when position-new-line-p
-                (setf prefix-first " \n"))
-              (dolist (l multiline-annotation)
-                (setq annotation-text
-                      (concat annotation-text
-                              prefix-first
-                              (propertize l 'face face)
-                              annotation-stopper))
-                ;; white space before for all but the first annotation line
-                (if position-new-line-p
-                    (setq prefix-first (concat prefix-first prefix-rest))
-                  (setq prefix-first prefix-rest))))))
-        ;; build facespec with the annotation text as display property
-        (if (string= annotation-text "")
-          ;; annotation has been removed: remove display prop
-          (list 'face 'default 'display nil)
-        ;; annotation has been changed/added: change/add display prop
-        (list 'face 'default 'display annotation-text))))))
+            (when (and (not annotate-use-echo-area)
+                       (annotate-chain-last-p ov))
+                (when position-new-line-p
+                  (setf prefix-first " \n"))
+                (dolist (l multiline-annotation)
+                  (setq annotation-text
+                        (concat annotation-text
+                                prefix-first
+                                (propertize l 'face face)
+                                annotation-stopper))
+                  ;; white space before for all but the first annotation line
+                  (if position-new-line-p
+                      (setq prefix-first (concat prefix-first prefix-rest))
+                    (setq prefix-first prefix-rest))))))
+        (when (not annotate-use-echo-area)
+          ;; build facespec with the annotation text as display property
+          (if (string= annotation-text "")
+              ;; annotation has been removed: remove display prop
+              (list 'face 'default 'display nil)
+            ;; annotation has been changed/added: change/add display prop
+            (list 'face 'default 'display annotation-text)))))))
 
 (defun annotate--remove-annotation-property (begin end)
   "Cleans up annotation properties associated with a region."
@@ -1343,6 +1360,17 @@ annotation."
              db-records))
        db-records))))
 
+(defun annotate-db-annotations-starts-before-p (a b)
+  "Non nil if  annotation `a' starts before `b'.
+
+In this context annotation means annotation loaded from local
+database not the annotation shown in the buffer (therefore these
+arguments are 'record' as called in the other database-related
+funcions).
+"
+  (< (annotate-beginning-of-annotation a)
+     (annotate-beginning-of-annotation b)))
+
 ;;;; database related procedures ends here
 
 (defun annotate-clear-annotations ()
@@ -1523,6 +1551,8 @@ The searched interval can be customized setting the 
variable:
                                     (highlight (make-overlay start 
end-overlay)))
                                (overlay-put highlight 'face 
'annotate-highlight)
                                (overlay-put highlight 'annotation 
annotation-text)
+                               (annotate-overlay-maybe-set-help-echo highlight
+                                                                     
annotation-text)
                                (annotate-annotation-chain-position highlight
                                                                    
annotate-prop-chain-pos-marker-last)
                                (push highlight all-overlays))))))
@@ -1629,6 +1659,22 @@ The searched interval can be customized setting the 
variable:
           (goto-char end)
           (font-lock-fontify-block 1))))))
 
+(defun annotate-overlay-put-echo-help (overlay text)
+  "Set the property `help-echo' to `text' in overlay `overlay'."
+  (overlay-put overlay 'help-echo text))
+
+(defun annotate-overlay-get-echo-help (overlay)
+  "Set the property `help-echo' from overlay `overlay'."
+  (overlay-get overlay 'help-echo))
+
+(defun annotate-overlay-maybe-set-help-echo (overlay annotation-text)
+  "Set the property `help-echo' to `text' in overlay `overlay' if
+the annotations should be shown in a popup fashion.
+
+See the variable: `annotate-use-echo-area'."
+  (when annotate-use-echo-area
+    (annotate-overlay-put-echo-help overlay annotation-text)))
+
 (defun annotate-change-annotation (pos)
   "Change annotation at point. If empty, delete annotation."
   (let* ((highlight       (annotate-annotation-at pos))
@@ -1646,17 +1692,18 @@ The searched interval can be customized setting the 
variable:
                 (change (annotation)
                   (let ((chain (annotate-find-chain annotation)))
                     (dolist (single-element chain)
-                        (overlay-put single-element 'annotation 
annotation-text)))))
-    (save-excursion
-      (cond
-       ;; annotation was cancelled:
-       ((null annotation-text))
-       ;; annotation was erased:
-       ((string= "" annotation-text)
-        (delete highlight))
-       ;; annotation was changed:
-       (t
-        (change highlight)))))))
+                      (annotate-overlay-maybe-set-help-echo single-element 
annotation-text)
+                      (overlay-put single-element 'annotation 
annotation-text)))))
+      (save-excursion
+        (cond
+         ;; annotation was cancelled:
+         ((null annotation-text))
+         ;; annotation was erased:
+         ((string= "" annotation-text)
+          (delete highlight))
+         ;; annotation was changed:
+         (t
+          (change highlight)))))))
 
 (defun annotate-make-prefix ()
   "An empty string from the end of the line upto the annotation."
@@ -1907,7 +1954,7 @@ sophisticated way than plain text"
         (annotate-dump-annotation-data replaced-annotation-db)
         (annotate-show-annotation-summary query)))))
 
-(defun annotate-show-annotation-summary (&optional arg-query)
+(defun annotate-show-annotation-summary (&optional arg-query cut-above-point)
  "Show a summary of all the annotations in a temp buffer, the
 results can be filtered with a simple query language: see
 `annotate-summary-filter-db'."
@@ -2023,7 +2070,8 @@ results can be filtered with a simple query language: see
                                ".*"))))
     (let* ((filter-query (get-query))
            (dump         (annotate-summary-filter-db 
(annotate-load-annotation-data t)
-                                                     filter-query)))
+                                                     filter-query
+                                                     cut-above-point)))
       (if (db-empty-p dump)
           (when annotate-use-messages
             (message "The annotation database is empty"))
@@ -2467,7 +2515,7 @@ Note: this function return the annotation part of the 
record, see
                           (list (format "Unknown operator: %s is not in '(and, 
or)"
                                         (annotate-summary-query-lexer-string 
operator-token))))))))))))))
 
-(defun annotate-summary-filter-db (annotations-dump query)
+(defun annotate-summary-filter-db (annotations-dump query 
remove-annotations-cutoff-point)
   "Filter an annotation database with a query.
 
 The argument `query' is a string that respect a simple syntax:
@@ -2502,7 +2550,12 @@ annotation, like this:
 
 - .* and \"not\"
  the \" can be used to escape strings
-"
+
+If you want to remove from summary the annotations that appears
+before a position in buffer set `remove-annotations-cutoff-point' to said
+position.
+
+The annotations in each record are sorted by starting point in ascending 
order."
   (let* ((parser             (annotate-summary-query-parse-expression))
          (filter-file        (lambda (file-mask annotation-dump)
                                (let ((filename
@@ -2514,27 +2567,48 @@ annotation, like this:
                                                     
(annotate-annotation-string annotation-dump-2))
                                     annotation-dump-2)))
          (filter             (lambda (single-annotation)
-                                (let ((filtered-annotations (funcall parser
-                                                                     
single-annotation
-                                                                     query
-                                                                     
filter-file
-                                                                     
filter-annotations)))
-                                  (setf filtered-annotations
-                                        (cl-remove-if 'null 
filtered-annotations))
-                                  (when filtered-annotations
-                                    (let ((filename 
(annotate-filename-from-dump
-                                                     single-annotation))
-                                          (checksum 
(annotate-checksum-from-dump
-                                                     single-annotation)))
-                                      (annotate-make-annotation-dump-entry 
filename
-                                                                           
filtered-annotations
-                                                                           
checksum))))))
-         (filtered           (mapcar filter annotations-dump)))
-    (cl-remove-if 'null filtered)))
+                               (let ((filtered-annotations (funcall parser
+                                                                    
single-annotation
+                                                                    query
+                                                                    filter-file
+                                                                    
filter-annotations)))
+                                 (setf filtered-annotations
+                                       (cl-remove-if 'null 
filtered-annotations))
+                                 (when filtered-annotations
+                                   (let ((filename (annotate-filename-from-dump
+                                                    single-annotation))
+                                         (checksum (annotate-checksum-from-dump
+                                                    single-annotation)))
+                                     (setf filtered-annotations
+                                           (sort filtered-annotations
+                                                 
'annotate-db-annotations-starts-before-p))
+                                     (when remove-annotations-cutoff-point
+                                       (setf filtered-annotations
+                                             (cl-remove-if (lambda (a)
+                                                             (< 
(annotate-ending-of-annotation a)
+                                                                
remove-annotations-cutoff-point))
+                                                           
filtered-annotations)))
+                                     (annotate-make-annotation-dump-entry 
filename
+                                                                          
filtered-annotations
+                                                                          
checksum))))))
+         (filtered           (cl-remove-if 'null (mapcar filter 
annotations-dump))))
+    filtered))
 
 ;;;; end of filtering: parser, lexer, etc.
 
-;;;; switching database
+;;;; misc commands
+
+(defun annotate-summary-of-file-from-current-pos ()
+ "Shows a summary window that contains only the annotations in
+the current buffer and that starts after the current cursor's
+position."
+  (interactive)
+  (with-current-buffer (current-buffer)
+    (when buffer-file-name
+      (annotate-show-annotation-summary buffer-file-name (point)))))
+
+
+;;; switching database
 
 (defun annotate-buffers-annotate-mode ()
  "Returns a list of all the buffers that have