* org-mac-protocol manual
#+TITLE: org-mac-protocol manual
#+AUTHOR: Christopher Suckling
#+EMAIL: suckling@gmail.com
#+OPTIONS: num:nil 
#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />
#+INFOJS_OPT: path:org-info.js
#+INFOJS_OPT: toc:nil localtoc:t view:info mouse:underline

  : Version: 0.634

  A suite of scripts that allow the user to annotate their org-mode
  buffers without switching focus from other OS X applications.

  The following applications are currently supported:

  + Safari
  + Mail
  + Address Book
  + [[http://skim-app.sourceforge.net/][Skim]]
  + [[http://bibdesk.sourceforge.net/][BibDesk]]
  + Pages
  + Numbers
  + Keynote
  + iTunes
  + Finder
  + Terminal

  The AppleScripts interface with [[http://orgmode.org/worg/org-contrib/org-protocol.php][org-protocol.el]] to extract content
  from, and link to, documents and applications.

  Four modes of interaction are provided:

  =org-link= creates an org-mode link and adds it to =*Org Links*= and
  the kill-ring.

  =org-link-tabs= creates org-mode links to all tabs in the front
  Safari window and adds them to =*Org Links*= and the kill-ring.

  =org-remember= pops up a small =*Remember*= frame with links and,
  where possible, extracted content embedded.

  =org-note= pops up a small =*Remember*= frame for note taking
  independent of the document being worked on.

** Obtaining

   A git repository can be found at =git://github.com/claviclaws/org-mac-protocol.git=

** Requirements

   - OS X 10.5 or above (untested on previous versions)

   - [[http://orgmode.org][Org-Mode]] 6.28 or above (untested on previous versions)
   - [[https://gna.org/p/remember-el][Remember]]

** Installation and configuration
*** Copy files to relevant directories 
      
      - =org-mac-protocol.el= should be copied to your Emacs
        load-path

      - The compiled AppleScripts[fn:1], =.scpt=, and the folder =/orgQSLib=
        should be copied to =~/Library/Scripts=

	The folder structure should be:

#+BEGIN_EXAMPLE
~/Library/Scripts/org-link.scpt
                  org-link-tabs.scpt
		  org-remember.scpt
		  org-note.scpt
		  orgQSLib/escape.rb
		           getEmacsClient.scpt
			   getItemMetadata.scpt
#+END_EXAMPLE
[fn:1] The repository contains two copies of all the
AppleScripts. Those with the suffix =.scpt= are compiled and ready for
installation, whilst those with the suffix =.applescript= are text
files for editing.

*** Edit your .emacs
**** Require org-mac-protocol.el

     : (require 'org-mac-protocol)

     or
     
     : M-x customize-variable <RET> org-modules <RET>

     and add =org-mac-protocol= to =External packages=

**** Start emacsserver

     : (server-start)

**** Create =*Remember*= templates

#+BEGIN_SRC emacs-lisp
(setq org-remember-templates
      '((template 1)
        (template 2)
	...
	(template n)))
#+END_SRC
     
     Two separate =*Remember*= templates are required, one for
     =org-remember= and one for =org-note=. Two examples:
    
     : ("AppleScript remember" ?y "* %:shortdesc\n  %:initial\n   Source: %u, %c\n\n  %?" (concat org-directory "inbox.org") "Remember")
     
     : ("AppleScript note" ?z "* %?\n\n  Date: %u\n" (concat org-directory "inbox.org") "Notes")
     
     These templates can be fairly flexible. The only essential items
     are =?y= and =?z= respectively (the template selection
     characters) and, for =org-remember=, =%c= (the org-link to the
     document), and =%:initial= (the selection within the document).

     In addition to the usual [[http://orgmode.org/manual/Remember-templates.html#Remember-templates][org-remember]] `%'-escapes, the following
     are available:

     | :type        | protocol of link                             |
     | :link        | link URL                                     |
     | :description | link title                                   |
     | :shortdesc   | link title, omitting originating application |
     | :initial     | selected content                             |

     If you choose to alter the template selection characters, you
     *must* alter =theProtocol= variable in =org-remember.scpt= and
     =org-note.scpt= to reflect your changes.

     Please see the [[http://orgmode.org/manual/Remember-templates.html#Remember-templates][org manual]] and the [[http://orgmode.org/worg/org-contrib/org-protocol.php][org-protocol.el manual]] for
     further details on template customisation.

**** Eval .emacs
*** Edit orgQSLib/getEmacsClient.scpt
    
    Set =theEmacsClient= to point to emacsclient for your flavour of
    Emacs.
      
    The default setting should work with Emacs.app compiled from
    bazaar and installed in =/Applications=. Aquamacs users will have
    to edit this variable.

** Usage
   There are four scripts that can be invoked; =org-link=,
   =org-link-tabs=, =org-note=, and =org-remember=. These scripts can
   be called by various methods, for example, the [[file://Applications/AppleScript/AppleScript%20Utility.app/][Script menu]] in the
   menu bar, [[http://code.google.com/p/blacktree-alchemy/][Quicksilver]], [[http://www.red-sweater.com/fastscripts/][FastScripts]] etc.

*** Currently supported applications

    |               | org-link           | org-link-tabs | org-remember                                         |
    |---------------+--------------------+---------------+------------------------------------------------------|
    | Safari        | Link: URL          | Link: URLs    | Content: current selection                           |
    | Firefox       | Link: URL          |               | Content: current *clipboard* [fn:2]                  |
    | Google Chrome | Link: URL          |               | Content: current *clipboard* [fn:2]                  |
    | Mail          | Link: message      |               | Content: entire message                              |
    | Address Book  | Link: person       |               | Content: no                                          |
    | Skim          | Link: page         |               | Content: current selection                           |
    | BibDesk       | Link: entry        |               | Content: Harvard style citation                      |
    | Pages         | Link: page [fn:3]  |               | Content: current selection                           |
    | Numbers       | Link: range [fn:4] |               | Content: current selection                           |
    | Keynote       | Link: slide        |               | Content: slide title and body text                   |
    | iTunes        | Link: track        |               | Content: Title, Album, Composer, and Artist of track |
    | Finder        | Link: file         |               | Content: no                                          |
    | Terminal      | Link: Terminal.app |               | Content: current window contents                     |


    - Unsupported applications that are AppleScript aware will attempt
      to create links to the front document, but do not include
      selected content.

    - Preview.app is /not/ AppleScript aware and Firefox has such
      limited AppleScript support as to be useless.

[fn:4] Firefox and Google Chrome have very limited AppleScript
support. Consequently is is necessary to *copy* any content you want
remembering to the clipboard.

[fn:3] Pages actually links to a character offset from the start of
the document. If the document is edited, then the link may degrade.

[fn:4] Numbers opens and selects the linked range, but it may be necessary to
change sheet manually.      
      
*** org-link
    Creates an org-mode link from the front document and passes it to
    emacsclient, adding it to =*Org Links*= and the kill-ring.

    - Call =org-link= from the required document

*** org-link-tabs
    Creates org-mode links from all tabs in the front Safari window and
    passes them to emacsclient, adding them to =*Org Links*= and the kill-ring.

    - Call =org-link-tabs= from anywhere

*** org-note
    Creates a note in an org-mode buffer. Does not link to the front
    document.

    - Call =org-note=
    - Enter note in pop-up =*Remember*= buffer
    - File note to return to previous application
      
*** org-remember
    Creates a note in an org-mode buffer. Links to the file of the
    front document and, where possible, uses selection in front
    document as initial content of the =*Remember*= buffer.

    - Call =org-remember= from the required document
    - Enter note in pop-up =*Remember*= buffer
    - File note to return to previous application
       

** Reference

*** Structure of links
    
    org-mac-protocol handles the following link structure:

    : org-protocol:/sub-protocol:/key/URI/description/short description/content:application name

    =org-protocol:/sub-protocol:/key/= is held by the variable
    =theProtocol= and set by =org-link=, =org-link-tabs=, =org-note=,
    or =org-remember=

    =application name= is held by the variable =theApp= and set by
    =org-link=, =org-link-tabs=, or =org-remember=

    =URI= is created by =getItemMetadata=

    =description= of the =URI= is created by =getItemMetadata=

    =short description= is a truncated version of =description=
    removing the =theApp= from the description

** Acknowledgements
   
   The pop up remember buffer is developed from a blog post by [[http://metajack.im/2008/12/30/gtd-capture-with-emacs-orgmode/][Jack Moffitt]].

   Alexander Poslavsky wrote Address Book support.

   Antony Lander for Firefox Support.