org-mac.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   5 #+TITLE:      Org and Mac OS X
   6 #+AUTHOR:     Worg people
   7 #+EMAIL:      bzg AT altern DOT org
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 # This file is the default header for new Org files in Worg.  Feel free
  13 # to tailor it to your needs.
  14
  15 [[file:index.org][{Back to Worg's index}]]
  16
  17 Assorted hacks to interact with org-mode whilst working in OS X
  18 applications other than Emacs...
  19
  20 * [[file:org-contrib/org-mac-iCal.org][org-mac-iCal]] -- import OS X iCal.app events into Emacs diary
  21   Written by /Christopher Suckling/.
  22
  23 * [[file:org-contrib/org-mac-message.org][org-mac-message]] -- linking to messages in OS X Mail.app
  24   Create links to selected or flagged messages in Mail.app.
  25   Written by /John Wiegley/ and /Christopher Suckling/.
  26
  27 * org-mac-protocol -- interact with [[file:org-contrib/org-protocol.org][org-protocol]] from OS X applications
  28   Written by /Christopher Suckling/.
  29
  30   : Version: 0.628
  31
  32   A suite of scripts that allow the user to annotate their org-mode
  33   buffers without switching focus from other OS X applications
  34   to Emacs.
  35
  36   The AppleScripts interface with org-protocol.el to extract content
  37   from, and link to, documents and applications.
  38
  39   Three modes of interaction are provided:
  40
  41   =org-link= creates an org-mode link and adds it to =*Org Links*= and
  42   the kill-ring.
  43
  44   =org-remember= pops up a small =*Remember*= frame with links and,
  45   where possible, extracted content embedded.
  46
  47   =org-note= pops up a small =*Remember*= frame for note taking
  48   independent of the document being worked on.
  49
  50 ** Obtaining
  51    A disk image can be downloaded [[http://claviclaws.net/org/org-mac-protocol.dmg][here]].
  52
  53    A git repository can be found at =git://github.com/claviclaws/org-mac-protocol.git=
  54
  55    The git repository does not contain the [[http://homepage.mac.com/tkurita/scriptfactory/Softwares/OSAX/URIEscape/manual/en/index.html][URI Escape]] scripting addition.
  56
  57 ** Included files
  58
  59    - org-mac-protocol.pkg (installer package)
  60    - sources (including Scripting Additions sources)
  61    - org-mac-protocol.org (this manual)
  62
  63 ** Requirements
  64
  65    - OS X 10.5 (untested on previous versions)
  66
  67    - [[http://orgmode.org][Org-Mode]] 6.28 or above (untested on previous versions)
  68    - [[https://gna.org/p/remember-el][Remember]]
  69
  70 ** Installation and configuration
  71 *** Install files
  72 **** =org-mac-protocol.pkg= - OS X 10.5 only
  73
  74     - Launch the installer and follow on screen instructions.  You
  75       must set a location for org-mac-protocol.el that is on your
  76       Emacs load-path.
  77
  78 **** Manual installation - OS X 10.4
  79
  80     - Copy files from the =sources= directory to their relevant
  81       locations.
  82
  83       =org-mac-protocol.el= should be placed on your Emacs load-path.
  84
  85       The contents of the =Scripts= directory should be placed in
  86       =~/Library/Scripts/=.
  87
  88       =URI Escape.osax= should be placed in
  89       =~/Library/ScriptingAdditions/=, creating the directory if
  90       necessary. =URI Escape.osax= is found on the
  91       =URIEscape1.1.2.dmg= disk image.
  92
  93 *** Edit your .emacs
  94 **** Require org-mac-protocol.el
  95
  96      : (require 'org-mac-protocol)
  97
  98      or
  99
 100      : (add-to-list 'org-modules 'org-mac-protocol)
 101
 102      Note that =org-modules= must be set before org-mode is loaded.
 103
 104 **** Start emacsserver
 105
 106      : (server-start)
 107
 108 **** Create =*Remember*= templates
 109
 110      Two separate =*Remember*= templates are required, one for
 111      =org-remember= and one for =org-note=:
 112
 113      : ("AppleScript remember" ?y "* %?\n\n  Source: %u, %c\n\n  %i" (concat org-directory "inbox.org") "Remember")
 114
 115      : ("AppleScript note" ?z "* %?\n\n  Date: %u\n" (concat org-directory "inbox.org") "Notes")
 116
 117      These templates can be fairly flexible. The only essential items
 118      are =?y= and =?z= respectively (the template selection
 119      characters), and, for =org-remember=, =%c= (the link to the
 120      document), and =%i= (the selection within the document).
 121
 122      If you choose to alter the template selection characters, you
 123      *must* alter =theProtocol= variable in =org-remember.scpt= and
 124      =org-note.scpt= to reflect your changes.
 125
 126      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
 127      further details on template customisation.
 128
 129 **** Eval .emacs
 130 *** Edit orgQSLib/getEmacsClient.scpt
 131
 132     - Set =theEmacsClient= to point to emacsclient for your flavour of Emacs.
 133
 134       The default setting should work with CVS Emacs and Carbon Emacs.
 135       Aquamacs users will have to edit this variable.
 136
 137 ** Usage
 138    There are three scripts that can be invoked; =org-link=,
 139    =org-note=, and =org-remember=. These scripts can be called by
 140    various methods, for example, the [[file://Applications/AppleScript/AppleScript%20Utility.app/][Script menu]] in the menu bar,
 141    [[http://code.google.com/p/blacktree-alchemy/][Quicksilver]], [[http://www.red-sweater.com/fastscripts/][FastScripts]] etc.
 142
 143 *** Currently supported applications
 144
 145     |          | org-link           | org-note | org-remember                     |
 146     |----------+--------------------+----------+----------------------------------|
 147     | Finder   | Link: file         | Yes      | Content: no                      |
 148     | Safari   | Link: URL          | Yes      | Content: current selection       |
 149     | Mail     | Link: message      | Yes      | Content: entire message          |
 150     | Skim     | Link: PDF          | Yes      | Content: current selection       |
 151     | BibDesk  | Link: entry        | Yes      | Content: Harvard style citation  |
 152     | Terminal | Link: Terminal.app | Yes      | Content: current window contents |
 153
 154
 155     - Unsupported applications that are AppleScript aware will attempt
 156       to create links to the front document, but do not support
 157       selected content.
 158
 159     - Preview.app is /not/ AppleScript aware and Firefox has such
 160       limited AppleScript support as to be useless.
 161
 162 *** org-link
 163     Creates an org-mode link from the front document and passes it to
 164     emacsclient, adding it to =*Org Links*= and the kill-ring.
 165
 166     - Run =org-link=
 167
 168 *** org-note
 169     Creates a note in an org-mode buffer. Does not link to the front
 170     document.
 171
 172     - Run =org-note=
 173     - Enter note in pop-up =*Remember*= buffer
 174     - File note to return to previous application
 175
 176 *** org-remember
 177     Creates a note in an org-mode buffer. Links to the file of the
 178     front document, and uses selection in front document as
 179     initial content of the =*Remember*= buffer.
 180
 181     - Run =org-remember=
 182     - Enter note in pop-up =*Remember*= buffer
 183     - File note to return to previous application
 184
 185 ** TODO
 186    Support for further applications will also require defining [[http://orgmode.org/manual/Adding-hyperlink-types.html#Adding-hyperlink-types][new
 187    org-mode hyperlinks]], as will improvements to linking for PDF files
 188    and Terminal. Planned support includes:
 189
 190    - [ ] Skim (improved)
 191    - [ ] Terminal (improved)
 192    - [ ] iCal
 193    - [ ] Microsoft Office
 194    - [ ] iTunes
 195    - [ ] iPhoto
 196    - [ ] Firefox (if AppleScript support is improved)
 197
 198 ** Acknowledgements
 199
 200    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]].
 201
 202    [[http://homepage.mac.com/tkurita/scriptfactory/Softwares/OSAX/URIEscape/manual/en/index.html][URI Escape]] is by Tetsuro Kurita.
 203
 204    org-info.js and CSS stylesheet by [[http://orgmode.org/worg/code/org-info-js/][Sebastian Rose]]
 205