[PATCH] Update documentation on org-protocol template placeholders

[PATCH] Update documentation on org-protocol template placeholders

[Allen Li]

* doc/org.texi (@code{capture} protocol): Fix placeholder names
(Template expansion): Add org-protocol placeholders

* lisp/org.el (org-store-link-plist): Fix docstring grammar
(org-store-link-props): Fix docstring grammar
---
 doc/org.texi | 25 +++++++++++++++++--------
 lisp/org.el  |  5 +++--
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 999f3f719..4039e127a 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -7351,6 +7351,7 @@ gnus                             |  %:group,
@r{for messages also all email fiel
 eww, w3, w3m                     |  %:url
 info                             |  %:file %:node
 calendar                         |  %:date
+org-protocol                     |  %:link %:description %:annotation
 @end smallexample

 @noindent
@@ -7592,15 +7593,14 @@
javascript:location.href='org-protocol://store-link?url='+
 @cindex capture protocol
 @cindex protocol, capture

-@cindex capture, %:url placeholder
-@cindex %:url template expansion in capture
-@cindex capture, %:title placeholder
-@cindex %:title template expansion in capture
+@cindex capture, %:link placeholder
+@cindex %:link template expansion in capture
+@cindex capture, %:description placeholder
+@cindex %:description template expansion in capture
+@cindex capture, %:annotation placeholder
+@cindex %:annotation template expansion in capture
 Activating @code{capture} handler pops up a @samp{Capture} buffer and fills
-the capture template associated to the @samp{X} key with them.  The template
-refers to the data through @code{%:url} and @code{%:title} placeholders.
-Moreover, any selected text in the browser is appended to the body of the
-entry.
+the capture template associated to the @samp{X} key with them.

 @example
 emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY
@@ -7621,6 +7621,15 @@ The result depends on the capture template
used, which is set in the bookmark
 itself, as in the example above, or in
 @code{org-protocol-default-template-key}.

+The following template placeholders are available:
+
+@example
+%:link          The URL
+%:description   The webpage title
+%:annotation    Equivalent to [[%:link][%:description]]
+%i              The selected text
+@end example
+
 @node @code{open-source} protocol
 @subsection @code{open-source} protocol
 @cindex open-source protocol
diff --git a/lisp/org.el b/lisp/org.el
index d6cd77bf9..3bcfae72a 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -9573,7 +9573,7 @@ sub-tree if optional argument INHERIT is non-nil."
   "Contains the links stored with `org-store-link'.")

 (defvar org-store-link-plist nil
-  "Plist with info about the most recently link created with
`org-store-link'.")
+  "Plist with info about the most recent link created with `org-store-link'.")

 (defun org-store-link-functions ()
   "Return a list of functions that are called to create and store a link.
@@ -9847,7 +9847,8 @@ active region."
  (car org-stored-links)))))

 (defun org-store-link-props (&rest plist)
-  "Store link properties, extract names, addresses and dates."
+  "Store link properties.
+The properties are preprocessed by extracting names, addresses and dates."
   (let ((x (plist-get plist :from)))
     (when x
       (let ((adr (mail-extract-address-components x)))
-- 
2.14.2

Re: [PATCH] Update documentation on org-protocol template placeholders

[Nicolas Goaziou]

Hello,

Allen Li <vianchielfaura@gmail.com> writes:

> * doc/org.texi (@code{capture} protocol): Fix placeholder names
> (Template expansion): Add org-protocol placeholders
>
> * lisp/org.el (org-store-link-plist): Fix docstring grammar
> (org-store-link-props): Fix docstring grammar

Thank you.

> +The following template placeholders are available:
> +
> +@example
> +%:link          The URL
> +%:description   The webpage title
> +%:annotation    Equivalent to [[%:link][%:description]]
> +%i              The selected text
> +@end example

This is not directly related to your patch, but isn't something wrong
here? 

I.e., shouldn't Org Protocol be able to capture arbitrary keywords
according to the attributes of the "org-protocol" link? What is the
point of using

  ?url=...&title=...&body=...

if you cannot access directly to :url, :title and :body from the capture
template thereafter?

Disclaimer: I'm not using Org Protocol at all so I may be missing
something.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] Update documentation on org-protocol template placeholders

[Allen Li]

On Tue, Oct 17, 2017 at 1:01 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>
> This is not directly related to your patch, but isn't something wrong
> here?
>
> I.e., shouldn't Org Protocol be able to capture arbitrary keywords
> according to the attributes of the "org-protocol" link? What is the
> point of using
>
>   ?url=...&title=...&body=...
>
> if you cannot access directly to :url, :title and :body from the capture
> template thereafter?

That sounds like a good idea, but the current behavior appears to be
how it was added in 2009 by Carsten.  I'm only documenting the current
behavior, not improving it.

>
> Disclaimer: I'm not using Org Protocol at all so I may be missing
> something.
>
> Regards,
>
> --
> Nicolas Goaziou

Re: [PATCH] Update documentation on org-protocol template placeholders

[Nicolas Goaziou]

Hello,

Allen Li <vianchielfaura@gmail.com> writes:

> That sounds like a good idea, but the current behavior appears to be
> how it was added in 2009 by Carsten.  I'm only documenting the current
> behavior, not improving it.

True. Applied. Thank you.

Regards,

-- 
Nicolas Goaziou