On 18/06/2025 03:33, Charles Choi wrote:
Patch 5141b91f for org-protocol.org 2025-06-17 rewrite submitted for review.
From my point of view, it would be easier to find your patch if it was
a reply to your the initial message of the thread and if it had "[PATCH
v2]" tag in its subject. I admit, gmail web UI may easily break the
thread on attempt to edit message subject.
+++ 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
To my taste first "custom" may be omitted to avoid repetition.
-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.
Notice that originally the document had hard wrapped lines instead of a
line per paragraph. My opinion is that the former is more friendly to
git with its line based diffs.
+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.
I find a similar fragment below in discussion of old style URLs
appropriate, however I do not see a reason to mention RFC here.
Side notes:
- In my opinion org-protocol docs violate URL spec because they use
action keyword after double slash where host name is expected.
Implementation of org-protocol allows single slash and in some cases it
is more reliable. Perhaps I confused you when I was trying to say the
same in earlier messages.
- I admit the following document is primary for browsers, but still:
<https://url.spec.whatwg.org/>
Goals
Align RFC 3986 and RFC 3987 with contemporary implementations and
obsolete the RFCs in the process.
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~.
Use relative links.
Are you going to increment count every year?
*** GNU/Linux, BSD, and Unix variants
***** Setup Emacs server
[...]
To test that Org protocol is setup and running, click on the link below to
store an Org link to this page.
#+begin_export html
<ul>
<li><a href="javascript:storeLink();">Test Org protocol
store-link</a></li>
</ul>
#+end_export
In an Org buffer, use the binding ~C-c M-l~ (~org-insert-last-stored-link~) to
paste the recently stored Org link.
***** Setup the Org protocol scheme handler
I find the order of section confusing. It is too early to try
org-protocol in browser before setting a scheme handler. At this step
emacsclient command may be used, but not something at higher level.
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]].)
29.2 would be more precise, especially taking into account "< 30" below.
#+begin_warningbox
NOTE: This section may be stale.
Users with an older (< 30) version of Emacs can use this guidance.
I do not like large warningbox blocks. From my point of view, in most
cases blocks requiring attention should be concise.
I believe that significant fraction of Linux users (or most of them)
still need custom .desktop file, so it is not really stale.
***** Setup Org protocol capture
See [[#1401e4ba-85e1-4860-bd64-d6e97ecf1fa1][Setup Org protocol capture]] in
the common section.
I would prefer human-readable custom_id labels. "#capture" will be shorter.
#+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
Is this repetition required? Why first source code block can not be
dropped? What is the reason to use `string-join' where string literal
with multiple lines may be used?
Is it intentional that `org-capture-template' is not referred to as a
user option that may be customized?
Single empty line before next section should be enough.
***** Setup Org protocol open source
#+begin_warningbox
This section needs update for Org 9.7.30.
#+end_warningbox
Have you encountered issues with the open-source sub-protocol in Emacs-30?
Has not emacs-30.1 been released with 9.7.11? If so, I would not use
9.7.30 in this document.
********* Firefox
Firefox users follow the steps documented on
https://kb.mozillazine.org/Register_protocol.
What OSes requires this link? I do not mind to have this link in
(currently absent) "Troubleshooting" section, but I am in doubts if it
is necessary here.
********* Acrobat Reader
:PROPERTIES:
:CUSTOM_ID: acrobat-reader-setup
:END:
#+begin_warningbox
The guidance in this section is likely stale.
Adapted from [[https://list.orgmode.org/loom.20080527t012114-...@post.gmane.org]]
You place a javascript file for each menu entry in
=~/.adobe/Acrobat/<VERSION>/JavaScripts= on unix-like systems or
=c:/Program Files/Adobe/Acrobat <VERSION>/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
Have you tried to export your variant? Subsection markup is escaped. For
stale content blindtext may be more appropriate than warningbox Blocks
do not allow headings inside however. Description list may be an
alternative.
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:
I can not say that I like tables too much, but I would consider a table
here to avoid "Old style"/"New style" repetitions.
*** Obsolete Formats
The ~remember~ protocol is /obsolete/. Users should migrate any configuration
relying on it to the ~capture~ protocol.
Why you named it "Formats"? There was "remember:" scheme and
"org-protocol:/remember" sub-protocol (or protocol) and both have been
*removed*. They are not just obsolete now.
