org-contrib/org-annotation-helper.org

   1 #+TITLE:     org-annotation-helper.el -- using org-mode as a bookmark manager, a knowledge base, a research tool and more!
   2 #+OPTIONS:   ^:{} author:nil
   3 #+STARTUP: odd
   4
   5 We want to be able to pass a URL, a document title and a selected
   6 region directly from a web browser to a running instance of Emacs.
   7
   8 * Oveview
   9   You select a region on a web page, click a bookmarklet and a link to
  10   the web page, page title and selected region is saved in a
  11   designated Org file.
  12
  13 * Components
  14 *** New protocols
  15 We define a remember:// url handler in the browser and use a shell
  16 script to handle the protocol.  This script passes the information to
  17 a running Emacs process (using =emacsclient= or =gnuclient=).  We use
  18 bookmarklets to create the =remember://= urls dynamicly.
  19
  20 The protocol types currently recognized are:
  21
  22 - remember:// :: start `remember' with the url and title filled in
  23 - annotation:// :: similar to `planner-annotation-as-kill' (org?)
  24
  25 The urls used internally will have the following form:
  26
  27   =remember://<the web page url>::remember::<the title>::remember::<selection>=
  28
  29 The title will be url-hex-encoded.
  30
  31 *** The bookmarklets
  32
  33 #+begin_src java
  34 javascript:location.href='remember://' + location.href + \
  35   '::remember::' + escape(document.title) + '::remember::' + escape(window.getSelection())
  36 #+end_src
  37
  38 #+begin_src java
  39 javascript:location.href='annotation://' + location.href + '::remember::' +\
  40     escape(document.title) ;;
  41 #+end_src
  42
  43 *** The handler
  44
  45 #+begin_src shell-script
  46
  47 #!/bin/sh
  48 # org-annotation-helper -- pass a remember-url to emacs
  49 #
  50 # Author: Geert Kloosterman <g.j.kloosterman@gmail.com>
  51 # Date: Sat Nov 19 22:33:18 2005
  52
  53 if [ -z "$1" ]; then
  54     echo "$0: Error: no arguments given!" 1>&2
  55     exit 1
  56 fi
  57
  58 # To test uncomment following line
  59 #echo $1 >> /tmp/remember.out
  60
  61 emacsclient --eval "(progn (bzg/org-annotation-helper \"$1\" ) nil)"
  62 #+end_src
  63
  64 * Installation
  65 *** Install org-annotation-helper.el
  66
  67     Install this script and require it in your .emacs (or wherever you
  68     want to do it)
  69
  70 #+begin_src emacs-lisp
  71 (require 'org-annotation-helper)
  72 #+end_src
  73
  74 *** Install the remember script
  75 ***** Save the handler as a script, and make sure it is executable, i.e. remember
  76 ***** Try it:
  77       1. Make sure emacs is running and you have started its server
  78          mode using (server-start) in .emacs or M-x server-start.
  79
  80       2. Run this command from the command line:
  81
  82 #+begin_src shell-script
  83 $ remember 'remember://http%3A//orgmode.org/::remember::Org-Mode%20Homepage::remember::Notes'
  84 #+end_src
  85
  86       3. Emacs should now show a remember window with a URL to remember.org
  87
  88 *** Add two bookmarklets
  89
  90     For firefox:
  91
  92     1. Right click on the bookmarks area of Firefox.
  93     2. Select new bookmark.
  94     3. In location fill the javascript code above (the bookmarklet)
  95     4. Make sure "Load this bookmark in the sidebar is deselected
  96
  97     Try it. You should have now a url that starts with "remember://"
  98      and your browser will not know what do to with it.
  99
 100 *** Add the handler for the "remember://" URI
 101
 102 ***** Firefox
 103
 104       To add a protocol handler (eg: remember://) in Firefox, take the
 105       following steps:
 106
 107       1. type in "about:config" in the location bar
 108       2. right click, select New --> String
 109          - the name should be "network.protocol-handler.app.remember"
 110          - the value should be the executable, eg. "org-annotation-helper".
 111
 112      At least under Linux this does not need to be the full path to
 113      the executable.
 114
 115      See http://kb.mozillazine.org/Register_protocol for more details.
 116
 117 ***** Opera
 118
 119       In Opera add the protocol in the Preferences->Advanced->Programs
 120       dialog.
 121
 122 *** Configure a template
 123
 124     I personally use the following template for this mode (all as one
 125     line):
 126
 127 #+begin_example
 128 ("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" )
 129 #+end_example
 130
 131    - =%c= :: will be replaced with the hyperlink to the page, displaying the title of the page
 132    - =%:link= :: will be replaced with the address of the page
 133    - =%i= :: will be replaced with the selected text from the browser
 134    - =%:region= :: will be replaced by the selected text from the web
 135                    page (special characters will be in hex-code.)
 136    - =%U= :: will be replaced by the current date
 137    - =%?= :: the cursor will be placed here (you may also replace this
 138              escape with =%&= to make it completely non-interactive.)
 139
 140    By default the new remember notes are placed in the bookmarks.org
 141    file under the "Web links" section, but it can be easily overriden
 142    with C-u C-c C-c
 143
 144 *** Step 5:
 145      Enjoy