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