Hi, Charles,
Charles Choi <kickingve...@gmail.com> writes:
> Interim snapshot of rewrite of Org Protocol page. This is still WIP,
> but intended to illustrate direction of changes to this document.
Thanks for not only updating the Worg documentation for Org protocol,
but also simplifying it in a comprehensive rewrite! When this is
finished, users who come to this page should find it easier and less
intimidating to get started.
Below I have some comments and suggestions, interleaved below the
relevant snippets of your patch (I've cut everything I don't comment
on).
I understand better now why you wanted to archive a copy, but I still
think it's best to make decisions about what to delete and what to
update and commit to them, not to rely on putting parts of the
org-protocol documentation in the archive. Below I've asked for reasons
for deletions, supplied reasons for some, and offered arguments against
some deletions (but am willing to be convinced).
> From 9cbaf959a3518cbcf3aa50a45c26061566861c57 Mon Sep 17 00:00:00 2001
> From: Charles Choi <kickingve...@gmail.com>
> Date: Fri, 30 May 2025 17:46:50 -0700
> Subject: [PATCH 2/2] Rewrite Org Protocol Page (org-protocol.org)
> - Rewrite to support Emacs 30.1 and currently released OS in May 2025.
In the final version, it would be good to expand on this commit message a bit.
I think the changelog should mention the creation of
org-protocol-architecture.svg, and it should note each section that is
deleted, preferably with a brief reason. That will be useful if we do
want to resurrect something from git later. Something along the form:
org-protocol.org: Rewrite to update for 2025
* org-protocol.org (...)
(HEAD): Delete the script and test links.
(Version): Add a section on the Emacs version updated to.
(...)
(Org-protocol-remember): Delete because remember is long obsolete.
(...)
* org-protocol-architecture.svg: Create illustration.
> .../images/org-protocol-architecture.svg | 49 ++
> org-contrib/org-protocol.org | 657 +++---------------
> 2 files changed, 154 insertions(+), 552 deletions(-)
> create mode 100644 org-contrib/images/org-protocol-architecture.svg
>
> diff --git a/org-contrib/images/org-protocol-architecture.svg
> b/org-contrib/images/org-protocol-architecture.svg
> new file mode 100644
> index 00000000..277cb55a
> --- /dev/null
> +++ b/org-contrib/images/org-protocol-architecture.svg
Nice! And thanks for including the dot source for it in
org-protocol.org.
But instead of creating a new images directory in worg/org-contrib, please
create a worg/images/org-protocol dir and place it there.
> diff --git a/org-contrib/org-protocol.org b/org-contrib/org-protocol.org
> index 08d191b4..797c9148 100644
> --- a/org-contrib/org-protocol.org
> +++ b/org-contrib/org-protocol.org
> @@ -1,25 +1,7 @@
> -#+TITLE: org-protocol.el -- Intercept calls from emacsclient to trigger
> custom actions
> +#+TITLE: Org Protocol - Trigger custom actions in Emacs via a custom URL
> scheme
^
--
Titles and styles on Worg vary greatly, but:
(1) When writing "Org protocol" in two unhyphenated words, I'd
recommend using a lower-case p throughout, similar to "Org mode".
(2) The current de facto standard for page titles in the
worg/org-contrib directory is the one used in the existing title:
<package-name> -- <Brief package description>
(Capitalization and use of en/em dashes have varied in practice, but it
needs a dash, not a hyphen.)
I'm not saying you have to follow this, though. This page is in the
org-contrib dir only for historical reasons, and perhaps we'll move it
elsewhere eventually. Anyway, since Org protocol is part of Org,
there's no reason to focus on the package filename, except that it
seems we still have to (require 'org-protocol) to activate it.
(3) If we *do* go for a title that differs from the package
description, I think it should contain keywords a user would be
looking for when they just want a way to tell stuff to Org from the
browser or other apps, unaware that the technicalities might involve
"intercepting calls from emacsclient" or "a custom URL scheme".
Consider using the same language as the manual: "trigger custom
actions in Emacs from external applications". Or perhaps even
something like: "tell stuff to Org from the browser or other apps". :)
> -#+HTML_HEAD_EXTRA: <script type="text/javascript">
> -#+HTML_HEAD_EXTRA: <!--/*--><![CDATA[/*><!--*/
> -#+HTML_HEAD_EXTRA: function makeUrl() {
> -#+HTML_HEAD_EXTRA: return encodeURIComponent(location.href)+
> -#+HTML_HEAD_EXTRA: '/'+encodeURIComponent(document.title)+
> -#+HTML_HEAD_EXTRA: '/'+encodeURIComponent(window.getSelection());
> -#+HTML_HEAD_EXTRA: }
> -#+HTML_HEAD_EXTRA: function storeLink() {
> -#+HTML_HEAD_EXTRA:
> document.location.href='org-protocol://store-link://'+makeUrl();
> -#+HTML_HEAD_EXTRA: }
> -#+HTML_HEAD_EXTRA: function remember() {
> -#+HTML_HEAD_EXTRA:
> document.location.href='org-protocol://remember://'+makeUrl();
> -#+HTML_HEAD_EXTRA: }
> -#+HTML_HEAD_EXTRA: function capture() {
> -#+HTML_HEAD_EXTRA:
> document.location.href='org-protocol://capture://'+makeUrl();
> -#+HTML_HEAD_EXTRA: }
> -#+HTML_HEAD_EXTRA: /*]]>*///-->
> -#+HTML_HEAD_EXTRA: </script>
The JS code is there to support the test links on the page. It's out
of date and doesn't work.
But would it be better to fix this, and to keep some test links? It
seems a helpful way to let users who've got that far test their setup
before they jump through the additional hoop of setting up
bookmarklets. The remember() function should be deleted, but it could
work for storeLink() and capture() (even without the user setting up
capture templates).
Either way, whether it's deleted or changed, it should be noted in the
changelog.
> +* Org Protocol
>
> -* About org-protocol.el
> +Org Protocol is a custom URL scheme used to trigger custom actions in Emacs.
> The URL scheme is ~org-protocol://~. A common use case for Org Protocol is
> data import (for example a web clipper), where an external application can
> make a URL request with scheme ~org-protocol://~ to send data to Emacs.
Thanks, this should make it clearer for new users what Org protocol does.
> +The host part of the URL is interpreted as a /sub-protocol/. There are three
> pre-defined sub-protocols provided by Org Protocol:
The first sentence could be made more informative by an addition like:
"The host part of the URL is interpreted as a /sub-protocol/ that
tells Org what action to take on the data."
>
> - "=org-protocol:/sub-protocol:/=" triggers actions associated with
> =sub-protocol=
> - through the custom variable =org-protocol-protocol-alist=.
> +- ~store-link~ Store a link, push URL to kill-ring.
Please keep this in the description-list form (- ::), it doesn't look
good otherwise.
I agree with simplifying the descriptions, and I see you've followed
the wordings in the manual, but I think they can be made more
informative -- suggestions below.
> +- ~capture~ Fill a buffer with external information.
More informative: "Capture a note and let the user view it in a buffer
before storing it."
> +- ~open-source~ Edit published contents.
More informative: "Open local source files of published contents
for editing."
> +Custom sub-protocols for Org Protocol can be defined in the variable
> ~org-protocol-protocol-alist~.
>
> - - =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 diagram below illustrates how an Org Protocol request is handled.
>
> - =org-protocol= helps creating custom handlers
> [[file:../org-tutorials/org-protocol-custom-handler.org][(tutorial)]] and so
> called
> - =org-protocol-projects=.
Why delete the link to the tutorial? Clearly the tutorial needs updating
too, but if someone can do that, it adds value. That link should be
provided under the line "Custom sub-protocols ..." that you added above.
But the rest of the existing formulation "~org-protocol~ helps
creating custom handlers ... and so-called ~org-protocol-projects~" is
odd. I wonder if this was meant to be a reference to the helper
function `org-protocol-create' and the variable
`org-protocol-project-alist' used for the `open-source' sub-protocol.
Both are documented in the manual [[info:org#The open-source
protocol]], but might be worth mentioning briefly here as well under
the ~open-source~ item above.
> - #+begin_infobox
> - @<b>As of Org mode release 7.01 =org-protocol-remember= is now by
> =org-protocol-capture=.@</b>
Agree that it should be safe to delete this infobox. Remember's been
obsolete for over 10 years.
> +The scheme handler for GNU/Linux and Windows is typically ~emacsclient~. On
> recent versions (since Ventura) of macOS, security policy prevents external
> applications from running programs like ~emacsclient~ outside of their
> sandbox. A commercial offering ([[http://yummymelon.com/scrim][Scrim]]) is
> available to serve as a macOS-trusted scheme handler for Org Protocol
> requests. Users running a version of macOS older than Ventura can still use
> ~emacsclient~ as a scheme handler for Org Protocol.
>
I think a brief disclaimer is in order here to note that the author of this
revision is also the publisher of Scrim.
> +*NOTE*: This document is a rewrite of the
> [[../archive/org-contrib/org-protocol.org][Org Protocol page that is
> archived]].
We're not archiving it, so this note can be removed.
> +
> +* Version
> +All guidance provided on this page should conform to GNU Emacs 30.1.
I suggest "The guidance on this page is up to date with" instead of
"All guidance ... should conform to", because the page also documents
solutions for <30.1, and I'm not sure what it would mean for docs to
"conform" to an emacs version.
> * Installation
> +*** Server
(...)
> +Native Windows has no support for a local domain socket. As such a TCP
> socket is used instead. Add the following lines to the Emacs initialization
> file (~init.el~, ~$HOME/.emacs~) to start Emacs server.
Nitpick: "As such" is redundant, you could just write: "A TCP socket is used
instead."
> +Note that users of the
> [[https://bitbucket.org/mituharu/emacs-mac/src/master/][Yamamoto Mitsuharu
> fork of Emacs]] (aka "Emacs Mac App") do not have to do the above as Org
> Protocol support is /natively/ supported where the scheme handler is
> /built-in/ to Emacs.
Redundant word: "support is ... supported"
Maybe: "where" -> "and"?
> +
> +*** Scheme Handler
> +
> +The scheme handler is generally an OS-level configuration. With recent
> releases of Emacs (e 30.1) and OS, this is little to nothing for the user to
> do.
"this is" -> "there is"
(Not sure why the greater-or-equal to sign is appears as "e" here, it
came out right in the patched file)
> +
> +***** GNU/Linux and Unix variants
> +Emacs 30.1+ now has ~emacsclient.desktop~ configured to handle Org Protocol
> URL requests. For users with older versions of Emacs, refer to [[*Legacy
> Scheme Handler Install][Legacy Scheme Handler Install]].
Perhaps end the first sentence with: ", so no further setup is required."
It's early days for calling <30.1 versions "legacy" -- many users will
be on them for years to come -- but I don't have a better wording for a
short headline.
By the same token, I'm unsure if it's necessary to create the
complicated structure of having subsections per OS plus a "legacy"
sub-section with sub-subsections per OS, instead of just treating older
versions under each OS in this section. I do see that it helps keep
things really short and simple for some users, and it's forward-looking,
in that we *will* eventually want to move that info into a separate
section. But perhaps we should put the "legacy scheme handler" section
on the same level as the "scheme handler" section, not as a subsection
of it.
> +***** Windows
> +
> +#+HTML: <p style='color: red;'><b>NOTE</b>: This section needs UPDATING.
> Need verification from a Windows user in 2025.</p>
I'm OK with leaving the Windows section in this state until we get an
intrepid volunteer willing to entrust their data to Win 11.
You can use the warningbox special block.
> +Refer to [[*Legacy Scheme Handler Install][Legacy Scheme Handler Install]]
> for instructions on configuring Windows to handle the Org Protocol URL scheme.
Without current instructions, this sort of amounts to calling Windows
a legacy system. Which, fair. :)
> +***** Legacy Scheme Handler Install
> +******* GNU/Linux and Unix Variants
> + 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.
Suggest deleting: ", in most cases,"
> +#+HTML: <p style='color: red;'><b>NOTE</b>: This section is STALE. Need
> verification from a Windows user in 2025.</p>
> +
> +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.
You can use the warningbox special block. This section is *really*
ancient, so I'll try to scramble up a Win 10 system to test it on if
noone else volunteers. Then we can rewrite this from scratch.
> -*** Mac OS X setup
> +******* macOS
>
> - 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]].
> +#+HTML: <p style='color: red;'><b>NOTE</b>: This section is STALE. Need
> verification from macOS users using an release older than Ventura (13).</p>
I have a Catalina system lying around that I could test on. Is that too
old to be helpful?
> +*** External App Configuration
>
> -***** Acrobat Reader
> - :PROPERTIES:
> - :CUSTOM_ID: acrobat-reader-setup
> - :END:
Why should information for Acrobat Reader be deleted instead of
updated/corrected?
> +Most web browsers (Chrome, Firefox, Safari) can support a bookmark whose
> address is JavaScript code that will construct the Org Protocol URL. For
> example, a ~store-link~ bookmark address is shown below. This solution works
> across different platforms.
>
> - Adapted from
> [[https://list.orgmode.org/loom.20080527t012114-...@post.gmane.org]]
> +#+begin_src js
> +javascript:location.href='org-protocol://store-link?url='+encodeURIComponent(window.location.href)+'&title='+encodeURIComponent(document.title);
> +#+end_src
Note that the manual now suggests using newURLSearchParams() instead
of repeated calls to encodeURIComponent() for Org >9.4.
It's more compact with multiple params, like for capture.
[[info:org#The capture protocol]]
For backward compatibility I think we can keep the existing code
examples here for a while yet, but maybe there should be a note about
it.
> -***** Opera
Why delete the info for Opera? If the above description of using
bookmarks now applies to Opera without further setup, we could delete
this section, but add Opera to the list of "Most web browsers" above.
If we do have browsers that need special setup in 2025, we could have
a single section covering them.
> +- ~org-capture-templates~
> +- ~org-protocol-default-template-key~
> +- ~org-directory~
> +- ~org-default-notes-file~
>
> +Refer to the Org documentation to understand the workings of the above in
> constructing capture templates for Org Protocol.
Please include links to https://orgmode.org/manual/Capture.html and
https://orgmode.org/manual/The-capture-protocol.html.
> -***** Safari
> - Safari is only supported on Mac systems, not iOS systems.
Does this no longer apply?
> -*** 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
> - <ul>
> - <li><a href="javascript:storeLink();">Org store-link</a></li>
> - <li><a href="javascript:capture();">Org capture (select some text if
> you like)</a></li>
> - <li><a href="javascript:remember();">Org remember (select some text
> please)</a></li>
> - </ul>
> - #+end_export
These functions are (mis)defined in the header in the existing
document. They currently don't work, but storeLink() and capture()
function could be made to work (possibly with a note on what to expect
when you click the link). Worth fixing, rather than deleting?
> -
> -* Using org-protocol
This section may safely be deleted, as the code is out of date and the
content is covered by the instructions you have added above.
As for the remaining sections below, let's not summarily delete them
without articulating the reasons why they should be deleted rather
than updated. Reasons might be that they are redundant because it's
covered in the manual and the above text, or that readers should
consult the documentation for capture; that the problem no longer
exists, that the browsers discussed are no longer used, or that they
can use bookmarks like the other browsers without further setup, etc.
It can be useful to have walkthroughs and tutorials that are more
chatty and hand-holding than the manual, even if they cover the same
basics.
> -* Links and bookmarks: =org-protocol-store-link=
> -
> - =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=":
> -
> - : emacsclient org-protocol:/store-link:/URL/TITLE
This still works, though with a warning to "update your Org Protocol
handler to deal with new-style links". Generally the page should
feature the new style, but perhaps this page should explain about the
historical links that preceded the introduction of query-style links
in Org 9.0.
https://orgmode.org/worg/org-release-notes.html#org090ae89
> - :
> javascript:location.href='org-protocol://store-link://'+encodeURIComponent(location.href)
Would think the old-style links would still be supported in the
browser too, but I can't get them to work.
> -* Note taking and citations: =org-protocol-capture=
> - This one is triggered through the sub-protocol "=capture=" and consumes up
> to
> - three data fields:
> -
> - : emacsclient org-protocol:/capture:/URL/TITLE/BODY
This works too, but the bookmark after doesn't.
> -
> -*** Which capture template is used?
If we update: again, the old CLI emacsclient URL construction actually
still works, but the bookmark should take a query string and a
`template' parameter.
> -
> -***** An example capture template
This duplicates information, but is it useful for the reader to have
it here? I think it probably is. Maybe keep it?
> -*** Org-protocol-remember
> - The =org-protocol-remember= handler is now obsolete. However, the
> handler is
> - still available for backward compatibility.
Delete because remember is obsolete (support was removed in Org 8.0).
> -* Edit published content: =org-protocol-open-source=
This section is now closely duplicated by the manual [[info:org#The
open-source protocol]]. It adds only an example of what
`org-protocol-project-alist' might look like with two projects
defined, which is nice, and could maybe be reused somewhere in the revised page.
> -*** Conkeror setup
> -
> - 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].
(...)
Conkeror saw its last stable release in 2017 and its last change in
2019, but with its emacs philosophy, I wouldn't be surprised if it
still has fans among Org users. Not a priority, but if this info still
works and is still needed for Conkeror, perhaps we should keep it?
Anyone know?
> -*** Uzbl
> - :PROPERTIES:
> - :CUSTOM_ID: uzbl
> - :END:
> -
> - Uzbl is a minimalistic webkit browser for Unix/Linux.
Delete because Uzbl has not seen development for 8 years.
(Uzbl also had a highly idiosyncratic definition of "user-friendly",
and more of a Vi philosophy than an Emacs one. I don't think this
information will be missed.)
> -
> -* Keybindings for Firefox
> -
> - You can add key bindings for the =org-protocol= commands using the
> - keyconfig Firefox extension.
Delete because the referenced extension is no longer available. (?)
> -* Screencast: small introduction to org-protocol.el
Delete because the video source is in a now extinct format (.swf) and
unavailable.
Yours,
Christian
