NonGNU ELPA - annotate

annotate

Description
annotate files without changing them
Latest
annotate-1.5.4.tar, 2022-Apr-28, 920 KiB
Maintainer
Bastian Bechtold <bastibe.dev@mailbox.org>, cage <cage-dev@twistfold.it>
Website
https://github.com/bastibe/annotate.el
Browse ELPA's repository
CGit or Gitweb
Badge

To install this package, run in Emacs:

M-x package-install RET annotate RET

Full description

1 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.

example.png

2 Usage

2.1 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. 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.

2.2 Metadata

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.

To use multiple database in the same Emacs session annotate-file should be made buffer-local, see: this thread and, in particular this message.

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.

Users of no-littering can take advantage of its packages generated files management.

  1. related customizable variable
    • annotate-file
    • annotate-warn-if-hash-mismatch
    • annotate-database-confirm-deletion

2.3 keybindings

2.3.1 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.

  1. related customizable variable
    • annotate-annotation-column;
    • annotate-annotation-confirm-deletion;
    • annotate-annotation-max-size-not-place-new-line;
    • annotate-annotation-position-policy;
    • annotate-annotation-secondary;
    • annotate-annotation;
    • annotate-endline-annotate-whole-line;
    • annotate-highlight-secondary;
    • annotate-highlight.
2.3.2 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.

  1. related customizable variable
    • annotate-annotation-confirm-deletion.
2.3.3 C-c ] (function annotate-goto-next-annotation)

Jump to the next annotation.

2.3.4 C-c [ (function annotate-goto-previous-annotation)

Jump to the previous annotation.

2.3.5 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.

  1. related customizable variable
    • annotate-summary-ask-query.

3 Exporting

Annotations can be exported annotate-export-annotations as commented unified diffs, like this:

diff-example.png

Alternatively, they can be integrated annotate-integrate-annotations as comments into the current buffer, like this:

integrate-example.png

  1. related customizable variable
    • annotate-integrate-marker
    • annotate-diff-export-options
    • annotate-integrate-highlight
    • annotate-fallback-comment

4 Importing

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.

  1. related customizable variable
    • annotate-database-confirm-import.

5 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 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.

  1. related customizable variable
    • annotate-use-echo-area

6 Other commands

6.1 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 this thread for a possible workflow where this command could be useful.

7 More documentation

Please check M-x customize-group RET annotate as there is extensive documentation for each customizable variable.

8 BUGS

8.1 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.
  • 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 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.

    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.

  • Deleting the first character of an annotated text will remove the annotation (this turned out to be useful, though).

8.2 Report bugs

To report bugs please, point your browser to the issue tracker.

9 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:

[file-mask] [(and | or) [not] regex-note [(and | or) [not] regexp-note ...]]

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.

9.1 Examples

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).

10 FAQ

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.

11 LICENSE

This package is released under the MIT license, see file LICENSE

Old versions

annotate-1.5.3.tar.lz2022-Apr-08 644 KiB
annotate-1.5.2.tar.lz2022-Apr-07 643 KiB
annotate-1.5.1.tar.lz2022-Feb-25 643 KiB
annotate-1.5.0.tar.lz2022-Feb-04 643 KiB

News

2022-01-26 v1.5.3 cage
This version fixed the email maintainer list that was previously confusing GNU ELPA building scripts.
2022-01-26 v1.5.2 cage
This version fixed a bug that prevented an annotation to be actually deleted when the only action on the buffer was a single call of the command `annotate-delete-annotation'. Also, again thanks to the help of an Emacs maintainer, the code was simplified and cleaned, and a few of docstring was improved too.
2022-01-26 v1.5.1 cage
This version refactored a lot of code thanks to the suggestions of Emacs maintainer. Several unused variables were removed and some portion of the code was simplified.
2022-01-26 v1.5.0 cage
This version add a new command to import a database file.
2021-09-30 v1.4.3 cage

This is a bugfix release.

The program would keep asking to confirmation for deleting a database file even if such file does not actually exists on the file system.

When the only action on a buffer was deleting an annotation, the buffer was not marked as modified; as a consequence, the deletion would not happens on the database (the database entry for the annotation to be deleted would not be removed from the file) and, when visiting the file, the annotation would be shown again.

2021-09-24 v1.4.2 cage
This version added a new command to delete the annotation under cursor.
2021-05-27 V1.3.1 cage

Bugfix release:

  • The button "[replace]" to edit an annotation from the summary window was not working at all;
  • In certain cases the summary window was rendering wrong text's fragment instead of the text of the annotation.

Many thanks to "glvno" for reporting the aforementioned bugs and testing the patches!

2021-05-07 V1.3.0 cage

This version added a procedure to prevent an empty database to be saved on the user's disk.

Moreover if an empty annotations database is going to overwrite an existing stale database file on disk the file is deleted instead.

Before deleting the old database file a confirmation message is printed on the minibuffer if the custom variable 'annotate-database-confirm-deletion' is non nil (default: t).

2021-05-05 V1.2.1 Bastian Bechtold, cage
This version fixes a bug that prevented command like 'comment-region' to works properly when annotate-mode was active.
2021-04-27 V1.2 Bastian Bechtold, cage

New feature. When the customizable variable `annotate-endline-annotate-whole-line' is not nil (default t), and and the user try to annotate a newline the whole line is annotated instead (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.

Also this version generates smaller database as files left with no annotations will not be saved on disk.

Finally annotating read-only buffers (especially deleting annotations) should works without problems.

2021-03-17 V1.1.5 Bastian Bechtold, cage

Removed compilation warnings, one of the problem highlighted by a warning was actually preventing this package working on Doom Emacs.

Also a bug that prevented annotations placed on info files to be deleted has been fixed.

Many thanks to many people that helped discovering and suggesting fix for these problems!

2021-02-05 V1.1.4 Bastian Bechtold, cage
Fixed highlight color of annotated text that starts from the first character of the buffer's content.
2021-01-06 V1.1.3 Bastian Bechtold, cage
Optimized the code to speedup reading and saving of encrypted (with GPG) annotated files.
2021-01-06 V1.1.2 Bastian Bechtold, cage
This version improves visual of multilined notes placed on the

… …