Annotation mode

[PT]

I'm looking for a mode for annotating files without modifying the
file's contents, so the anotations are stored separately from the
actual files.

The desired features:

- I want to add textual annotations to a file while reading it. I'm
thinking of hitting a key which pops up a window showing the existing
annotation (if any) for the file. I can edit the annotation and when I
close the window it is saved automatically.

- When a global annotation mode is enabled the currently stored
annotations are always shown for the current buffer.

- I'd like a browser which shows the existing anotations with the
corresponding file names, so that I don't have to open the actual files
if I want to see their annotations. The annotations should be
searchable. Preferably they could also be edited from the annotation
browser.

I tried to search with Google for a similar thing, but didn't find
anything. Thought I asked here first, before starting hacking my own
implementation.

[Joe Corneli]

I've been working on a very sophisticated system for doing things like
this. You can find it in CVS at http://www.nongnu.org/hdm/ under the
"scholium-system" subdirectory when the code is checked out. It might
need a little hacking to get it to do everything you want; its
currently pre-release, but just barely. (I'd be happy to accept
contributed code.)

If you want to start with something simpler, you could also take a
look at

http://lists.gnu.org/archive/html/help-gnu-emacs/2005-07/msg00276.html

[PT]

I took a look at the options and decided to implement my own solution,
since it was pretty easy. Here it is if someone is interested:

;;; annotate.el --- simple file annotation system
;;;
;;;
;;; M-x annotate-file pops up a window where the annotation for the
;;; current file can be edited. If the annotation window is left open
;;; it always shows the annotation belonging to the current buffer.
;;;
;;;

;;; Code:

(defvar annotate-storage-file "~/.annotate"
"File containing the stored annotations.")

(defvar annotate-current-buffer nil
"The last buffer known to be the current one.")

(defvar annotate-window-configuration nil
"The window configuration before the annoation buffer was
displayed.")

(defun annotate-file ()
(interactive)
(annotate-narrow-to-annotation)

(setq annotate-window-configuration (current-window-configuration))
(pop-to-buffer (get-file-buffer annotate-storage-file))

(local-set-key (kbd "C-c C-c") 'annotate-finish)
(message "Type C-c C-c to hide the annotation buffer.")

(setq annotate-current-buffer 'nosuchbuffer)
(ad-activate 'switch-to-buffer))

(defun annotate-narrow-to-annotation ()
"Narrow the annotation buffer to the portion belonging to the file
associated
wit the current buffer.
If no annotation exists for the file a new section is created.

If the current buffer has no file associated with it then show a
warning message."
(let* ((buffer (find-file-noselect annotate-storage-file))
(file (buffer-file-name))
(filename (if file
(expand-file-name file)
"nofile")))

(with-current-buffer buffer
(widen)
(unless (equal filename (expand-file-name annotate-storage-file))
(goto-char (point-min))
(if (re-search-forward (concat "^ " filename) nil t)
(forward-line)
(goto-char (point-min))
(insert " " filename "\n\n")
(forward-line -1))

(let ((begin (point)))
(if (re-search-forward "^" nil t)
(progn (forward-line -1)
(end-of-line))
(goto-char (point-max)))
(narrow-to-region begin (point))
(goto-char (point-min)))

;; prepare warning message if it does not exist yet
(if (and (not file)
(= (point-min) (point-max)))
(insert "The current buffer has no file associated with it,
"
"so it cannot have an annotation."))))))

(defadvice switch-to-buffer (after annotate-handle-buffer-change)
(annotate-update-annotation-display))

(defun annotate-update-annotation-display ()
"Synchronize the displayed annotation to the current buffer if the
annotation
window is visible. Otherwise cancel current buffer monitoring."
(if (get-buffer-window (get-file-buffer annotate-storage-file))
(unless (equal (current-buffer) annotate-current-buffer)
(setq annotate-current-buffer (current-buffer))
(annotate-narrow-to-annotation))

(ad-deactivate 'switch-to-buffer)))

(defun annotate-finish ()
"Hide the annotation buffer and restore previous window
configuration."
(interactive)
(set-window-configuration annotate-window-configuration)
(with-current-buffer (get-file-buffer annotate-storage-file)
(save-buffer)))

(provide 'annotate)
;;; annotate.el ends here

[Joe Corneli]

If you think people might be interested, you should
probably release the software under the GPL.

[Enila Nero]

Useful concept. The code fails if the buffer of annotate-storage-file
is deleted, and then one tries to find a file. A good feature would
be to have an annotate-storage-file per directory.

[PT]

Okay. I simply added the GNU license to the file. Hope it's enough.
I also fixed the bug reported by Enila Nero.

I don't intend to spend time improving the package, since it already
does what I want. If someone's interested in improving it it's up for
grabs.

I was a bit suprised Emacs didn't have something like this built in
given its 20 or so years of history. The concept seems fairly trivial
to me.

Here's the revised code. (The line beginning character in
re-search-forward is supposed to be a Ctrl-L if for some reason it
doesn't get through properly.)

;; annotate.el --- simple file annotation system
;;

;; Copyright (C) 2005 Free Software Foundation, Inc.
;;
;; This file is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.
;;
;; This file is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to
;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.
;;
;;

;; M-x annotate-file pops up a window where the annotation for the
;; current file can be edited. If the annotation window is left open
;; it always shows the annotation belonging to the current buffer.
;;
;;

;;; Code:

(defvar annotate-storage-file "~/.annotate"
"File containing the stored annotations.")

(defvar annotate-current-buffer nil
"The last buffer known to be the current one.")

(defvar annotate-window-configuration nil
"The window configuration before the annoation buffer was
displayed.")

(defun annotate-file ()
(interactive)
(annotate-narrow-to-annotation)

(setq annotate-window-configuration (current-window-configuration))
(pop-to-buffer (get-file-buffer annotate-storage-file))

(local-set-key (kbd "C-c C-c") 'annotate-finish)

(message "Type C-c C-c to hide the annotation window.")

(if (get-buffer-window (let ((buffer (get-file-buffer
annotate-storage-file)))
(or buffer
(find-file-noselect
annotate-storage-file))))

(unless (equal (current-buffer) annotate-current-buffer)
(setq annotate-current-buffer (current-buffer))
(annotate-narrow-to-annotation))

(ad-deactivate 'switch-to-buffer)))

(defun annotate-finish ()
"Hide the annotation buffer and restore previous window
configuration."
(interactive)
(set-window-configuration annotate-window-configuration)
(with-current-buffer (get-file-buffer annotate-storage-file)

(widen)

[PT]

> A good feature would be to have an annotate-storage-file per directory.

One of my original goals was to a provide a way to browse the existing
annotations without having to visit the individual annotated files.
That's why I've choosen the single-file storage mechanism, since the
user can easily browse or search the existing annotations there.

A per directory storage wouldn't have this advantage.