[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/annotate 59c52e7318 162/372: - updated documentation to re
From: |
ELPA Syncer |
Subject: |
[nongnu] elpa/annotate 59c52e7318 162/372: - updated documentation to reflects changes in the code |
Date: |
Fri, 4 Feb 2022 16:58:55 -0500 (EST) |
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.
-
-![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..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]]
- [nongnu] elpa/annotate 1350e1d073 338/372: - fixed annotated text shown in the summary window, (continued)
- [nongnu] elpa/annotate 1350e1d073 338/372: - fixed annotated text shown in the summary window, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate 3e3c1b1066 368/372: - fixed function name;, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate a484ffa0b6 319/372: - allowed removing (or cutting) annotations when buffer is in read-only mode., ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate 936389e36a 316/372: - prevented asking for annotation when trying to annotate a newline character., ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate 36d3729c27 339/372: - updated version number and docs., ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate a8762cd08a 344/372: - removed garbage at the end of an error message., ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate 9aba6305fe 342/372: Merge pull request #109 from cage2/fix-replace-button, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate bd12129213 333/372: Merge pull request #106 from cage2/fixed-call-comment-region, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate 83e81e0979 369/372: - added missing docstrings and improved a bit the old ones., ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate f5436b2bff 366/372: - added helper functions to manage annotation's interval and 'annotate-db-merge-annotations'., ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate 59c52e7318 162/372: - updated documentation to reflects changes in the code,
ELPA Syncer <=
- [nongnu] elpa/annotate fd9c403ecc 164/372: - changed quotation mark sentence., ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate a28e7b4fd2 028/372: refactored and documented export function, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate b2cd959cfa 053/372: Annotations of long lines start at the next line, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate e98c93a12b 072/372: - added 'annotate-' prefix to public symbols;, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate 6289c87bf8 029/372: annotation buffer now has proper file name, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate e1daa61b99 065/372: use `locate-user-emacs-file` to specify default save file, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate 392197f943 155/372: Merge branch 'master' into annotations-on-their-own-line, ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate 3bb486d0cf 158/372: - changed `let*' with `let'., ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate c007611614 159/372: - removed useless rebinding of 'annotate-annotation-position-policy'., ELPA Syncer, 2022/02/04
- [nongnu] elpa/annotate c7891d8d24 163/372: - tried to make the file more "site friendly"., ELPA Syncer, 2022/02/04