Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
246 lines (174 sloc) 9.35 KB

org-mac-protocol manual

org-mac-protocol manual

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
  • Skim
  • BibDesk
  • Pages
  • Numbers
  • Keynote
  • iTunes
  • Finder
  • Terminal

The AppleScripts interface with 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.


A git repository can be found at git://


  • OS X 10.5 or above (untested on previous versions)
  • Org-Mode 6.28 or above (untested on previous versions)
  • 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:


[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)


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

and add org-mac-protocol to External packages

Start emacsserver


Create *Remember* templates

(setq org-remember-templates
      '((template 1)
        (template 2)
	(template n)))

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 "") "Remember")
("AppleScript note" ?z "* %?\n\n  Date: %u\n" (concat org-directory "") "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 org-remember `%’-escapes, the following are available:

:typeprotocol of link
:linklink URL
:descriptionlink title
:shortdesclink title, omitting originating application
:initialselected 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 org manual and the 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 compiled from bazaar and installed in /Applications. Aquamacs users will have to edit this variable.


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 Script menu in the menu bar, Quicksilver, FastScripts etc.

Currently supported applications

SafariLink: URLLink: URLsContent: current selection
FirefoxLink: URLContent: current clipboard [fn:2]
Google ChromeLink: URLContent: current clipboard [fn:2]
MailLink: messageContent: entire message
Address BookLink: personContent: no
SkimLink: pageContent: current selection
BibDeskLink: entryContent: Harvard style citation
PagesLink: page [fn:3]Content: current selection
NumbersLink: range [fn:4]Content: current selection
KeynoteLink: slideContent: slide title and body text
iTunesLink: trackContent: Title, Album, Composer, and Artist of track
FinderLink: fileContent: no
TerminalLink: Terminal.appContent: current window contents
  • Unsupported applications that are AppleScript aware will attempt to create links to the front document, but do not include selected content.
  • 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.


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


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


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


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


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


The pop up remember buffer is developed from a blog post by Jack Moffitt.

Alexander Poslavsky wrote Address Book support.

Antony Lander for Firefox Support.