With this package you can add annotations to your files without
modifying them. Each file can have multiple annotations at various
buffer positions. The annotation texts are not parts of the files,
they are stored separately.

All annotations are stored in a common file, so searching
annotations is trivial.

Original author is TamasPatrovics. Current maintainer is XavierMaillard.

Lisp:ipa.el

Lisp:anything-ipa.el is [[Anything]] interface.

== Prettier Annotations ==
I like overlay which is above the target line. Because default IPA messes the line.

<pre>
;; REDEFINED!!
(defun ipa-set-overlay-text (overlay text)
  (if (string-match ipa-annotation-id-regexp text)
      (setq text (match-string 2 text)))
  (save-excursion
    (beginning-of-line)
    (overlay-put overlay 'before-string
                 (if (equal text "")
                     ""
                   (propertize (concat "[" text "]\n") 'face ipa-annotation-face)))))

;; REDEFINED!!
(defun ipa-create-overlay (pos text)
  (save-excursion
    (goto-char pos)
    (setq pos (point-at-bol))
    (let ((overlay (make-overlay pos pos nil t nil)))
     (ipa-set-overlay-text overlay text)
     (push (cons overlay text) ipa-annotations-in-buffer)
     (ipa-sort-overlays))))
</pre>

-- [[rubikitch]]

You can define a different face:

 (defface ipa '((t :foreground "green")) "Face for annotations." :group 'basic-faces)
 (defvar ipa-annotation-face 'ipa "Face for annotations.")

Also consider this changed version of the ipa-set-overlay-text above to indent:

 (defun string-repeat (str n)
   (let ((retval ""))
     (dotimes (i n)
       (setq retval (concat retval str)))
     retval))
 
 (defun ipa-set-overlay-text (overlay text)
   (if (string-match ipa-annotation-id-regexp text)
       (setq text (match-string 2 text)))
   (save-excursion
     (let ((ipa-indent-level (current-indentation)))
     (beginning-of-line)
     (overlay-put overlay 'before-string
                  (if (equal text "") ""
	 	   (propertize
	 	    (concat
	 	     (string-repeat " " ipa-indent-level) "* " text "\n")
	 	    'face ipa-annotation-face))))))

-- CH

[new:XavierMaillard:2009-02-14 22:33 UTC]
Thank you. I will check your code and see how I can integrate both
approach.


== Icon Annotations ==
I like using an icon instead of displaying text directly in the buffer.
Here is my modification of function ipa-set-overlay-text
<pre>
(defun ipa-set-overlay-text (overlay text)
  (if (string-match ipa-annotation-id-regexp text)
      (setq text (match-string 2 text)))
  (overlay-put overlay 'after-string
               (if (equal text  "")
                   ""
                 (propertize "!" 'display
                             `(image :type png
                                     :file "~/button-annotation-up.png"
                                     :ascent center)
                             'help-echo text))))
</pre>
-- Jingtao xu

== Problem with VisibleLines ==
InPlaceAnnotations does not work with VisibleLines in some condition. This advice solves the problem.
<pre>
(defadvice vertical-motion (around ipa activate)
  (let ((pos (point)))
    ad-do-it
    (when (and (= lines 1) (eq pos (point)))
      (vertical-motion 2))))
</pre>

-- [[rubikitch]]

== Feature Requests ==

=== Annotations on right? ===

I find the inline annotations to be kind of disruptive. I would rather have the
annotations float to the right of the text, without interfering with the
movement of point. Is it possible to do something like this:

<pre>
text
text
more text                       [annotation floats here]
suff here
</pre>

Where the annotation stays at some (configurable) offset from the rest of the
text? I looked into modifying it myself, but my overlay- and properties-foo is
not strong.

-- [[DanielHackney]]

=== Annotations in their own buffer, too? ===

To take Daniel's FR a step further, I'd love to see annotations also in their own 
buffer, as OrgAnnotateFile does.  Being able to displaying annotations in their 
own buffer AND inline in the file would be nothing short of magical wonderfulness.

: according to the source code you can switch to the file ~/.ipa which contains the annotations, so you can see all of them there and even can press return there on an annotation to go to the location  -- Anonymous

== 2012 update ==
I liked this mode so much I updated it and posted it on github. https://github.com/idomagal/ipa.el

I made the following modifications:

 - defvars moved into a customization group ('ipa)
 - I added rubikitch and CH 'above-the-line' as an option.
 - I added support for sidecar files, so each annotated file.txt saves out its own file.txt.ipa.

-Ido

== Indented multiline annotations ==
I noticed it is possible to insert multiline annotations by pressing M-j in the minibuffer. 
This function redefinition supports indenting multi-line annotations:
<pre>
;; REDEFINED!
(defun ipa-set-overlay-text-above (overlay text)
  (if (string-match ipa-annotation-id-regexp text)
      (setq text (match-string 2 text)))
  (save-excursion
    (let ((ipa-indent-level (current-indentation)))
      (beginning-of-line)
      (let ((text (mapconcat #'identity (split-string text "\n")
                             (concat "\n" (string-repeat " " (+ 2 ipa-indent-level))))))
        (overlay-put overlay 'before-string
                     (if (equal text "") ""
                       (propertize
                        (concat
                         (string-repeat " " ipa-indent-level) "* " text "\n")
                        'face ipa-annotation-face)))))))
</pre>
-- Alessandro