How to use org-annotate-file?

Question

I recently found org-annotate-file. I would like to use it to annotate pdf documents or music files or any other files on my computer, and write my annotations in a file annotations.org. I am not looking to include annotations IN the pdf. But what I cannot figure out is what it means to "visit a file"? Does it have to be a file that emacs can open?

But more generally, is there a package that can do something like this: I visit a directory in dired mode, mark a bunch of files on some topic of my interest, and with one command I send links to the files to my annotations.org file (maybe as subheadings under a heading, which may be the directory name), and then I can write the annotations in the annotations file. Then with one command, I should be able to reach any of the files (which org-mode will allow) or open it in an external program. Is this possible in some package?

Thanks.

Diego Sevilla Diego Sevilla · Accepted Answer · 2011-09-04T00:10:07

Of course, it can be done. However, it seems the actual code of org-annotate-file.el, that I found here, doesn't seem to accept annotating a file that has not been opened (visited means here opened), because the function to annotate uses the current open file as a source for the name. The current implementation of org-annotate-file is this:

(defun org-annotate-file ()
  "Put a section for the current file into your annotation file"
  (interactive)
  (error-if-no-file)
  (org-annotate-file-show-section))

At least you could modify it to accept an arbitrary file (if you provide it):

(defun org-annotate-file (&optional filename)
  "Put a section for the current file into your annotation file"
  (interactive "FFile to tag: ")
  ; if a file is specified, bypass the check for error when no file
  (if filename
     (org-annotate-file-show-section filename)
     (progn
      (error-if-no-file)
      (org-annotate-file-show-section))))

This ask you for a file name whenever you do M-xorg-annotate-file.

You also have to change the org-annotate-file-show-section to accept either a file name or a buffer. The first let should be like this:

(defun org-annotate-file-show-section (&optional buffer-or-file)
  "Visit the buffer named `org-annotate-file-storage-file' and
show the relevant section"
  (let* ((line (buffer-substring-no-properties (point-at-bol) (point-at-eol)))
                 (filename (if (stringp buffer-or-file)
                            buffer-or-file
                            (get-filename buffer-or-file (buffer-file-name))))
                 (link (get-link filename))
         (search-link (org-make-link-string
                       (concat "file:" filename "::" line)
                               (org-annotate-file-prettyfy-desc line))))
        (show-annotations filename link)
.... rest of the code....

dired integration can be started from here, but I'm still not familiar with the dired API...

EDIT: I'm creating a branch in bitbucket for that modifications. I find the utility very useful and might use it myself. I'll post the link here. And here it is: https://bitbucket.org/dsevilla/org-annotate-file/src

How to use org-annotate-file?

1 Answers