Skip to content
master
Go to file
Code

README.org

Annotate.el

http://melpa.org/packages/annotate-badge.svg

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

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.

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.

Users of 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-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.

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

Report bugs

To report bugs please, point your browser to the 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:

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

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

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.

LICENSE

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

You can’t perform that action at this time.