#+TITLE:     org-annotation-helper.el: using org-mode as a bookmark manager, a knowledge base, a research tool and more!
#+DESCRIPTION: The org-annotation-helper.el library was replaced by org-protocol and removed in Org-6.33.
#+OPTIONS:   ^:{} author:nil
#+STARTUP: odd

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

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.

#+BEGIN_WARNINGBOX
THIS DOCUMENT IS OBSOLETE.

It is superseded by [[https://orgmode.org/manual/Protocols.html][Org Protocol]].

~org-annotation-helper.el~ was removed in Org 6.33.
#+END_WARNINGBOX

* 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.

* Components

*** 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.

*** The bookmarklets

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

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

*** The handler

    #+begin_src shell-script
    #!/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)"
    #+end_src

* Installation

*** Install org-annotation-helper.el
    
    Install this script and require it in your .emacs (or wherever you
    want to do it).

    #+begin_src emacs-lisp
    (require 'org-annotation-helper)
    #+end_src

*** Install the remember script

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

***** Try it:

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

      2. Run this command from the command line:

	 #+begin_src shell-script
	 $ remember 'remember://http%3A//orgmode.org/::remember::Org-Mode%20Homepage::remember::Notes'
	 #+end_src

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

*** Add two bookmarklets

    For firefox:

    1. Right click on the bookmarks area of Firefox.
    2. Select new bookmark.
    3. In location fill the javascript code above (the bookmarklet)
    4. 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.

*** Add the handler for the "remember://" URI

***** Firefox

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

      1. type in "about:config" in the location bar
      2. 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.

***** Opera

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

*** Configure a template

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

    #+begin_example 
    ("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" )
    #+end_example

    - =%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

*** Step 5

    Enjoy!