Bug: org-protocol-protocol-alist: needs better description, not mentioning key/value [9.4.4 (release_9.4.4 @ /home/admin/Programming/Software/emacs/lisp/org/)]

Bug: org-protocol-protocol-alist: needs better description, not mentioning key/value [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.
------------------------------------------------------------------------

The variable `org-protocol-protocol-alist' is describing what it has to
contain, but does not describe what `key' has to contain and what
`value' has to contain, as those are entries where user has to enter
something.

Key -- should contain the module name in quotes, this fact is not
described, example on my side is:

Key: "Hyperscope Store Hyperlink"

Value -- should contain the list, but how is that list formatted is not
explained here.

On my side I have tried by providing quoted list, that did not work,
then I figured out myself I would to provide this:

Value: 
(:protocol "store-link" :function hyperscope-org-protocol-store-link)

And I first tried quoting with:

function 'hyperscope-org-protocol-store-link

which did not work, then I tried the above version which did work. It is
a guess work.

The text below should be corrected by developers to tell to users what
belongs to `key' and what exactly belongs to `value', and example of
entering data should be clearly given.


Hide Org Protocol Protocol Alist:
Alist:
INS DEL Key: nil
            Value: nil
INS
    State : EDITED, shown value does not take effect until you set or save it.
   Register custom handlers for org-protocol. Hide
   
   Each element of this list must be of the form:
   
     (module-name :protocol protocol :function func :kill-client nil)
   
   protocol - protocol to detect in a filename without trailing
              colon and slashes.  See rfc1738 section 2.1 for more
              on this.  If you define a protocol "my-protocol",
              ‘org-protocol-check-filename-for-protocol’ will search
              filenames for "org-protocol:/my-protocol" and
              trigger your action for every match.  ‘org-protocol’
              is defined in ‘org-protocol-the-protocol’.  Double and
              triple slashes are compressed to one by emacsclient.
   
   function - function that handles requests with protocol and takes
              one argument.  If a new-style link (key=val&key2=val2)
              is given, the argument will be a property list with
              the values from the link.  If an old-style link is
              given (val1/val2), the argument will be the filename
              with all protocols stripped.
   
              If the function returns nil, emacsclient and -server
              do nothing.  Any non-nil return value is considered a
              valid filename and thus passed to the server.
   
              ‘org-protocol.el’ provides some support for handling
              old-style filenames, if you follow the conventions
              used for the standard handlers in
              ‘org-protocol-protocol-alist-default’.  See
              ‘org-protocol-parse-parameters’.
   
   kill-client - If t, kill the client immediately, once the sub-protocol is
              detected.  This is necessary for actions that can be interrupted by
              ‘C-g’ to avoid dangling emacsclients.  Note that all other command
              line arguments but the this one will be discarded.  Greedy handlers
              still receive the whole list of arguments though.
   
   Here is an example:
   
     (setq org-protocol-protocol-alist
         '(("my-protocol"
            :protocol "my-protocol"
            :function my-protocol-handler-function)
           ("your-protocol"
            :protocol "your-protocol"
            :function your-protocol-handler-function)))


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
⎔ λ 🄯 𝍄 𝌡 𝌚