Bug: Org manual, 16.15.2 The ‘capture’ protocol, possible error [9.4.4 (release_9.4.4 @ /home/admin/Programming/Software/emacs/lisp/org/)]

Bug: Org manual, 16.15.2 The ‘capture’ protocol, possible error [9.4.4 (release_9.4.4 @ /home/admin/Programming/Software/emacs/lisp/org/)]

[Jean Louis]

Remember to cover the basics, that is, what you expected to happen and
what in fact did happen.  You don't know how to make a good report?  See

     https://orgmode.org/manual/Feedback.html#Feedback

Your bug report will be posted to the Org mailing list.
------------------------------------------------------------------------

16.15.2 The ‘capture’ protocol
------------------------------

Activating the “capture” handler pops up a ‘Capture’ buffer in Emacs,
using acapture template.

     emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY

In my opinion above line has errors and places "?" where actually the
symbol "&" should be.

This works:

emacsclient 'org-protocol://store-link?url=http://www.gnu.org&title=GNU.org'

while this does not work:

emacsclient 'org-protocol://store-link?url=http://www.gnu.org?title=GNU.org'

Thus the line should be shown as below in the manual:

emacsclient org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY

and I would recommend quoting:

emacsclient 'org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY'

Emacs  : GNU Emacs 28.0.50 (build 1, x86_64-pc-linux-gnu, X toolkit, cairo version 1.17.4, Xaw scroll bars)
 of 2021-03-15
Package: Org mode version 9.4.4 (release_9.4.4 @ /home/admin/Programming/Software/emacs/lisp/org/)
-- 
Thanks,
Jean Louis
⎔ λ 🄯 𝍄 𝌡 𝌚

Re: Bug: Org manual, 16.15.2 The ‘capture’ protocol, possible error [9.4.4 (release_9.4.4 @ /home/admin/Programming/Software/emacs/lisp/org/)]

[Maxim Nikulin]

On 21/03/2021 14:04, Jean Louis wrote:
>  >       emacsclient 
org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY

Certainly extra question marks should be replaced by "&".

> emacsclient 'org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY'

However I am in doubts if such form with double slash should be 
recommended if org-protocol scheme is registered in desktop settings. 
Subprotocol "capture" could be parsed as host name before passing to 
handler. With old syntax and colon after subprotocol the problem was 
more severe:
https://github.com/sprig/org-capture-extension/issues/16
Colon in some desktop environments may be dropped since port number 
after it is not specified. It seems with new syntax a similar problem 
could happen as well:
https://code.orgmode.org/bzg/org-mode/commit/928e67df
These complications are irrelevant if org-protocol URI is passed 
directly to emacsclient bypassing desktop handlers.

Is any problem expected with single slash after the scheme?

org-protocol:/capture?template=X&url=URL&title=TITLE&body=BODY

Alternatively 3 slashes could be used in examples:

org-protocol:///capture?template=X&url=URL&title=TITLE&body=BODY

I hope, "capture" in both variants is parsed as part of path, so it is 
safer. On the other hand I could not test on Mac and Windows. Even some 
linux distribution could be some specific.

Such change could be committed in optimistic way if nobody will object, 
not requiring to confirm that it works on every OS.

A have a couple more questions.

Is it intended decision that no leading slash is not allowed?
org-protocol:capture?template=T&...
In my opinion it is similar to mailto: scheme, so subprotocol should not 
be considered as hostname.

Is there any reason that space can not be encoded as "+"? It is allowed 
in query URL part and it prevents direct usage of modern API available 
in JavaScript:
String(new URLSearchParams({template: "X", url: "https://orgmode.org/", 
title: "Org mode"}))
"template=X&url=https%3A%2F%2Forgmode.org%2F&title=Org+mode"

I guess that decoding of "+" just was not necessary in old syntax since 
all parameters were encoded as path components. Could anything bad 
happen due to update of decode function to allow "+"?

[PATCH 1/2] org-manual.org: Fix typo in org-protocol capture example

[Maxim Nikulin]

