contrib/lisp/org-annotation-helper.el

   1 ;;; org-annotation-helper.el --- start remember from a web browser
   2 ;;
   3 ;; Author: bzg AT altern DOT org
   4 ;; Author: dmg AT uvic   DOT org
   5 ;;
   6 ;; Keywords: org remember
   7 ;;
   8 ;; Version 0.3,  May 19, 2008
   9 ;;
  10 ;;; Commentary:
  11 ;;
  12 ;; [bzg:] This is an adapted version of the planner-mode extension the
  13 ;; was first posted by Geert Kloosterman <g.j.kloosterman@gmail.com> on
  14 ;; the Planner mailing list.
  15 ;;
  16 ;; [dmg:] I have updated and extended the function to allow for
  17 ;; handling of the selection (it is now available as a region, so it
  18 ;; can be used in a template using %i )
  19 ;;
  20 ;;
  21 ;; We want to be able to pass a URL and document title directly from a
  22 ;; web browser to Emacs.
  23 ;;
  24 ;; We define a remember:// url handler in the browser and use a shell
  25 ;; script to handle the protocol.  This script passes the information
  26 ;; to a running Emacs process (using emacsclient/gnuclient).  We use
  27 ;; bookmarklets to create the remember:// urls dynamicly.
  28 ;;
  29 ;; The protocol types currently recognized are:
  30 ;;
  31 ;; remember://     start `remember' with the url and title filled in
  32 ;; annotation://   similar to `planner-annotation-as-kill' (org?)
  33 ;;
  34 ;; The urls used internally will have the following form:
  35 ;;
  36 ;;   remember://<the web page url>::remember::<the title>::remember::<selection>
  37 ;;
  38 ;; The title will be url-hex-encoded.
  39 ;;
  40 ;; The bookmarklets:
  41 ;;
  42 ;;----------------------------------------------------------------------
  43 ;; javascript:location.href='remember://' + location.href + \
  44 ;;   '::remember::' + escape(document.title) + '::remember::' + escape(window.getSelection())
  45 ;;----------------------------------------------------------------------
  46 ;; javascript:location.href='annotation://' + location.href + '::remember::' +\
  47 ;;     escape(document.title) ;;
  48 ;;----------------------------------------------------------------------
  49 ;;
  50 ;; The handler
  51 ;;
  52 ;;----------------------------------------------------------------------
  53 ;; #!/bin/sh
  54 ;; # org-annotation-helper -- pass a remember-url to emacs
  55 ;; #
  56 ;; # Author: Geert Kloosterman <g.j.kloosterman@gmail.com>
  57 ;; # Date: Sat Nov 19 22:33:18 2005
  58 ;;
  59 ;; if [ -z "$1" ]; then
  60 ;;     echo "$0: Error: no arguments given!" 1>&2
  61 ;;     exit 1
  62 ;; fi
  63 ;;
  64 ;; # To test uncomment following line
  65 ;; #echo $1 >> /tmp/remember.out
  66 ;;
  67 ;; emacsclient --eval "(progn (bzg/org-annotation-helper \"$1\" ) nil)"
  68 ;;----------------------------------------------------------------------
  69 ;;
  70 ;;  To install:
  71 ;;
  72 ;; Step 0: Install this module
  73 ;;
  74 ;;  *  Install this script and require it in your .emacs (or wherever you
  75 ;;    want to do it)
  76 ;;
  77 ;;    (require 'org-annotation-helper)
  78 ;;
  79 ;;
  80 ;; Step 1: Install the remember script
  81 ;;
  82 ;;  * Save the handler as a script, and make sure it is executable, i.e.
  83 ;;     remember
  84 ;;  * Try it:
  85 ;;     Make sure emacs is running and you have started its server mode (server-start)
  86 ;;     Run this command from the command line
  87 ;;      remember 'remember://http%3A//orgmode.org/::remember::Org-Mode%20Homepage::remember::Notes'
  88 ;;     Emacs should now show a remember window with a URL to remember.org
  89 ;;
  90 ;;
  91 ;; Step 2: add two bookmarklets
  92 ;;
  93 ;; For firefox:
  94 ;;
  95 ;;  * Right click on the bookmarks area of Firefox.
  96 ;;  * Select new bookmark.
  97 ;;  * In location fill the javascript code above (the bookmarklet)
  98 ;;  * Make sure "Load this bookmark in the sidebar is deselected
  99 ;;
 100 ;;  Try it. You should have now a url that starts with "remember://"
 101 ;;  and your browser will not know what do to with it.
 102 ;;
 103 ;; Step 3: Add the handler for the "remember://" URI
 104 ;;
 105 ;; Firefox
 106 ;;
 107 ;; To add a protocol handler (eg: remember://) in Firefox, take the
 108 ;; following steps:
 109 ;;
 110 ;; - type in "about:config" in the location bar
 111 ;; - right click, select New --> String
 112 ;; - the name should be "network.protocol-handler.app.remember"
 113 ;; - the value should be the executable, eg. "org-annotation-helper".
 114 ;;   At least under Linux this does not need to be the full path to
 115 ;;   the executable.
 116 ;;
 117 ;; See http://kb.mozillazine.org/Register_protocol for more details.
 118 ;;
 119 ;; Opera
 120 ;;
 121 ;; In Opera add the protocol in the Preferences->Advanced->Programs
 122 ;; dialog.
 123 ;;
 124 ;;   Step 4: Configure a template
 125 ;;    I personally  use the following template for this mode
 126 ;;
 127 ;;         (?w "* %u %c \n\n%i" "~/working/trunk/org/bookmarks.org" "Web links")
 128 ;;
 129 ;;    %c will be replaced with the hyperlink to the page, displaying the title of the page
 130 ;;    %i will be replaced with the selected text from the browser
 131 ;;       By default the new remember notes are placed in the
 132 ;;    bookmarks.org file under the "Web links" section, but it can be
 133 ;;    easily overriden with C-u C-c C-c
 134 ;;
 135 ;; Step 5:
 136 ;;    Enjoy
 137
 138 (require 'url)
 139
 140 (autoload 'url-unhex-string "url")
 141
 142 (defun bzg/org-annotation-helper (info)
 143 (interactive)
 144   "Process an externally passed remember:// style url.
 145
 146 URLSTRING consists of a protocol part and a url and title,
 147 separated by ::remember::
 148
 149 The protocol types currently recognized are:
 150
 151 remember://     start `remember' with the url and title
 152 annotation://   similar to `org-annotation-as-kill'."
 153   (let ((remember-annotation-functions nil))
 154     ;; The `parse-url' functions break on the embedded url,
 155     ;; since our format is fixed we'll split the url ourselves.
 156     (if (string-match  "^\\([^:]*\\):\\(/*\\)\\(.*\\)" info)
 157       (let* ((b (get-buffer-create "*org-ann*"))
 158              (proto (match-string 1 info))
 159              (url_title_region (match-string 3 info))
 160              (splitparts (split-string url_title_region "::remember::"))
 161              (url (url-unhex-string (car splitparts)))
 162              (type (if (string-match "^\\([a-z]+\\):" url)
 163                        (match-string 1 url)))
 164              (title (cadr splitparts))
 165              (region (url-unhex-string (caddr splitparts)))
 166              orglink)
 167         (setq title (if (> (length title) 0) (url-unhex-string title)))
 168         (setq orglink (org-make-link-string url title))
 169         (org-store-link-props :type type
 170                               :link url
 171                               :region region
 172                               :description title)
 173         (setq org-stored-links
 174               (cons (list url title) org-stored-links))
 175         ;; FIXME can't access %a in the template -- how to set annotation?
 176         (raise-frame)
 177         (cond ((equal proto "remember")
 178                (kill-new orglink)
 179                (set-buffer b)
 180                (set-mark (point))
 181                (insert region)
 182                (org-remember nil ?w))
 183               ((equal proto "annotation")
 184                (message "Copied '%s' to the kill-ring." orglink)
 185                (kill-new orglink))
 186               (t (error "unrecognized org-helper protocol"))))
 187       (error "could not parse argument")))
 188 )
 189
 190
 191 (provide 'org-annotation-helper)