From 307b3bb9a94edc9b045d0f66268b873b06967fe4 Mon Sep 17 00:00:00 2001 From: Charles Choi Date: Wed, 25 Jun 2025 14:02:44 -0700 Subject: [PATCH 1/2] =?UTF-8?q?org-protocol.org:=20Rename=20"Construct=20O?= =?UTF-8?q?rg=E2=80=A6"=20to=20"Using=20Org=20protocol"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * org-contrib/org-protocol.org (* Construct Org protocol URL Request) Headings previously titled "Construct Org protocol URL Request" have been renamed to (* Using Org protocol). (* 3rd Party Applications) This heading has been removed but its child headings have been promoted up. (* Terminal/Shell) This heading has been added to describe shell command invocation of an Org protocol URL. --- org-contrib/org-protocol.org | 62 +++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/org-contrib/org-protocol.org b/org-contrib/org-protocol.org index e176bd84..4dffa33f 100644 --- a/org-contrib/org-protocol.org +++ b/org-contrib/org-protocol.org @@ -83,7 +83,7 @@ Take the following steps to get Org protocol working for you. 2. Setup the Org protocol scheme handler. 3. Test your Org protocol setup. 4. Setup Org protocol capture. -5. Construct an Org protocol URL request. +5. Using Org protocol. Steps 1, 2, and 5 are platform-specific so this section is largely organized by platform. Setting up Org protocol capture is placed in a @@ -158,8 +158,8 @@ In an Org buffer, use the binding ~C-c M-l~ ***** Setup Org protocol capture See [[#capture][Setup Org protocol capture]] in the common section. -***** Construct Org protocol URL Request -See [[#construct-url-request][Construct Org protocol URL request]] in the common section. +***** Using Org protocol +See [[#using-org-protocol][Using Org protocol]] in the common section. ----- @@ -224,8 +224,8 @@ In an Org buffer, use the binding ~C-c M-l~ ***** Setup Org protocol capture See [[#capture][Setup Org protocol capture]] in the common section. -***** Construct Org protocol URL request -See [[#construct-url-request][Construct Org protocol URL request]] in the common section. +***** Using Org protocol +See [[#using-org-protocol][Using Org protocol]] in the common section. ----- @@ -284,8 +284,8 @@ In an Org buffer, use the binding ~C-c M-l~ ***** Setup Org protocol capture See [[#capture][Setup Org protocol capture]] in the common section. -***** Construct Org protocol URL request -See [[#construct-url-request][Construct Org protocol URL request]] in the common section. +***** Using Org protocol +See [[#using-org-protocol][Using Org protocol]] in the common section. ----- *** Common @@ -463,18 +463,36 @@ This section needs update for Org 9.7.11. The =:rewrites= are searched as a last resort if and only if no existing file name is matched. -***** Construct Org protocol URL request +***** Using Org protocol :PROPERTIES: -:CUSTOM_ID: construct-url-request +:CUSTOM_ID: using-org-protocol :END: +With Org protocol successfully setup, you are ready to use it. Two +steps are required: + +1. Construct the Org protocol URL request. +2. Issue the URL request via the OS scheme handler. + Numerous approaches can be used to construct an Org protocol request: - As a [[#web-browser-bookmark][web browser bookmark]] that can invoke JavaScript -- Via program/script generation (Bash, Python, Java, Go, Rust, C#, etc.) +- 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. +All these approaches require that the OS-dependent scheme handler is +setup for ~org-protocol://~. In this way, 3rd party applications can +delegate to the scheme handler the responsibility of processing the +URL request. + +The scheme handler can be bypassed by direct invocation of +~emacsclient~. That said, on platforms like macOS that employ +sandboxing/hardened runtimes for applications, this will run into +security restrictions that prevent its usage by 3rd party +applications. + +Listed below are some approaches to making an Org protocol URL +request. ******* Web Browser Bookmark :PROPERTIES: @@ -495,18 +513,25 @@ location. share this link to Emacs. Note that a permission may need to be granted with this approach. -Many different variants of this approach can be taken to cover different Org protocol request types. +Many different variants of this approach can be taken to cover +different Org protocol request types. -******* 3rd Party Applications +******* Terminal/Shell +Users with shell access can issue the URL request via a command line +utility. This utility is platform-dependent. -********* Captee (macOS) +On systems supporting [[https://www.freedesktop.org/wiki/][XDG]], the ~xdg-open~ utility can be used. + +On macOS, the [[https://support.apple.com/guide/terminal/execute-commands-and-run-tools-apdb66b5242-0d18-49fc-9c47-a2498b7c91d5/mac][open]] utility can be used. + +******* Captee (macOS) [[http://yummymelon.com/captee][Captee]] is an application that can construct an Org protocol URL from the [[https://support.apple.com/en-by/guide/mac-help/mh40614/mac][macOS Share Menu]][fn:scrim-captee-disclaimer]. Native apps that support the Share Menu can make an Org protocol =store-link= or =capture= request. -********* Acrobat Reader +******* Acrobat Reader :PROPERTIES: :CUSTOM_ID: acrobat-reader-setup :END: @@ -526,12 +551,12 @@ request. The examples given here will place new menu entries in the "Tools" menu, after restarting Adobe Reader. -*********** org-store-link.js +********* 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 +********* 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) + '/');"}); @@ -555,6 +580,7 @@ request. radio button "/Open with other application/" and enter the path to emacsclient. + * Troubleshooting *** Firefox -- 2.50.0