From 804c7b9421dd605f5e7c3bd00e54020c5df23677 Mon Sep 17 00:00:00 2001 From: cage Date: Sun, 20 Sep 2020 14:48:14 +0200 Subject: [PATCH 1/6] - Removed internal link because of issue #79. --- README.org | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.org b/README.org index cf40f0b..6657e2a 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. From c972641056ddcc1d8ef2c8cf1a89ab30e9f6505d Mon Sep 17 00:00:00 2001 From: cage Date: Sun, 20 Sep 2020 15:32:08 +0200 Subject: [PATCH 2/6] - 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' --- annotate.el | 86 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 28 deletions(-) diff --git a/annotate.el b/annotate.el index dfd1251..511bc53 100644 --- a/annotate.el +++ b/annotate.el @@ -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." @@ -1523,6 +1540,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 +1648,16 @@ 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) + (overlay-put overlay 'help-echo text)) + +(defun annotate-overlay-get-echo-help (overlay text) + (overlay-get overlay 'help-echo)) + +(defun annotate-overlay-maybe-set-help-echo (overlay annotation-text) + (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,7 +1675,8 @@ 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))))) + (annotate-overlay-maybe-set-help-echo single-element annotation-text) + (overlay-put single-element 'annotation annotation-text))))) (save-excursion (cond ;; annotation was cancelled: From 6543d3b1c0fea4396dac459669488c2b0c38b1f2 Mon Sep 17 00:00:00 2001 From: cage Date: Sun, 20 Sep 2020 15:36:11 +0200 Subject: [PATCH 3/6] - fixed indentation. --- annotate.el | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/annotate.el b/annotate.el index 511bc53..3fde2e2 100644 --- a/annotate.el +++ b/annotate.el @@ -1677,16 +1677,16 @@ The searched interval can be customized setting the variable: (dolist (single-element chain) (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))))))) + (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." From bd31608f504319c2e79976d45a58e40bc3bf150f Mon Sep 17 00:00:00 2001 From: cage Date: Tue, 22 Sep 2020 18:13:07 +0200 Subject: [PATCH 4/6] - 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. --- annotate.el | 90 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 67 insertions(+), 23 deletions(-) diff --git a/annotate.el b/annotate.el index 3fde2e2..83fbd87 100644 --- a/annotate.el +++ b/annotate.el @@ -1360,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 () @@ -1649,12 +1660,18 @@ The searched interval can be customized setting the variable: (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 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))) @@ -1937,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'." @@ -2053,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")) @@ -2497,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: @@ -2532,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 @@ -2544,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 From 7893fb3060dd644b7588125df3d78c548bc7d128 Mon Sep 17 00:00:00 2001 From: cage Date: Tue, 29 Sep 2020 19:27:27 +0200 Subject: [PATCH 5/6] - updated README. - increased version. --- README.org | 42 +++++++++++++++++++++++++++++++++++++++++- annotate.el | 4 ++-- 2 files changed, 43 insertions(+), 3 deletions(-) diff --git a/README.org b/README.org index 6657e2a..615ede3 100644 --- a/README.org +++ b/README.org @@ -109,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 @@ -125,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 83fbd87..17ac590 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 From 3e70e187b357a7845f2360caac101dac4b7c0acc Mon Sep 17 00:00:00 2001 From: cage Date: Tue, 29 Sep 2020 19:34:05 +0200 Subject: [PATCH 6/6] - updated NEWS and Changelog. --- Changelog | 28 ++++++++++++++++++++++++++++ NEWS.org | 4 ++++ 2 files changed, 32 insertions(+) diff --git a/Changelog b/Changelog index 1e4a97e..25e8def 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 a67f0f5..98f8a20 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.