Re: [PATCH v5] WORG Org Protocol Page Rewrite

[Christian Moe]

In a thread on the ongoing update of the Worg org-protocol page,
Charles Choi <kickingvegas@gmail.com> wrote:
> - A historical account of Org protocol is needed.
>   - As I was not an Org user at the time of Org protocol’s inception,
> I do not consider myself qualified to account on it.

(Copying in Bastien, who was very much there at the inception.)

This was the outcome of a discussion on what to do with Worg materials
that were obsolete as instructions, but seemed to have some historical
interest. 

I've drafted a history section, attached here as a patch. Comments and
corrections welcome!

If it works out well here, we might think about eventually adding
history sections to other pages where it makes sense as well.

(One thing I haven't managed to pin down: org-protocol must have started
out in the contrib directory, as it's still in the org-contrib section
for historical reasons, but I think it must have been moved into core
right away in 2009 ... ?)

Regards,
Christian

>From 1427cb8cdabc76664e4c602d6346de35351bb6fb Mon Sep 17 00:00:00 2001
From: Christian Moe <mail@christianmoe.com>
Date: Tue, 15 Jul 2025 13:54:37 +0200
Subject: [PATCH] org-protocol.org: Add history section

* org-contrib/org-protocol.org (*History of Org protocol): Add
historical narrative.  Integrate old screencast.
(*Screencast): Delete as separate section.
(*Deprecated URL Styles): Add custom ID.
---
 org-contrib/org-protocol.org | 89 +++++++++++++++++++++++-------------
 1 file changed, 56 insertions(+), 33 deletions(-)

diff --git a/org-contrib/org-protocol.org b/org-contrib/org-protocol.org
index 77a3176f..0d73ac2e 100644
--- a/org-contrib/org-protocol.org
+++ b/org-contrib/org-protocol.org
@@ -552,17 +552,69 @@ request.
 
 Firefox users can follow the steps documented on 
https://kb.mozillazine.org/Register_protocol.
 
------
+
 * History of Org protocol
+:PROPERTIES:
+:CUSTOM_ID: history
+:END:
+
+Org protocol was originally 
[[https://list.orgmode.org/20071106154907.5d68b019@dhcp-296-6/][inspired]] by 
Geert Kloosterman's setup for
+passing a URL and page title from a browser to Planner mode with
+custom =remember://= and =annotate://= protocols, using a bookmarklet,
+a bash script, emacsclient, and =remember.el=. 
[[https://list.orgmode.org/874pfyre0g.fsf@bzg.ath.cx][Bastien Guerry adapted
+it]] into the =org-annotation-helper.el= module in 2007. Daniel M German
+[[https://list.orgmode.org/87mymppyx1.fsf@uvic.ca/][updated]] the module the 
following year, when it was 
[[https://list.orgmode.org/70800982-FF12-4587-AFB9-36DDF3373C98@uva.nl/][included]]
 into the
+Org =contrib= directory. Taking a different approach, 
[[https://list.orgmode.org/878wrax5qf.fsf@transitory.lefae.org/][Ross Patterson
+contributed]] =org-browse-url.el=, for storing a link from the browser
+without relying on Remember templates or inserting it into a buffer.
+Inspired by these libraries, 
[[https://list.orgmode.org/87d4d3oqln.fsf@kassiopeya.MSHEIMNETZ/][Sebastian 
Rose published]] a setup to open
+the source of a published Worg file in 2009, and soon generalized it to
+other "worglets."
+
+These packages were [[../org-release-notes.org::#v6.25][superseded in Org 
version 6.25 (April 2009) by
+Sebastian Rose's =org-protocol.el=]]. Org protocol provided a more
+abstracted interface: Only one protocol had to be configured with
+external applications or the operating system. The three approaches
+above became the =remember= (now =capture=), =store-link=, and
+=open-source= schemes.  The following screencast by Bastien Guerry
+(2009) showcases Org protocol as it looked at the time, using Firefox
+and emacsclient.
 
 #+begin_warningbox
-A historical account of Org protocol is needed here.
+This video is obsolete. Retained for historical purposes.
 #+end_warningbox
 
-=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=.
+#+begin_export html
+<video controls
+       <source 
src="https://bzg.fr/uploads/store-links-in-emacs-org-using-org-protocol.mp4"; 
type="video/webm">
+       <source 
src="https://bzg.fr/uploads/store-links-in-emacs-org-using-org-protocol.mp4"; 
type="video/mp4">
+<p>
+  Your browser does not support HTML video.
+</p>
+</video>
+#+end_export
+
+During these developments, Org mode relied on [[info:remember#Top][John 
Wiegley's Remember
+mode]] for capturing information with the =org-remember.el= module. To
+make the code easier to maintain and offer more options, Carsten
+Dominik 
[[https://list.orgmode.org/orgmode/C46F10DC-DE51-43D4-AFFE-F71E440D1E1F@gmail.com/][rewrote
 and renamed it]] as the independent =org-capture.el=
+module (Org version 
[[https://list.orgmode.org/87bolcr957.fsf@altern.org/][7.8.11]], 2010). 
Accordingly, the Org protocol
+=remember= scheme was renamed as =capture=. Parallel support for the
+now partly incompatible Remember in Org protocol was finally dropped
+with the major update in 
[[https://list.orgmode.org/87ehe7yenk.fsf@bzg.ath.cx][version 8.0]] (2013).
+
+The Org protocol URL schemes originally used positional parameters
+separated by slashes. They were replaced by HTTP query-style
+=?key=value= parameters in version 9.0. Since version 9.5, Org
+protocol has also understood such parameters constructed with the
+=URLSearchParams= Javascript class, which makes for more readable
+bookmarklets. As of 2025, Org protocol still supports "old-style
+links" (see [[*Deprecated URL Styles]]), but raises a warning.
 
 *** Deprecated URL Styles
+:PROPERTIES:
+:CUSTOM_ID: deprecated-url-styles
+:END:
 
 The =store-link=, =capture=, and =open-source= URL styles have been
 changed to largely conform to the 
[[https://datatracker.ietf.org/doc/html/rfc1738#section-3.1][common internet 
scheme syntax]] of RFC
@@ -598,35 +650,6 @@ styles. Migrating from the old style to new is recommended.
 The ~remember~ protocol is /removed/. 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
-
-  #+begin_export html
-  <video controls
-  <source 
src="https://bzg.fr/uploads/store-links-in-emacs-org-using-org-protocol.mp4"; 
type="video/webm">
-  <source 
src="https://bzg.fr/uploads/store-links-in-emacs-org-using-org-protocol.mp4"; 
type="video/mp4">
-  <p>
-  Your browser does not support HTML video.
-  </p>
-  </video>
-  #+end_export
-
-  This screencast shows off some nice things you can do with Firefox,
-  Emacs, Org-mode and org-protocol.el.
-
-  It first shows how to create two bookmarklets, =org-capture= and
-  =org-store-link=. These bookmarklets enable your Firefox to talk to
-  emacsclient via a new protocol (=org-protocol://=); emacsclient then
-  parses the request and tells Emacs to capture or store stuff at the
-  relevant places in your Org files.
-
-  At the end of the screencast, we create two ubiquity commands from
-  these bookmarklets.  Now in Firefox =ALT-SPC org-capture RET= creates
-  a note in my Org files.
-
 * Footnotes
 
 [fn:scrim-captee-disclaimer] Disclaimer: author of this section,
-- 
2.43.0