In a thread on the ongoing update of the Worg org-protocol page, Charles Choi <kickingve...@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 <m...@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....@bzg.ath.cx][Bastien Guerry adapted +it]] into the =org-annotation-helper.el= module in 2007. Daniel M German +[[https://list.orgmode.org/87mymppyx1....@uvic.ca/][updated]] the module the following year, when it was [[https://list.orgmode.org/70800982-ff12-4587-afb9-36ddf3373...@uva.nl/][included]] into the +Org =contrib= directory. Taking a different approach, [[https://list.orgmode.org/878wrax5qf....@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-f71e440d1...@gmail.com/][rewrote and renamed it]] as the independent =org-capture.el= +module (Org version [[https://list.orgmode.org/87bolcr957....@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....@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