* doc/org-manual.org: Use "&" as parameter separator in query part
of example for org-protocol capture URI.
---
 doc/org-manual.org | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 258576b24..e2fbdceb4 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -19640,7 +19640,7 @@ javascript:location.href='org-protocol://store-link?url='+
 Activating the "capture" handler pops up a =Capture= buffer in Emacs,
 using acapture template.
 
-: emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY
+: emacsclient org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY
 
 To use this feature, add a bookmark with an arbitrary name, e.g.,
 =Org: capture=, and enter this as =Location=:
-- 
2.25.1

Re: [PATCH 1/2] org-manual.org: Fix typo in org-protocol capture example

[Kyle Meyer]

Maxim Nikulin writes:

> * doc/org-manual.org: Use "&" as parameter separator in query part
> of example for org-protocol capture URI.

Thank you.  Pushed this and the next patch (4de2fff87), with a minor
formatting tweak to the second commit message.

[PATCH 2/2] Add quotes to emacsclient arguments in examples

[Maxim Nikulin]

* doc/org-manual.org, lisp/org-protocol.el: Quote emacsclient arguments
in examples to prevent interpreting of ampersands as intent
to run processes in background by bash and similar shells.
Single quotes may cause a problem with cmd.exe, so use
double quotes despite they are a bit less safe in bash and Co.
---
 doc/org-manual.org   | 6 +++---
 lisp/org-protocol.el | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index e2fbdceb4..efe956877 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -19588,7 +19588,7 @@ passed to Emacs through the =emacsclient= command, so you also need to
 ensure an Emacs server is running.  More precisely, when the
 application calls
 
-: emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2
+: emacsclient "org-protocol://PROTOCOL?key1=val1&key2=val2"
 
 #+texinfo: @noindent
 Emacs calls the handler associated to {{{var(PROTOCOL)}}} with
@@ -19611,7 +19611,7 @@ Using the ~store-link~ handler, you can copy links, to that they can
 be inserted using {{{kbd(M-x org-insert-link)}}} or yanking.  More
 precisely, the command
 
-: emacsclient org-protocol://store-link?url=URL&title=TITLE
+: emacsclient "org-protocol://store-link?url=URL&title=TITLE"
 
 #+texinfo: @noindent
 stores the following link:
@@ -19640,7 +19640,7 @@ javascript:location.href='org-protocol://store-link?url='+
 Activating the "capture" handler pops up a =Capture= buffer in Emacs,
 using acapture template.
 
-: emacsclient org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY
+: emacsclient "org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY"
 
 To use this feature, add a bookmark with an arbitrary name, e.g.,
 =Org: capture=, and enter this as =Location=:
diff --git a/lisp/org-protocol.el b/lisp/org-protocol.el
index 6f8cf00e9..731f51e19 100644
--- a/lisp/org-protocol.el
+++ b/lisp/org-protocol.el
@@ -49,7 +49,7 @@
 ;;   4.) Try this from the command line (adjust the URL as needed):
 ;;
 ;;       $ emacsclient \
-;;         org-protocol://store-link?url=http:%2F%2Flocalhost%2Findex.html&title=The%20title
+;;         "org-protocol://store-link?url=http:%2F%2Flocalhost%2Findex.html&title=The%20title"
 ;;
 ;;   5.) Optionally add custom sub-protocols and handlers:
 ;;
-- 
2.25.1

Re: [PATCH 2/2] Add quotes to emacsclient arguments in examples

[Maxim Nikulin]

On 28/03/2021 23:38, Maxim Nikulin wrote:
> * doc/org-manual.org, lisp/org-protocol.el: Quote emacsclient arguments
> in examples to prevent interpreting of ampersands as intent
> to run processes in background by bash and similar shells.
> Single quotes may cause a problem with cmd.exe, so use
> double quotes despite they are a bit less safe in bash and Co.

Let's remove it from the list of pending patches.

Applied by Kyle Meyer as commit a17243f9a5, see mid:87lfa67eul.fsf@kyleam.com