[nongnu] elpa/annotate 696f4ee0cd 167/372: Merge pull request #55 from cage2/update-doc

[ELPA Syncer]

branch: elpa/annotate
commit 696f4ee0cd8364341a3169766a2181968568ed95
Merge: 0ae5752526 5b0bb094c9
Author: cage2 <1257703+cage2@users.noreply.github.com>
Commit: GitHub <noreply@github.com>

    Merge pull request #55 from cage2/update-doc
    
    - updated documentation to reflects changes in the code
---
 NEWS.org    |  83 ++++++++++++++++++++++++++++
 README.md   |  92 ------------------------------
 README.org  | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 annotate.el |   5 +-
 4 files changed, 267 insertions(+), 94 deletions(-)

diff --git a/NEWS.org b/NEWS.org
new file mode 100644
index 0000000000..a8ead98ba0
--- /dev/null
+++ b/NEWS.org
@@ -0,0 +1,83 @@
+- 2015-06-12 V0.1 Bastian Bechtold ::
+  First working release.
+
+- 2015-06-12 V0.1.1 Bastian Bechtold ::
+  Improve documentation and add license.
+
+- 2015-06-12 V0.1.2 Bastian Bechtold ::
+  Fix typo and version error.
+
+- 2015-06-15 V0.1.3 Bastian Bechtold ::
+  Improve README and auto-remove empty annotations created by earlier bug.
+
+- 2015-06-15 V0.1.4 Bastian Bechtold ::
+  Minor bug fixes.
+
+- 2015-06-15 V0.1.5 Bastian Bechtold ::
+  Annotations now work on long lines.
+
+- 2015-06-19 V0.2.0 Bastian Bechtold ::
+  Annotations can be exported as unified diff files.
+  Several smaller bug fixes.
+
+- 2015-06-19 V0.2.1 Bastian Bechtold ::
+  Now with fewer compile warnings (turns out, not really).
+
+- 2015-06-19 V0.2.2 Bastian Bechtold ::
+  Now with more compile warnings (0.2.1 didn't work).
+
+- 2015-07-02 V0.2.3 Bastian Bechtold ::
+  Can now disable minibuffer messages.
+
+- 2015-09-17 V0.2.4 Bastian Bechtold ::
+  Load and Clear don't mark buffer as modified any more.
+
+- 2015-09-21 V0.3.0 Bastian Bechtold ::
+  Add key bindings for jumping to next/previous annotation.
+
+- 2015-09-22 V0.3.1 Bastian Bechtold ::
+  Change key bindings for jumping as to conform with Emacs' standards.
+
+  Didn't change  the main key binding  though, because I don't  know a
+  good alternative.
+
+- 2015-09-23 V0.4.0 Bastian Bechtold ::
+  Completely reworked the display engine for annotations. You can now
+ have several annotations per line, and annotations should not
+ move any more when editing the line they are on. Finally,
+ annotations can now span several lines.
+
+- 2015-10-06 V0.4.3 Bastian Bechtold ::
+  Bugfixes. No more hidden newlines, no more annotations in undo-list,
+  no more error messages with annotations at bol, mark deactivated
+  after creating annotation, annotations auto-reflow on frame size
+  change.
+
+- 2015-10-06 V0.4.4 Bastian Bechtold ::
+  Added a new export system. Let's see if it turns out to be more
+  useful than the previous one.
+
+- 2016-08-25 V0.4.5 Bastian Bechtold ::
+  Bugfix release for unicode annotations and multiline annotations.
+
+- 2016-09-07 V0.4.6 Bastian Bechtold ::
+  Bugfix release for annotations ending on an empty line.
+
+- 2016-10-06 V0.4.7 Bastian Bechtold ::
+  Bugfix release for buffers without a file name.
+
+- 2019-12-09 V0.5.0 Bastian Bechtold, cage ::
+  - prevented crash when a window (containing annotations) is resized;
+  - prevented loss of undo tree when annotations is modified;
+  - positioning of annotation is customizable;
+  - added a summary window to display annotations; the summary results
+    can be filtered by a simple query language. Deleting or
+    modifying of annotation text is possible;
+  - info files can be annotated (thanks to randomwangran);
+  - annotated text on the same lines are highlighted with two
+    different, alternating, colors;
+  - annotate try to check file modifications using checksum and warns
+    user if the file has been modified when annotate minor mode was
+    not loaded;
+  - a simple heuristic is used to search for annotated text when
+    annotate mode is loaded.
diff --git a/README.md b/README.md
deleted file mode 100644
index 24081991d2..0000000000
--- a/README.md
+++ /dev/null
@@ -1,92 +0,0 @@
-Annotate.el [![MELPA][mi]][m] [![MELPA-STABLE][msi]][ms]
-===========
-
-[mi]: http://melpa.org/packages/annotate-badge.svg
-[m]: http://melpa.org/#/annotate
-[msi]: http://stable.melpa.org/packages/annotate-badge.svg
-[ms]: http://stable.melpa.org/#/annotate
-
-This package provides a minor mode `annotate-mode`, which can add annotations 
to arbitrary files without changing the files themselves. This is very useful 
for code reviews. When `annotate-mode` is active, `C-c C-a` will create, edit, 
or delete annotations. 
-
-![example-screenshot](https://raw.githubusercontent.com/bastibe/annotate.el/master/example.png)
-
-With an active region, `C-c C-a` creates a new annotation for that region. 
With no active region, `C-c C-a` will create an annotation for the word under 
point. If point is on an annotated region, `C-c C-a` will edit that annotation 
instead of creating a new one. Clearing the annotation deletes them.
-
-Use `C-c ]` to jump to the next annotation and `C-c [` to jump to the previous 
annotation.
-
-All annotations are saved in `annotate-file` (`~/.annotations` by default).
-
-Annotations can be exported `annotate-export-annotations` as commented unified 
diffs, like this:
-
-![diff-example-screenshot](https://raw.githubusercontent.com/bastibe/annotate.el/master/diff-example.png)
-
-Alternatively, they can be integrated `annotate-integrate-annotations` as 
comments into the current buffer, like this:
-
-![integrate-example-screenshot](https://raw.githubusercontent.com/bastibe/annotate.el/master/integrate-example.png)
-
-### Incompatibilities:
-
-- annotations in org-mode source blocks will be underlined, but the 
annotations don't show up. This is likely a fundamental incompatibility with 
the way source blocks are highlighted and the way annotations are displayed.
-
-This package is released under the MIT license.
-
-### Changelog
-
-- **2015-06-12 V0.1 Bastian Bechtold**  
-  First working release.
-
-- **2015-06-12 V0.1.1 Bastian Bechtold**  
-  Improve documentation and add license.
-
-- **2015-06-12 V0.1.2 Bastian Bechtold**  
-  Fix typo and version error.
-
-- **2015-06-15 V0.1.3 Bastian Bechtold**  
-  Improve README and auto-remove empty annotations created by earlier bug.
-
-- **2015-06-15 V0.1.4 Bastian Bechtold**  
-  Minor bug fixes.
-
-- **2015-06-15 V0.1.5 Bastian Bechtold**  
-  Annotations now work on long lines.
-
-- **2015-06-19 V0.2.0 Bastian Bechtold**  
-  Annotations can be exported as unified diff files.  
-  Several smaller bug fixes.
-
-- **2015-06-19 V0.2.1 Bastian Bechtold**  
-  Now with fewer compile warnings (turns out, not really).
-
-- **2015-06-19 V0.2.2 Bastian Bechtold**  
-  Now with more compile warnings (0.2.1 didn't work).
-
-- **2015-07-02 V0.2.3 Bastian Bechtold**  
-  Can now disable minibuffer messages.
-
-- **2015-09-17 V0.2.4 Bastian Bechtold**  
-  Load and Clear don't mark buffer as modified any more.
-
-- **2015-09-21 V0.3.0 Bastian Bechtold**  
-  Add key bindings for jumping to next/previous annotation.
-
-- **2015-09-22 V0.3.1 Bastian Bechtold**  
-  Change key bindings for jumping as to conform with Emacs' standards.  
-  Didn't change the main key binding though, because I don't know a good 
alternative.
-
-- **2015-09-23 V0.4.0 Bastian Bechtold**  
-  Completely reworked the display engine for annotations. You can now have 
several annotations per line, and annotations should not move any more when 
editing the line they are on. Finally, annotations can now span several lines.
-
-- **2015-10-06 V0.4.3 Bastian Bechtold**  
-  Bugfixes. No more hidden newlines, no more annotations in undo-list, no more 
error messages with annotations at bol, mark deactivated after creating 
annotation, annotations auto-reflow on frame size change.
-
-- **2015-10-06 V0.4.4 Bastian Bechtold**  
-  Added a new export system. Let's see if it turns out to be more useful than 
the previous one.
-  
-- **2016-08-25 V0.4.5 Bastian Bechtold**  
-  Bugfix release for unicode annotations and multiline annotations.
-
-- **2016-09-07 V0.4.6 Bastian Bechtold**  
-  Bugfix release for annotations ending on an empty line.
-
-- **2016-10-06 V0.4.7 Bastian Bechtold**  
-  Bugfix release for buffers without a file name.
diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..8369005749
--- /dev/null
+++ b/README.org
@@ -0,0 +1,181 @@
+#+OPTIONS: html-postamble:nil html-preamble:nil toc:nil
+#+AUTHOR:
+#+TITLE: Annotate.el
+
+[[http://melpa.org/#/annotate][http://melpa.org/packages/annotate-badge.svg]]
+
+[[http://stable.melpa.org/#/annotate][http://stable.melpa.org/packages/annotate-badge.svg]]
+
+* introduction
+
+This  package provides  a minor  mode ~annotate-mode~,  which can  add
+annotations   to   arbitrary   files  without   changing   the   files
+themselves. This is very useful for code reviews. When ~annotate-mode~
+is active, ~C-c C-a~ will create, edit, or delete annotations.
+
+[[https://raw.githubusercontent.com/bastibe/annotate.el/master/example.png]]
+
+* Usage
+
+** Quick start
+
+With an  active region, ~C-c  C-a~ creates  a new annotation  for that
+region. With no active region, ~C-c C-a~ will create an annotation for
+the word  under point. If point  is on an annotated  region, ~C-c C-a~
+will edit that annotation instead of  creating a new one. Clearing the
+annotation deletes them.
+
+Use ~C-c ]~ to jump to the next  annotation and ~C-c [~ to jump to the
+previous annotation.
+
+** Metadata
+
+All  annotations are  saved  in  ~annotate-file~ (=~/.annotations=  by
+default).
+
+Users of
+[[https://github.com/emacscollective/no-littering][no-littering]]
+can take advantage of its packages generated files management.
+
+**** related customizable variable
+     - ~annotate-file~
+
+** keybindings
+
+*** ~C-c  C-a~ (function annotate-annotate)
+    creates  a new annotation  for that
+    region. With no active region, ~C-c C-a~ will create an annotation for
+    the word  under point. If point  is on an annotated  region, ~C-c C-a~
+    will edit that annotation instead of  creating a new one. Clearing the
+    annotation deletes them.
+
+**** related customizable variable
+     - ~annotate-highlight~;
+     - ~annotate-highlight-secondary~;
+     - ~annotate-annotation~;
+     - ~annotate-annotation-secondary~;
+     - ~annotate-annotation-column~;
+     - ~annotate-annotation-max-size-not-place-new-line~;
+     - ~annotate-annotation-position-policy~.
+
+*** ~C-c ]~ (function annotate-next-annotation)
+    Jump to the next  annotation.
+
+*** ~C-c [~ (function annotate-previous-annotation)
+    Jump to the previous annotation.
+
+*** ~C-c C-s~ (function annotate-show-annotation-summary)
+    Show summary window.
+
+    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]].
+
+    The summary window allow editing and removing of annotation using
+    the provided buttons.
+
+    The annotation text can be pressed to and will open the annotated
+    file, placing the cursor at the point where the corresponding
+    annotated text appears.
+
+**** related customizable variable
+     - ~annotate-summary-ask-query~.
+
+* Exporting
+
+Annotations can be exported ~annotate-export-annotations~ as commented
+unified diffs, like this:
+
+[[https://raw.githubusercontent.com/bastibe/annotate.el/master/diff-example.png]]
+
+Alternatively, they can be integrated ~annotate-integrate-annotations~
+as comments into the current buffer, like this:
+
+[[https://raw.githubusercontent.com/bastibe/annotate.el/master/integrate-example.png]]
+
+**** related customizable variable
+     - ~annotate-integrate-marker~
+     - ~annotate-diff-export-context~
+     - ~annotate-integrate-highlight~
+     - ~annotate-fallback-comment~
+
+* More documentation
+
+ Please check ~M-x customize-group RET annotate~ as there is
+ extensive documentation for each customizable variable.
+
+* BUGS
+
+** Known bugs
+
+   Annotations in org-mode source blocks will be underlined, but the
+   annotations don't show up. This is likely a fundamental
+   incompatibility with the way source blocks are highlighted and the
+   way annotations are displayed.
+
+   Deleting the first  character of an annotated text  will remove the
+   annotation (this turned out to be useful, though).
+
+** Report bugs
+
+   To report bugs please, point your browser to the
+   [[https://github.com/bastibe/annotate.el/issues][issue tracker]].
+
+* Query Language
+
+  The summary window can shows  results filtered by criteria specified
+  with a very simple query language, the basis syntax for that language
+  is shown below:
+
+#+BEGIN_SRC text
+ [file-mask] [(and | or) [not] regex-note (and | or) [not] regexp-note ...]
+#+END_SRC
+
+where
+
+  - file-mask :: is a regular expression that should match the path of file
+    the annotation refers to;
+  - and, or, not :: you guess? Classics logical operators;
+  - regex-note :: the text of annotation must match this regular expression.
+
+** Examples
+
+#+BEGIN_SRC text
+  lisp$ and TODO
+#+END_SRC
+
+   matches the text ~TODO~ in all lisp files
+
+Parenthesis can be used for the expression related to the text of
+annotation, like this:
+
+#+BEGIN_SRC text
+ lisp$ and (TODO or important)
+#+END_SRC
+
+   the same as above but checks also for string `important'
+
+#+BEGIN_SRC text
+ /home/foo/
+#+END_SRC
+   matches all the annotation that refers to file in the directory
+   ~/home/foo~
+
+#+BEGIN_SRC text
+ /home/foo/ and not minor
+#+END_SRC
+
+   matches all the annotation that refers to file in the directory
+   ~/home/foo~ and that not contains the text ~minor~.
+
+#+BEGIN_SRC text
+ .* and "not"
+#+END_SRC
+ the quotation mark (") can be used to escape strings.
+
+As a shortcut, an empty query will match everything (just press
+~return~ at prompt).
+
+* LICENSE
+This package is released under the MIT license [[./LICENSE][LICENSE]]
diff --git a/annotate.el b/annotate.el
index 9bed16f2ba..953b4d8a52 100644
--- a/annotate.el
+++ b/annotate.el
@@ -57,7 +57,8 @@
 
 ;;;###autoload
 (define-minor-mode annotate-mode
-  "Toggle Annotate mode."
+  "Toggle Annotate mode.
+See https://github.com/bastibe/annotate.el/ for documentation."
   :init-value nil
   :lighter " Ann"
   :keymap (make-sparse-keymap)
@@ -2100,7 +2101,7 @@ Note: this function return the annotation part of the 
record, see
 
 The argument `query' is a string that respect a simple syntax:
 
-- [file-mask] (and | or) [not] regex-note (and | or) [not] regexp-note ...
+- [file-mask] [(and | or) [not] regex-note (and | or) [not] regexp-note ...]
 
 where