From 5141b91f24361e11f87367104916fc1a3edafbaa Mon Sep 17 00:00:00 2001 From: Charles Choi Date: Mon, 16 Jun 2025 13:37:11 -0700 Subject: [PATCH] org-protocol.org: Rewrite for 2025 Update org-protocol.org to be up to date with GNU Emacs 30.1 and Org 9.7.30. * org-contrib/org-protocol.org (HEAD) Revised TITLE to directly describe Org protocol. (HEAD) JavaScript modified only support testing `store-link' protocol. Removed support `remember` protocol as it is obsolete. Removed `capture' protocol as it requires a priori configuration of `org-capture-templates` for it to work. (* About org-protocol.el) Moved to new (* History of Org protocol) section. (* Installation) This section is rewritten. (* Browser / system setup) This section has been rewritten with its sub-sections migrated and annotated. (* Using org-protocol) This section has rewritten. (* Links and bookmarks) This section have been moved to the new (* History of Org protocol) and modified. (* Note taking and citations: =org-protocol-capture=) This section has been moved to the new (* History of Org protocol) and modified. (* Edit published content: =org-protocol-open-source=) This section has been moved to the new (* History of Org protocol) and modified. (* Other browsers) Obsolete. (* Keybindings for Firefox) Obsolete. (* Screencast: small introduction to org-protocol.el) This section has been moved to the new (* History of Org protocol) and modified. * images/org-protocol/org-protocol-architecture.svg Added SVG image describing architecture of Org protocol. --- .../org-protocol-architecture.svg | 49 ++ org-contrib/org-protocol.org | 762 +++++++++--------- 2 files changed, 408 insertions(+), 403 deletions(-) create mode 100644 images/org-protocol/org-protocol-architecture.svg diff --git a/images/org-protocol/org-protocol-architecture.svg b/images/org-protocol/org-protocol-architecture.svg new file mode 100644 index 00000000..277cb55a --- /dev/null +++ b/images/org-protocol/org-protocol-architecture.svg @@ -0,0 +1,49 @@ + + + + + + +Org Protocol Architecture + + + +a + +External App + + + +b + +Scheme Handler +(OS-specific) + + + +a->b + + +org-protocol:// +request + + + +c + +Emacs +(server) + + + +b->c + + +socket +request + + + diff --git a/org-contrib/org-protocol.org b/org-contrib/org-protocol.org index 08d191b4..c01ac680 100644 --- a/org-contrib/org-protocol.org +++ b/org-contrib/org-protocol.org @@ -1,25 +1,16 @@ -#+TITLE: org-protocol.el -- Intercept calls from emacsclient to trigger custom actions +#+TITLE: org-protocol.el -- Trigger custom actions in Emacs via a custom URL scheme #+OPTIONS: H:3 num:nil toc:t \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc author:nil #+STARTUP: odd #+SETUPFILE: ../macros.setupfile #+HTML_HEAD_EXTRA: +# #+HTML_HEAD: #+HTML_LINK_UP: index.html #+HTML_LINK_HOME: https://orgmode.org/worg/ @@ -27,367 +18,317 @@ # Free Documentation license v1.3 or later, code examples are released # under the GNU General Public License v3 or later. -org-protocol intercepts calls from emacsclient to trigger custom actions without -external dependencies. Only one protocol has to be configured with your external -applications or the operating system, to trigger an arbitrary number of custom -actions. Just register your custom sub-protocol and handler with the variable -`org-protocol-protocol-alist'. +* Org protocol -* About org-protocol.el +Org protocol [[https://orgmode.org/manual/Protocols.html][(info "(org) Protocols")]] is a custom URL scheme (~org-protocol://~) used to trigger custom actions in Emacs. A common use case for Org protocol is data import (for example a web clipper), where an external application can send data to Emacs by making an Org protocol URL request. - =org-protocol.el= is based on code and ideas from - [[file:./org-annotation-helper.org][org-annotation-helper.el]] and =org-browser-url.el=. +The form of an Org protocol URL is - "=org-protocol:/sub-protocol:/=" triggers actions associated with =sub-protocol= - through the custom variable =org-protocol-protocol-alist=. +: org-protocol://PROTOCOL?key1=val1&key2=val2… - It comes with four predefined handlers: - - =org-protocol-store-link= :: - triggered through the sub-protocol "=store-link=". Stores an Org-link and - pushes the URL to the =kill-ring=. - - =org-protocol-capture= :: - Fill a =CAPTURE= buffer with information gathered somewhere else. This - handler is triggered through the "=capture=" sub-protocol and uses the - function =org-capture=. - - =org-protocol-remember= :: - Fills a remember buffer with information gathered somewhere else. This - handler is triggered through the "=remember=" sub-protocol and still - available for backward compatibility. This handler uses =org-remember=. Use - the current =org-protocol-capture=. +where ~keyN=valN~ is a ( +key, value) pair specific to the ~PROTOCOL~ used. The value must be [[https://en.wikipedia.org/wiki/Percent-encoding][percent encoded]]. - - =org-protocol-open-source= :: - "=open-source=". Maps URLs to local filenames. Use this to open sources of - already published contents in emacs for editing. +The scheme specific part of Org protocol (example ~org-protocol://{scheme specific part}~) largely conforms to the [[https://datatracker.ietf.org/doc/html/rfc1738#section-3.1][common internet scheme syntax]] of RFC 1738 and [[https://datatracker.ietf.org/doc/html/rfc3986#section-3.4][query component]] specification of RFC 3986. - =org-protocol= helps creating custom handlers [[file:../org-tutorials/org-protocol-custom-handler.org][(tutorial)]] and so called - =org-protocol-projects=. +There are three predefined protocols provided by Org protocol: - #+begin_infobox - @As of Org mode release 7.01 =org-protocol-remember= is now by =org-protocol-capture=.@ - If not stated otherwise, you may simply replace each occurrence of - /capture/ with /remember/ throughout this document, if you still want to use - remember templates. Use =M-x org-version= to find out about the version you're - using. - #+end_infobox +- ~store-link~ :: Store a link, push URL to kill-ring. +- ~capture~ :: Capture a note and let the user view it in a buffer before storing it. +- ~open-source~ :: Open local source files of published contents for editing. -* Installation +Motivated users can define their [[file:~/Projects/vendor/worg/org-tutorials/org-protocol-custom-handler.org][own custom protocol]] (Note: this links to a 4 year old document, it is likely outdated.) using the variable ~org-protocol-protocol-alist~. - - To load org-protocol.el add the following to your =.emacs=: +The diagram below illustrates how an Org Protocol request is handled. - : (server-start) - : (add-to-list 'load-path "~/path/to/org/protocol/") - : (require 'org-protocol) +#+BEGIN_SRC dot :file ../images/org-protocol/org-protocol-architecture.svg :cmdline -Tsvg :exports none :results raw +digraph "Org Protocol Architecture" { + rankdir=LR; + node [shape="rect", color="black", style="filled", fillcolor="white", fontcolor="black", fontsize=12, fontname="Helvetica"]; + edge [fontname="Helvetica", fontsize=10]; + + a[label="External App"]; + b[label="Scheme Handler\n(OS-specific)"]; + c[label="Emacs\n(server)"] -* Browser / system setup + a -> b [label="org-protocol://\nrequest"]; + b -> c [label="socket\nrequest"]; +} +#+END_SRC - - [[GNU/Linux setup]] - - [[Windows setup]] - - [[Mac OS X setup]] - - [[*Applications][Applications]] - - [[*Verify the installation][Verify the installation]] +[[file:../images/org-protocol/org-protocol-architecture.svg]] -*** GNU/Linux setup - Most common desktop environments (Gnome, KDE et al) comply with the [[https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html][XDG Desktop Entry Specification]]. - This means setting up =emacsclient= as the =org-protocol= handler using a .desktop file can be regarded - as a, in most cases, standard way to set this up in most common desktop environments. +The scheme handler for GNU/Linux and Windows is typically *emacsclient*. On recent versions of macOS (since Ventura), security policy prevents external applications from calling programs like *emacsclient* outside of their sandbox. An alternate, commercial offering ([[http://yummymelon.com/scrim][Scrim]]) is available to serve as a macOS-trusted scheme handler for Org Protocol requests[fn:scrim-captee-disclaimer]. Users running a version of macOS older than Ventura can still use *emacsclient* as a scheme handler for Org Protocol. - Some environments, e.g. Gnome as of Gnome 3, have deprecated other configuration methods, - e.g. =gconftool-2= to set-up protocol handling. +* Version Compliance +Guidance on this page is up to date with GNU Emacs 30.1 and Org 9.7.30. Sections where there is uncertainty on this are marked as such. - Create an =org-protocol.desktop= file either in =~/.local/share/applications/= to set-up =emacsclient= as the - =org-protocol= handler for the current user or in =/usr/share/applications= to set-up a system-wide - configuration: +* Installation and Configuration - #+begin_example - [Desktop Entry] - Name=org-protocol - Comment=Intercept calls from emacsclient to trigger custom actions - Categories=Other; - Keywords=org-protocol; - Icon=emacs - Type=Application - Exec=emacsclient -- %u - Terminal=false - StartupWMClass=Emacs - MimeType=x-scheme-handler/org-protocol; - #+end_example +Take the following steps to get Org protocol working for you. - Update the cache database of MIME types handled by desktop files via: +1. Setup Emacs server. +2. Setup the Org protocol scheme handler. +3. Setup Org protocol capture. +4. Construct an Org protocol URL request. - : update-desktop-database ~/.local/share/applications/ +Steps 1, 2, and 4 are platform-specific so this section will be largely organized by platform, with a common section for Org protocol capture as that is platform-independent. -*** Windows setup +*** GNU/Linux, BSD, and Unix variants +***** Setup Emacs server +Add the following lines to the Emacs initialization file (~init.el~, ~$HOME/.emacs~) to start Emacs server. - Windows users may register the "=org-protocol=" once for all by adjusting the - following to their facts, save it as *.reg file and double-click it. This - worked for me on Windows-XP Professional and the emasc23 from ourcomments.org - ([[http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl]]). I'm no Windows user - though and enhancements are more than welcome on the org-mode mailinglist. The - original file is from http://kb.mozillazine.org/Register_protocol. +: (server-start) +: (require 'org-protocol) - #+begin_example - REGEDIT4 +Either evaluate the above or restart Emacs to start the server. - [HKEY_CLASSES_ROOT\org-protocol] - @="URL:Org Protocol" - "URL Protocol"="" - [HKEY_CLASSES_ROOT\org-protocol\shell] - [HKEY_CLASSES_ROOT\org-protocol\shell\open] - [HKEY_CLASSES_ROOT\org-protocol\shell\open\command] - @="\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\"" - #+end_example +To test that Org protocol is setup and running, click on the link below to store an Org link to this page. -*** Mac OS X setup - - Follow the directions for installing EmacsClient.app from https://github.com/neil-smithline-elisp/EmacsClient.app. This should configure the org-protocol for all Mac OS X browsers. - - After installing EmacsClient.app you should then [[Verify the installation]]. Once verified, you can begin [[Using org-protocol]]. - - If that doesn't work, you might check https://github.com/xuchunyang/setup-org-protocol-on-mac for building a custom handler, combined with the per-browser config information below. - -*** Applications - -***** Firefox - If you are using Firefox on Mac OS X, see [[Mac OS X setup]]. - - - Please refer to http://kb.mozillazine.org/Register_protocol and use - "org-protocol" as protocol. - -***** Acrobat Reader - :PROPERTIES: - :CUSTOM_ID: acrobat-reader-setup - :END: - - Adapted from [[https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org]] - - You place a javascript file for each menu entry in - =~/.adobe/Acrobat//JavaScripts= on unix-like systems or - =c:/Program Files/Adobe/Acrobat /Reader/Javascripts/= on - Windows, or wherever your Adobe Reader Installation might look for - javascript. - - The examples given here will place new menu entries in the "Tools" - menu, after restarting Adobe Reader. - -******* org-store-link.js - : // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org - : app.addMenuItem({cName:"org-store-link", cParent:"Tools", - : cExec:"app.launchURL('org-protocol://store-link://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title));"}); - -******* org-capture.js - : // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org - : app.addMenuItem({cName:"org-capture", cParent:"Tools", - : cExec:"app.launchURL('org-protocol://capture://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"}); - - And this one, if you still use remember templates: - -******* org-remember.js - : // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org - : app.addMenuItem({cName:"org-remember", cParent:"Tools", - : cExec:"app.launchURL('org-protocol://remember://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"}); - -***** Opera - - If you are using Opera on Mac OS X, see [[Mac OS X setup]]. - - Opera setup is described here: - http://www.opera.com/support/kb/view/535/. - - To set up opera for use with org-protocol, follow these steps: - - 1. Choose "/Tools/" -> "/Prefences/" from the menu. - 2. Select the tab "/Advanced/". - 3. Choose "/Programs/" from the list on the left. - 4. Now click the button "/Add/" on the very right. - 5. In the new dialog window, enter "=org-protocol=" as "/Protocol/", choose the - radio button "/Open with other application/" and enter the path to - emacsclient. - -***** Safari - Safari is only supported on Mac systems, not iOS systems. - - See [[Mac OS X setup]] for directions. - -*** Verify the installation - - After your protocol is registered with your browser/OS, these links here - should work. Click on them and see if emacs reacts: - - #+begin_export html +#+begin_export html - #+end_export +#+end_export -* Using org-protocol +In an Org buffer, use the binding ~C-c M-l~ (~org-insert-last-stored-link~) to paste the recently stored Org link. - To actually use org-protocol add a bookmark to Firefox or Opera. +***** Setup the Org protocol scheme handler - Here is the URL to use as "/Location/" for browser bookmarks. Just remove the - line breaks and replace "=sub-protocol=" with the real sub-protocol to use: +On GNU/Linux, Emacs 30.1+ configures ~emacsclient.desktop~ to handle Org Protocol URL requests. If your GUI window environment can use this file, no further setup is required. (NOTE: This is not true for some distributions of xdg-tools as reported in the bug [[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74467][#74467 - 31.0.50; org-protocol emacsclient.desktop change is not fully functional - GNU bug report logs]].) - : javascript:location.href='org-protocol://sub-protocol://'+ - : encodeURIComponent(location.href)+'/'+ - : encodeURIComponent(document.title)+'/'+ - : encodeURIComponent(window.getSelection()) - This URL may be used for all three standard handlers in =org-protocol.el=. Some - of the values will be ignored (e.g. =store-link:/= will use the URL and title - only). +#+begin_warningbox -* Links and bookmarks: =org-protocol-store-link= +NOTE: This section may be stale. - =org-store-link= stores an Org-link insertable through =M-x org-insert-link= and - pushes the URL found onto the =kill-ring= for yanking (=C-y=). The sub-protocol - used is "=store-link=": +Users with an older (< 30) version of Emacs can use this guidance. - : emacsclient org-protocol:/store-link:/URL/TITLE +Most common desktop environments (Gnome, KDE et al) comply with the [[https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html][XDG Desktop Entry Specification]]. This means setting up =emacsclient= as the =org-protocol= handler using a .desktop file can be regarded as a standard way to set this up in most common desktop environments. - will store this Org-link: +Some environments, e.g. Gnome as of Gnome 3, have deprecated other configuration methods, e.g. =gconftool-2= to set-up protocol handling. - #+begin_example - [[URL][TITLE]] - #+end_example +Create an =org-protocol.desktop= file either in =~/.local/share/applications/= to set-up =emacsclient= as the =org-protocol= handler for the current user or in =/usr/share/applications= to set-up a system-wide configuration: - In addition, =URL= will be pushed on the =kill-ring= for yanking ('=C-y='). You will - have to encode =URL= and/or =TITLE= if they contain slashes, and probably quote - those for the shell. +#+begin_example + [Desktop Entry] + Name=org-protocol + Comment=Intercept calls from emacsclient to trigger custom actions + Categories=Other; + Keywords=org-protocol; + Icon=emacs + Type=Application + Exec=emacsclient -- %u + Terminal=false + StartupWMClass=Emacs + MimeType=x-scheme-handler/org-protocol; +#+end_example - To use this feature, add a bookmark with an arbitrary name (e.g. - "/Org: store-link/") and enter this as "=Location=": +Update the cache database of MIME types handled by desktop files via: - : javascript:location.href='org-protocol://store-link://'+encodeURIComponent(location.href) +: update-desktop-database ~/.local/share/applications/ -* Note taking and citations: =org-protocol-capture= +#+end_warningbox - This one is triggered through the sub-protocol "=capture=" and consumes up to - three data fields: +***** Setup Org protocol capture +See [[#1401e4ba-85e1-4860-bd64-d6e97ecf1fa1][Setup Org protocol capture]] in the common section. - : emacsclient org-protocol:/capture:/URL/TITLE/BODY +***** Construct Org protocol URL Request - will pop up an /*Capture*/ buffer and fill the template with the data - submitted. +Numerous approaches can be used to generate an Org protocol request: - To use this feature, add a bookmark with an arbitrary name (e.g. - "/Org: capture/") and enter this as "=Location=": +- As a [[#b74d3e67-918c-4e68-934b-532dc9f8654d][web browser bookmark]] that can invoke JavaScript +- Via program/script generation (Bash, Python, Java, Go, Rust, C, etc.) - : javascript:location.href='org-protocol://capture://'+ - : encodeURIComponent(location.href)+'/'+ - : encodeURIComponent(document.title)+'/'+ - : encodeURIComponent(window.getSelection()) +Once the URL request has been constructed, it can be sent to Emacs via the scheme handler which will invoke *emacsclient*. - The result depends on the template used. See [[*An example capture template][An example capture template]] further down. +----- - Note, that this one, as opposed to the other two standard handlers, does not - mix with more parameters to emacsclient. All parameters but the - #'=org-protocol://org-capture://...=' one will be discarded. +*** macOS +***** Setup Emacs Server -*** Which capture template is used? - :PROPERTIES: - :ID: org:f56bcb9a-20e7-4b37-99f1-839a8821cc4b - :END: +Recent versions of macOS (since Ventura) disallow the use of a local domain socket for inter-process communication between apps with separate sandboxes. Users using [[http://yummymelon.com/scrim][Scrim]] can instead setup a TCP socket [fn:scrim-captee-disclaimer]. Add the following lines to the Emacs initialization file (~init.el~, ~$HOME/.emacs~) to start Emacs server. - You don't need to setup a capture template to use - =org-protocol-capture=, since Org-mode provides a default template - for those cases. Newer versions provide an interactive interface - for choosing a template. You may provide a template to be used by - customizing the variable =org-capture-default-template= [fn:1]. +: (setopt server-use-tcp t) +: (server-start) +: (require 'org-protocol) - The problem with this solution would be, that only one template - can be used with the fuction. Luckily, =org-protocol-capture= - understands a slightly extended syntax to choose between several - templates: If the first field of the data submitted is exactly one - character in length, this character will be used to select the - template. +To test that Org protocol is setup and running, click on the link below to store an Org link to this page. - Here we choose to use the "=x=" template: +#+begin_export html + +#+end_export - : emacsclient org-protocol:/capture:/x/URL/TITLE/BODY +In an Org buffer, use the binding ~C-c M-l~ (~org-insert-last-stored-link~) to paste the recently stored Org link. - And, again, as bookmark location: - : javascript:location.href='org-protocol://capture://x/'+ - : encodeURIComponent(location.href)+'/'+ - : encodeURIComponent(document.title)+'/'+ - : encodeURIComponent(window.getSelection()) +***** Setup the Org protocol scheme handler -***** An example capture template +If [[http://yummymelon.com/scrim][Scrim]] is installed, no further setup is required as Scrim will automatically handle Org protocol URL requests [fn:scrim-captee-disclaimer]. - #+begin_src emacs-lisp - (setq org-capture-templates - (quote - (("w" - "Default template" - entry - (file+headline "~/org/capture.org" "Notes") - "* %^{Title}\n\n Source: %u, %c\n\n %i" - :empty-lines 1) - ;; ... more templates here ... - ))) - #+end_src +Users of the [[https://bitbucket.org/mituharu/emacs-mac/src/master/][Mitsuharu Yamamoto fork of Emacs]] also do not need to setup an Org protocol scheme handler as this fork will natively handle Org protocol URL requests. - - "=w=" :: makes this one the default template used for - "=org-protocol://capture://=" URLs. - - =entry= :: makes it a regular entry with a headline. - - =file+headline= :: files the note in file "=~/org/capture.org=" as child of - the headline "=Notes=" - - '=%c=' :: will be replaced by an Org-link pointing to the location of the - page you have been visiting when clicking on the link. The page - title will be the link's description. - - '=%i=' :: will be replaced by the selected text in your browser window if - any. +#+begin_warningbox - In addition, you may use the following placeholders in your template: +If you are using an old version of macOS (nee Mac OS X) older than Ventura, this guidance may still be valid. If you are using macOS Ventura or newer, *none* of this guidance is valid. - | Placeholders | Replacement | - |---------------+---------------------------| - | =%:link= | URL of the web-page | - | =%:description= | The title of the web-page | - | =%:initial= | Selected text. | +Follow the directions for installing EmacsClient.app from https://github.com/neil-smithline-elisp/EmacsClient.app. This should configure the org-protocol for all Mac OS X browsers. - You may read more about templates and their special escape characters in the - [[https://orgmode.org/manual/Capture-templates.html#Capture-templates][Org-mode manual]]. +After installing EmacsClient.app you should then verify the installation. Once verified, you can begin using org-protocol. -*** Org-protocol-remember +If that doesn't work, you might check https://github.com/xuchunyang/setup-org-protocol-on-mac for building a custom handler, combined with the per-browser config information below. - The =org-protocol-remember= handler is now obsolete. However, the handler is - still available for backward compatibility. To use this handler, closely - follow the setup for the current =org-protocol-capture= handler, and simply - replace each occurrence of /capture/ with /remember/. +#+end_warningbox - As remember templates look slightly different than capture templates, we - provide an example here. +***** Setup Org protocol capture -***** An example remember template +See [[#1401e4ba-85e1-4860-bd64-d6e97ecf1fa1][Setup Org protocol capture]] in the common section. - #+begin_src emacs-lisp -(setq org-remember-templates - '((?w "* %^{Title}\n\n Source: %u, %c\n\n %i" nil "Notes"))) - #+end_src +***** Setup Org protocol URL request - - '=?w=' :: makes this one the default template used for - "=org-protocol://remember://=" URLs. - - '=%c=' :: will be replaced by an Org-link pointing to the location of the - page you have been visiting when clicking on the link. The page - title will be the link's description. - - '=%i=' :: will be replaced by the selected text in your browser window if - any. +Numerous approaches can be used to generate an Org protocol request: - In addition, you may use the following placeholders in your template: +- As a [[#b74d3e67-918c-4e68-934b-532dc9f8654d][web browser bookmark]] that can invoke JavaScript +- Via program/script generation (Bash, Python, Java, Go, Rust, C, etc.) +- [[http://yummymelon.com/captee][Captee]] is a commerical app that can construct an Org protocol URL request from the native macOS Share Menu [fn:scrim-captee-disclaimer]. - | Placeholders | Replacement | - |---------------+---------------------------| - | =%:link= | URL of the web-page | - | =%:description= | The title of the web-page | - | =%:initial= | Selected text. | +Once the URL request has been constructed, it can be sent to Emacs via the scheme handler. - You may read more about templates and their special escape characters in the - [[https://orgmode.org/manual/Capture-templates.html#Capture-templates][Org-mode manual]]. +----- -* Edit published content: =org-protocol-open-source= +*** Windows +***** Setup Emacs Server + +Native Windows has no support for a local domain socket so a TCP socket is used instead. Add the following lines to the Emacs initialization file (~init.el~, ~$HOME/.emacs~) to start Emacs server. + +: (setopt server-use-tcp t) +: (server-start) +: (require 'org-protocol) + +***** Setup the Org protocol scheme handler + +#+begin_warningbox +This section has not been updated since Windows XP and may not be valid. Updated guidance is wanted. +#+end_warningbox + +Windows users may register the "=org-protocol=" once for all by adjusting the following to their facts, save it as *.reg file and double-click it. This worked for me on Windows-XP Professional and the emasc23 from ourcomments.org ([[http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl]]). I'm no Windows user though and enhancements are more than welcome on the org-mode mailinglist. The original file is from http://kb.mozillazine.org/Register_protocol. +#+begin_example +REGEDIT4 + +[HKEY_CLASSES_ROOT\org-protocol] +@="URL:Org Protocol" +"URL Protocol"="" +[HKEY_CLASSES_ROOT\org-protocol\shell] +[HKEY_CLASSES_ROOT\org-protocol\shell\open] +[HKEY_CLASSES_ROOT\org-protocol\shell\open\command] +@="\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\"" +#+end_example + + +***** Setup Org protocol capture + +See [[#1401e4ba-85e1-4860-bd64-d6e97ecf1fa1][Setup Org protocol capture]] in the common section. + +***** Setup Org protocol URL request + +Numerous approaches can be used to generate an Org protocol request: + +- As a [[#b74d3e67-918c-4e68-934b-532dc9f8654d][web browser bookmark]] that can invoke JavaScript +- Via program/script generation (Bash, Python, Java, Go, Rust, C#, etc.) + +Once the URL request has been constructed, it can be sent to Emacs via the scheme handler which will invoke *emacsclient*. + +----- +*** Common +***** Setup Org protocol capture +:PROPERTIES: +:CUSTOM_ID: 1401e4ba-85e1-4860-bd64-d6e97ecf1fa1 +:END: + +#+begin_infobox +Knowledge of Org capture [[https://orgmode.org/manual/Capture.html][(info "(org) Capture")]] is recommended beforehand to understand how Org protocol extends it. +#+end_infobox + +Org protocol capture [[https://orgmode.org/manual/The-capture-protocol.html][(info "(org) The capture protocol")]] extends Org capture [[https://orgmode.org/manual/Capture.html][(info "(org) Capture")]] to support data import from external apps into Emacs. Different data types are supported for import: + +- url :: a URL (typically of a web page) +- title :: the title of the web page +- selected text :: selected text within the web page + +The form of an Org protocol URL request with the ~capture~ protocol looks like this: + +: org-protocol://capture?template=TEMPLATE&url=URL&title=TITLE&body=BODY + +In table form the following keys for the ~capture~ protocol are described as follows: + +| Key | Description | Template Placeholder | Notes | +| | | | <20> | +|----------+--------------+----------------------+------------------------------------------------------------------------------------------------------------| +| ~template~ | Template key | | Capture template key in ~org-capture-templates~. If omitted, then ~org-protocol-default-template-key~ is used. | +| ~url~ | URL | ~%:link~ | Typically the web page URL to capture. | +| ~title~ | Title | ~%:description~ | Typically the title of the above web page, but can be arbitrary. | +| ~body~ | Body Text | ~%i~ | Typically the selected text in the web page, but can be arbitrary. | + +The template placeholder ~%:annotation~ is expanded to be an Org link constructed from ~url~ and ~title~. + +Users can define different capture templates [[https://orgmode.org/manual/Capture-templates.html][(info "(org) Capture templates")]] using the template placeholders described above. These templates are added to the Org variable ~org-capture-templates~ which itself is a list of templates. + +An example Org protocol capture template is shown below with key name "capture". + +#+begin_src elisp :lexical no +("capture" + "Capture (Org Protocol)" + entry + (file "notes.org") + (function (lambda () + (string-join + '("* %:description" + ":PROPERTIES:" + ":CREATED: %U" + ":END:" + "%:annotation" + "%i" + "" + "%?") + "\n"))) + :prepend t + :empty-lines 1) +#+end_src + +The following Elisp shows how the template "capture" can be added to ~org-capture-templates~. + +#+begin_src elisp :lexical no +(add-hook 'org-mode-hook + (lambda () + (add-to-list 'org-capture-templates + '("capture" + "Capture (Org Protocol)" + entry + (file "notes.org") + (function (lambda () + (string-join + '("* %:description" + ":PROPERTIES:" + ":CREATED: %U" + ":END:" + "%:annotation" + "%i" + "" + "%?") + "\n"))) + :prepend t + :empty-lines 1)))) +#+end_src + + + +***** Setup Org protocol open source + +#+begin_warningbox +This section needs update for Org 9.7.30. +#+end_warningbox This one was designed to help with opening sources for editing when browsing in the first place. =org-protocol-open-source= uses the custom variable @@ -430,7 +371,7 @@ actions. Just register your custom sub-protocol and handler with the variable : M-x org-protocol-create-for-org RET -*** Handle rewritten URLs +******* Handle rewritten URLs In some cases, replacing =:base-url= with =:working-directory= and =:online-suffix= with =:working-suffix= will not yield the desired results. @@ -484,126 +425,148 @@ actions. Just register your custom sub-protocol and handler with the variable The =:rewrites= are searched as a last resort if and only if no existing file name is matched. -* Other browsers -*** Conkeror setup +***** Construct Org protocol URL request +:PROPERTIES: +:CUSTOM_ID: b74d3e67-918c-4e68-934b-532dc9f8654d +:END: - Setting up org-protocol in [[http://conkeror.org/][Conkeror]] (an emacs inspired Mozilla web - browser) requires a slightly different method. You may simply add the - following snippets of code to your .conkerorrc file[fn:2]. +******* Web Browser Bookmark - For org-store-link, add the following to .conkerorrc: +A cross-platform approach to constructing an Org protocol request is to create a web browser bookmark that can run JavaScript as its location. - : function org_store_link (url, title, window) { - : var cmd_str = 'emacsclient \"org-protocol://store-link://'+url+'/'+title+'\"'; - : if (window != null) { - : window.minibuffer.message('Issuing ' + cmd_str); - : } - : shell_command_blind(cmd_str); - : } - : - : interactive("org-store-link", "Stores [[url][title]] as org link and copies url to emacs kill ring", - : function (I) { - : org_store_link(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), I.window); - : }); +1. Create a bookmark in your web browser (Chrome, Firefox, Safari) named "Share Org Link". +2. Add the following code as the location for this bookmark. + #+begin_src js + javascript:location.href='org-protocol://store-link?' + new URLSearchParams({url:location.href, title:document.title});void(0); + #+end_src +3. When visiting a web page, invoke the bookmark "Share Org Link" to share this link to Emacs. Note that a permission may need to be granted with this approach. - For org-capture (or org-remember --- just exchange /capture/ with /remember/), use - the following: +Many different variants of this approach can be taken to cover different Org protocol request types. - : function org_capture (url, title, selection, window) { - : var cmd_str = 'emacsclient \"org-protocol://capture://'+url+'/'+title+'/'+selection+'\"'; - : if (window != null) { - : window.minibuffer.message('Issuing ' + cmd_str); - : } - : shell_command_blind(cmd_str); - : } - : - : interactive("org-capture", "Clip url, title, and selection to capture via org-protocol", - : function (I) { - : org_capture(encodeURIComponent(I.buffer.display_uri_string), encodeURIComponent(I.buffer.document.title), encodeURIComponent(I.buffer.top_frame.getSelection()), I.window); - : }); +******* 3rd Party Applications - Now, you should be able to invoke the commands from within conkeror - with =M-x org-store-link= and =M-x org-capture= (or remember). +********* Firefox - Or, if you'd like your familiar emacs keybindings, you can add the - following to your .conkerorrc: +Firefox users follow the steps documented on https://kb.mozillazine.org/Register_protocol. - : define_key(content_buffer_normal_keymap, "C-c r", "org-capture"); - : define_key(content_buffer_normal_keymap, "C-c l", "org-store-link"); +********* Acrobat Reader + :PROPERTIES: + :CUSTOM_ID: acrobat-reader-setup + :END: -*** Uzbl - :PROPERTIES: - :CUSTOM_ID: uzbl - :END: - Uzbl is a minimalistic webkit browser for Unix/Linux. + #+begin_warningbox + The guidance in this section is likely stale. + + Adapted from [[https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org]] - - [[http://www.uzbl.org/]] + You place a javascript file for each menu entry in + =~/.adobe/Acrobat//JavaScripts= on unix-like systems or + =c:/Program Files/Adobe/Acrobat /Reader/Javascripts/= on + Windows, or wherever your Adobe Reader Installation might look for + javascript. - You can pass encoded url data from uzbl to org-protocol by adding the - following lines to =.config/uzbl/config=. + The examples given here will place new menu entries in the "Tools" + menu, after restarting Adobe Reader. - #+begin_example +,*********** org-store-link.js + : // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org + : app.addMenuItem({cName:"org-store-link", cParent:"Tools", + : cExec:"app.launchURL('org-protocol://store-link://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title));"}); - # Org-protocol +,*********** org-capture.js + : // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org + : app.addMenuItem({cName:"org-capture", cParent:"Tools", + : cExec:"app.launchURL('org-protocol://capture://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"}); - @cbind \\r = sh 'emacsclient "org-protocol://capture://\@\@/\@\@/\@\@"' - @cbind \\l = sh 'emacsclient "org-protocol://capture://\@\@/\@\@"' + And this one, if you still use remember templates: - #+end_example +,*********** org-remember.js + : // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org + : app.addMenuItem({cName:"org-remember", cParent:"Tools", + : cExec:"app.launchURL('org-protocol://remember://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"}); + #+end_warningbox - These bind org-protocol-capture and org-store-line to "\r" and - "\l" respectively. -* Keybindings for Firefox +********* Opera - You can add key bindings for the =org-protocol= commands using the - keyconfig Firefox extension. + #+begin_warningbox + The guidance in this section is likely stale. + + Opera setup is described here: + http://www.opera.com/support/kb/view/535/. - First, install keyconfig from - http://mozilla.dorando.at/keyconfig.xpi. + To set up opera for use with org-protocol, follow these steps: - Open the keyconfig dialog by going to Tools and then Keyconfig. + 1. Choose "/Tools/" -> "/Prefences/" from the menu. + 2. Select the tab "/Advanced/". + 3. Choose "/Programs/" from the list on the left. + 4. Now click the button "/Add/" on the very right. + 5. In the new dialog window, enter "=org-protocol=" as "/Protocol/", choose the + radio button "/Open with other application/" and enter the path to + emacsclient. + #+end_warningbox - Click the 'Add a new Key' button. Enter "Org store link" as the name. - Enter the following in the box with /* CODE */ in it: +----- +* History of Org protocol - : var orgProtoString = 'org-protocol://store-link://'+ - : encodeURIComponent(gBrowser.currentURI.spec) + '/' + - : encodeURIComponent(gBrowser.contentWindow.document.title) + '/' + - : encodeURIComponent(gBrowser.contentWindow.getSelection()); - : - : gBrowser.loadURI(orgProtoString); +#+begin_warningbox +A historical account of Org protocol is needed here. +#+end_warningbox - Click OK. You will then need to bind a key by clicking in the box - next to the 'Apply' button and pressing whatever key combination you - want. Click 'Apply' to store the keybinding. +=org-protocol.el= is based on code and ideas from [[file:../archive/org-contrib/org-annotation-helper.org][org-annotation-helper.el]] and =org-browser-url.el=. - Repeat the steps, but call the next key "Org capture" and use the - code below: +*** Deprecated Formats - : var orgProtoString = 'org-protocol://capture://'+ - : encodeURIComponent(gBrowser.currentURI.spec) + '/' + - : encodeURIComponent(gBrowser.contentWindow.document.title) + '/' + - : encodeURIComponent(content.window.getSelection()); - : - : gBrowser.loadURI(orgProtoString); +Both the ~store-link~, ~capture~, and ~open-source~ protocols have been changed to largely conform to the [[https://datatracker.ietf.org/doc/html/rfc1738#section-3.1][common internet scheme syntax]] of RFC 1738 and [[https://datatracker.ietf.org/doc/html/rfc3986#section-3.4][query component]] specification of RFC 3986. - Click Close, then OK, and then restart Firefox. You should then be - able to access the org-protocol functions with your chosen keys. +This changes the format of the scheme specific part from using ~/~ to separate parameters to using HTTP query ~key=value~ style parameters. + +Old style ~store-link~: + +: org-protocol:/store-link:/URL/TITLE + +New style ~store-link~ protocol: + +: org-protocol://store-link?url=URL&title=TITLE + +Old style ~capture~ protocol: + +: org-protocol:/capture:/URL/TITLE + +New style ~capture~ protocol: + +: org-protocol://capture?url=URL&title=TITLE&body=BODY + +Old style ~open-source~ protocol: + +: org-protocol:/open-source:/URL + +New style ~capture~ protocol: + +: org-protocol://open-source?url=URL + +*** Obsolete Formats + +The ~remember~ protocol is /obsolete/. Users should migrate any configuration relying on it to the ~capture~ protocol. + + +*** Screencast: small introduction to org-protocol.el + +#+begin_warningbox +This video is obsolete. Retained for archival purposes. +#+end_warningbox -* Screencast: small introduction to org-protocol.el #+begin_export html - + #+end_export This screencast shows off some nice things you can do with Firefox, @@ -620,11 +583,4 @@ actions. Just register your custom sub-protocol and handler with the variable a note in my Org files. * Footnotes - -[fn:1] Before commit =fc49c1ec96b2c789f573ae1ba936b930a8494402=, 3rd -Sept. 2010, if a template with the key string "=w=" was defined, this -one was chosen by default. This was done to make bookmarks used for -[[file:./org-annotation-helper.org][org-annotation-helper]] work without changing the template. - -[fn:2] Adapted from Tassilo Horn's [[http://tsdh.wordpress.com/2008/11/14/calling-org-remember-from-inside-conkeror/][blog post]], "Calling org-remember -from inside conkeror," November 14, 2008. +[fn:scrim-captee-disclaimer] Disclaimer: author of this section, Charles Choi, is also the publisher of [[http://yummymelon.com/scrim][Scrim]] and [[http://yummymelon.com/captee][Captee]]. -- 2.49.0