Revised v3 patch (d22ecf53) for org-protocol.org rewrite per feedback from Max Nikulin.
> On Jun 21, 2025, at 6:27 AM, Max Nikulin <maniku...@gmail.com> wrote:
>
> 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.
>
Done.
> To my taste first "custom" may be omitted to avoid repetition.
Done.
> 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.
Documented reformatted via auto-fill-mode.
> I find a similar fragment below in discussion of old style URLs appropriate,
> however I do not see a reason to mention RFC here.
Removed.
>
> Use relative links.
Done.
> Are you going to increment count every year?
Amended wording to avoid maintenance.
> 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.
Moved JavaScript store-link test to follow section “Setup the Org protocol
scheme handler.”
>
> 29.2 would be more precise, especially taking into account "< 30" below.
Amended to refer to 29.2.
>
> 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.
Amended document to address both comments.
> I would prefer human-readable custom_id labels. "#capture" will be shorter.
Changed CUSTOM_ID values to be human-readable.
>
>> #+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?
>
My intent is to emphasize that the user is working with a list of templates. As
such, I thought it would be more instructive to show a single template entry
first and then show how it can be added to `org-capture-templates’.
My usage of `string-join’ is to facilitate readability and maintainability. I
have found that using a string literal with multiple lines to have poor
readability when editing in Elisp mode, particularly if `org-capture-template’
has many templates. Furthermore, I find using a string literal with embedded
“\n” difficult to debug.
> Is it intentional that `org-capture-template' is not referred to as a user
> option that may be customized?
No intention. I have amended to describe `org-capture-template’ as a
customizable variable.
>
> Have you encountered issues with the open-source sub-protocol in Emacs-30?
I have not had the cycles to test the open-source protocol in Emacs 30 as I do
not particularly use it. My reading of the current Org 9.7.30 documentation is
that the term “sub-protocol” has been dropped in favor of “protocol”.
>
> Has not emacs-30.1 been released with 9.7.11? If so, I would not use 9.7.30
> in this document.
Amended to only refer to Org 9.7.11.
>
>> ********* 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.
This is legacy text that I moved to a new “Troubleshooting” section.
>
> 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.
The Acrobat reader section has been modified so that the headings are preserved.
> I can not say that I like tables too much, but I would consider a table here
> to avoid "Old style"/"New style" repetitions.
>
This section reformatted to use a table.
>
> 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.
Amended to use “Protocols” instead of “Formats”.
Thanks again for the feedback Max.
0001-org-protocol.org-Rewrite-for-2025.patch
Description: Binary data
— Charles Y. Choi, Ph.D. kickingve...@gmail.com
