Merge pull request #81 from cage2/popup-annotation

Popup annotation

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,

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.

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.