org-annotation-helper.el: using org-mode as a bookmark manager, a knowledge base, a research tool and more!

We want to be able to pass a URL, a document title and a selected region directly from a web browser to a running instance of Emacs.

1. Overview

You select a region on a web page, click a bookmarklet and a link to the web page, page title and selected region is saved in a designated Org file.

2. Components

2.1. New protocols

We define a remember:// url handler in the browser and use a shell script to handle the protocol. This script passes the information to a running Emacs process (using emacsclient or gnuclient). We use bookmarklets to create the remember:// urls dynamicly.

The protocol types currently recognized are:

remember://: start `remember' with the url and title filled in
annotation://: similar to `planner-annotation-as-kill' (org?)

The urls used internally will have the following form:

remember://<the web page url>::remember::<the title>::remember::<selection>

The title will be url-hex-encoded.

2.2. The bookmarklets

javascript:location.href='remember://' + location.href + '::remember::' + escape(document.title) + '::remember::' + escape(window.getSelection())

javascript:location.href='annotation://' + location.href + '::remember::' + escape(document.title) ;;

2.3. The handler

#!/bin/sh
# org-annotation-helper -- pass a remember-url to emacs
#
# Author: Geert Kloosterman <g.j.kloosterman@gmail.com>
# Date: Sat Nov 19 22:33:18 2005

if [ -z "$1" ]; then
        echo "$0: Error: no arguments given!" 1>&2
        exit 1
fi

# To test uncomment following line
#echo $1 >> /tmp/remember.out

emacsclient --eval "(progn (bzg/org-annotation-helper \"$1\" ) nil)"

3. Installation

3.1. Install org-annotation-helper.el

Install this script and require it in your .emacs (or wherever you want to do it).

(require 'org-annotation-helper)

3.2. Install the remember script

3.2.1. Save the handler as a script, and make sure it is executable, i.e. remember

3.2.2. Try it:

Make sure emacs is running and you have started its server mode using (server-start) in .emacs or M-x server-start.

Run this command from the command line:

$ remember 'remember://http%3A//orgmode.org/::remember::Org-Mode%20Homepage::remember::Notes'

Emacs should now show a remember window with a URL to remember.org

3.3. Add two bookmarklets

For firefox:

Right click on the bookmarks area of Firefox.
Select new bookmark.
In location fill the javascript code above (the bookmarklet)
Make sure "Load this bookmark in the sidebar is deselected

Try it. You should have now a url that starts with "remember://" and your browser will not know what do to with it.

3.4. Add the handler for the "remember://" URI

3.4.1. Firefox

To add a protocol handler (eg: remember://) in Firefox, take the following steps:

type in "about:config" in the location bar
right click, select New –> String
- the name should be "network.protocol-handler.app.remember"
- the value should be the executable, eg. "org-annotation-helper".

At least under Linux this does not need to be the full path to the executable.

See http://kb.mozillazine.org/Register_protocol for more details.

3.4.2. Opera

In Opera add the protocol in the Preferences->Advanced->Programs dialog.

3.5. Configure a template

I personally use the following template for this mode (all as one line):

("Weblink" ?w "* %c\n  :PROPERTIES:\n  :CREATED: %U\n  :END:\n  - link: %:link\n  - Quote:\n\n    %?%:region\n\n  - End Quote\n\n" "bookmarks.org" "WebLinks" )

%c: will be replaced with the hyperlink to the page, displaying the title of the page
%:link: will be replaced with the address of the page
%i: will be replaced with the selected text from the browser
%:region: will be replaced by the selected text from the web page (special characters will be in hex-code.)
%U: will be replaced by the current date
%?: the cursor will be placed here (you may also replace this escape with %& to make it completely non-interactive.)

By default the new remember notes are placed in the bookmarks.org file under the "Web links" section, but it can be easily overriden with C-u C-c C-c

3.6. Step 5

Enjoy!