To install this package, run in Emacs:
M-x package-install RET annotate RET
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. Typing C-c C-d
or clearing the annotation deletes them.
Use C-c ]
to jump to the next annotation and C-c [
to jump to the previous annotation.
The current database for annotations is contained in the file
indicated by the variable annotate-file
(~/.emacs.d/annotations
by
default) but each user can change this value in a dynamic way using
the command annotate-switch-db
. This command will take care to
refresh/redraw all annotations in the buffers that uses
annotate-mode
.
The database holds the hash of each annotated file so it can print a warning if the file has been modified outside Emacs (for example).
Warning can be suppressed setting the variable
annotate-warn-if-hash-mismatch
to nil.
Please note that switching database, in this context, means rebinding
the aforementioned variable (annotate-file
). This means than no
more than a single database can be active for each Emacs session.
If an empty annotation database (in memory) is saved the database
file is deleted instead, if annotate-database-confirm-deletion
is
non nil (the default) a confirmation action is asked to the user
before actually remove the file from the file system.
annotate-file
annotate-warn-if-hash-mismatch
annotate-database-confirm-deletion
To use multiple database in the same Emacs session annotate-file
should be made buffer-local,
see:
this thread and, in particular this message.
Finally, if the customizable variable annotate-file-buffer-local
is non-nil (default nil
), for each annotated file an annotation database is saved under the same directory that contains the annotated file.
The name of the annotation database is built concatenating the name of the annotated file without the optional extension and the string value bound to the customizable variable annotate-buffer-local-database-extension
(default: notes
), example follows:
annotated file | annotations file |
---|---|
/home/user/foo.c | /home/user/foo.notes |
Important note: if /home/user/foo.notes
exists, will be overwritten.
Users of no-littering can take advantage of its packages generated files management.
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.
If annotate-annotation-confirm-deletion
is non nil (the default is nil) a confirmation action is asked, using y-or-n-p
, to the user before actually remove the annotation.
If point is the newline character and the customizable variable annotate-endline-annotate-whole-line
is not nil (default is non nil) the whole line is annotated (or the next if the line is empty).
If the line contains a single annotation that cover all the line, annotating the newline will ask to edit the annotation. If annotate-endline-annotate-whole-line
is nil annotating a newline will signal an error.
With a numeric prefix the annotations will be displayed with the faces indicated in annotate-endline-annotate-whole-line
and annotate-annotation-text-faces
, respectively. The numeric prefix is used as index in the lists bound to the aforementioned variables.
The first theme can be addressed by the prefix 1
, the second by the prefix 2
and so on.
C-c C-d
Delete an annotation under point, if such annotation exists.
If annotate-annotation-confirm-deletion
is non nil (the default is nil) a confirmation action is asked, using y-or-n-p
, to the user before actually remove the annotation.
C-c ]
(function annotate-goto-next-annotation)Jump to the next annotation.
C-c [
(function annotate-goto-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"
below.
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.
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:
An annotation database file can be imported using the command annotate-import-annotations
.
When importing, overlapping annotations will be merged in a single annotation with the new annotated text that maximizes the portion of text annotated, e.g.
The quick brown fox ← text ^^^^^^^^ ← first annotation ******** ← second annotation +++++++++++++ ← merged annotation
The text of the merged annotation is the concatenated text of the two annotations.
Note that importing a database will modify permanently the file bound to the variable annotate-file
. If unsure of the results, backup that file before importing.
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 this pull request for a couple of examples.
Moreover if annotate-use-echo-area
and annotate-print-annotation-under-cursor
value both non null, placing the cursor over an annotated text region will print the annotation's text in the minibuffer prefixed by the value of customizable variable annotate-print-annotation-under-cursor-prefix
, after a delay (in seconds) defined by the variable annotate-print-annotation-under-cursor-delay
.
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.
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 this thread for a possible workflow where this command could be useful.
Shows or hides annotation's text under cursor.
Shows or hides the annotation's text in the whole buffer.
Please check M-x customize-group RET annotate
as there is extensive documentation for each customizable variable.
scroll-down-line
could get stuck on a annotated line. So no fix can be provided by the authors of annotate.el
, a possibleworkaround is to call the command with a numeric prefix equals to one plus the number of annotation text lines below the annotated text.
For example:
foo bar baz annotation
needs a prefix of 2: C-u 2 M-x scroll-down-line
But note that:
foo bar baz annotation
Needs no prefix.
To report bugs please, point your browser to the issue tracker.
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:
[file-mask] [(and | or) [not] regex-note [(and | or) [not] regexp-note ...]]
where:
lisp$ and TODO
matches the text TODO
in all lisp files
Parenthesis can be used for the expression related to the text of annotation, like this:
lisp$ and (TODO or important)
the same as above but checks also for string `important'
/home/foo/
matches all the annotation that refers to file in the directory /home/foo
/home/foo/ and not minor
matches all the annotation that refers to file in the directory /home/foo
and that not contains the text minor
.
.* and "not"
the quotation mark (") can be used to escape strings.
As a shortcut, an empty query will match everything (just press return
at prompt).
Sometimes the package does not respect the customizable variable's value of annotate-annotation-position-policy
, is this a bug?
No it is not, when a line which is using a non default font is annotated the software force the :new-line
policy, that is the annotation will be displayed on a new line regardless of the value of the variable mentioned in the question.
This is necessary to prevent the annotation to be pushed beyond the window limits if an huge font is used by the annotated text.
This package is released under the MIT license, see file LICENSE
annotate-2.0.1.tar.lz | 2023-Jul-09 | 650 KiB |
annotate-2.0.0.tar.lz | 2023-Apr-01 | 650 KiB |
annotate-1.9.0.tar.lz | 2023-Mar-10 | 650 KiB |
annotate-1.8.5.tar.lz | 2023-Feb-03 | 649 KiB |
annotate-1.8.4.tar.lz | 2022-Dec-19 | 649 KiB |
annotate-1.8.3.tar.lz | 2022-Dec-10 | 649 KiB |
annotate-1.8.2.tar.lz | 2022-Nov-22 | 648 KiB |
annotate-1.8.1.tar.lz | 2022-Oct-24 | 648 KiB |
annotate-1.8.0.tar.lz | 2022-Sep-30 | 648 KiB |
annotate-1.7.2.tar.lz | 2022-Sep-16 | 646 KiB |
annotate-1.7.1.tar.lz | 2022-Aug-09 | 646 KiB |
annotate-1.7.0.tar.lz | 2022-Jul-07 | 646 KiB |
annotate-1.6.0.tar.lz | 2022-Jun-03 | 644 KiB |
annotate-1.5.4.tar.lz | 2022-Apr-28 | 644 KiB |
annotate-1.5.3.tar.lz | 2022-Apr-08 | 644 KiB |
annotate-1.5.2.tar.lz | 2022-Apr-07 | 643 KiB |
annotate-1.5.1.tar.lz | 2022-Feb-25 | 643 KiB |
annotate-1.5.0.tar.lz | 2022-Feb-04 | 643 KiB |
This version ensures that querying the database will search in all the annotated buffers on the current Emacs session.
A phrase regarding the annotation of the newline character has been corrected in README.org
annotate-annotate
to allow setting specific colors
for each annotation.This versions prevented printing of a warning
`annotate-save-annotations' printed a warning if the buffer was not based on a file's contents. But the warning was printed even if the buffer contained no annotations at all.
This version prints the warning about missing file only if the buffer is annotated (i.e. contains at least an annotation).
This versions fixed a bug that prevented annotations of info files.
Also opening of annotated remote files should be faster.
This version fixed a crash that occurred when visiting an annotated buffer using TRAMP.
Thanks to gsingh93 for discovering the bug and providing an immensely useful help.
annotate-integrate-annotations
that
was corrupting the buffer containing the annotations, when used.This version allows printing of the annotation in the minibuffer when the cursor is placed over an annotated text region.
To activate this feature set to non nil the values of these two customizable variables:
annotate-use-echo-area
annotate-print-annotation-under-cursor
This version removed an error signalled when closing an annotated indirect buffer. Instead, when an annotated indirect buffer is killed annotate-mode will clone it into a new regular buffer so that the user can decide to save it in a file or discard it completely.
Thanks JuanManuelM!
… …