branch: elpa/annotate
commit 59c52e7318861cd43e60eb532116540cba91ff8b
Author: cage <cage-invalid@invalid>
Commit: cage <cage-invalid@invalid>
- updated documentation to reflects changes in the code
- added NEWS.org;
- changed format of README to ORG;
- expanded README contents.
---
NEWS.org | 83 +++++++++++++++++++++++++++++
README.md | 92 --------------------------------
README.org | 177 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 260 insertions(+), 92 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.
-
-
-
-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:
-
-
-
-Alternatively, they can be integrated `annotate-integrate-annotations` as
comments into the current buffer, like this:
-
-
-
-### 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..8df768df00
--- /dev/null
+++ b/README.org
@@ -0,0 +1,177 @@
+#+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~
+ 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 ]~
+ Jump to the next annotation.
+
+*** ~C-c [~
+ Jump to the previous annotation.
+
+*** ~C-c C-s~
+ 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-higlight~
+ - ~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.
+
+** 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 ~"~ 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]]
![http://melpa.org/#/annotate][http://melpa.org/packages/annotate-badge.svg](http://melpa.org/#/annotate][http://melpa.org/packages/annotate-badge.svg){kind=link}
![http://stable.melpa.org/#/annotate][http://stable.melpa.org/packages/annotate-badge.svg](http://stable.melpa.org/#/annotate][http://stable.melpa.org/packages/annotate-badge.svg){kind=link}