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