Capture, template expansion and keyword for link type

Capture, template expansion and keyword for link type

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 933 bytes --]

Hello,


I was reading the Org-mode manual, at section "10.1.3.2 Template
expansion":
https://orgmode.org/manual/Template-expansion.html

And I was a little bit confused by the "%:keyword". The manual say:
"Specific information for certain link types, see below."

Where did this link come from ?

When is it defined, and from/to where ?

To be able to use the "%:keyword" in a capture: Do I need to store a
link before calling org-capture ? Or do the call of org-capture will
automatically store a link to where my point is before the call ?

The manual page of template expansion did not explain it.

Also, if a capture template is selected after an org-protocol call, the
documentation say that only 3 keywords are available: %:link’,
‘%:description’ and ‘%:annotation’.

Is it possible to passe more keyword through an org-protocol call ?



Best regards

-------
Gendre Sébastien

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Capture, template expansion and keyword for link type

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 933 bytes --]

Hello,


I was reading the Org-mode manual, at section "10.1.3.2 Template
expansion":
https://orgmode.org/manual/Template-expansion.html

And I was a little bit confused by the "%:keyword". The manual say:
"Specific information for certain link types, see below."

Where did this link come from ?

When is it defined, and from/to where ?

To be able to use the "%:keyword" in a capture: Do I need to store a
link before calling org-capture ? Or do the call of org-capture will
automatically store a link to where my point is before the call ?

The manual page of template expansion did not explain it.

Also, if a capture template is selected after an org-protocol call, the
documentation say that only 3 keywords are available: %:link’,
‘%:description’ and ‘%:annotation’.

Is it possible to passe more keyword through an org-protocol call ?



Best regards

-------
Gendre Sébastien

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Capture, template expansion and keyword for link type

[Ihor Radchenko]

Sébastien Gendre <seb@k-7.ch> writes:

> I was reading the Org-mode manual, at section "10.1.3.2 Template
> expansion":
> https://orgmode.org/manual/Template-expansion.html
>
> And I was a little bit confused by the "%:keyword". The manual say:
> "Specific information for certain link types, see below."
>
> Where did this link come from ?

> When is it defined, and from/to where ?

> To be able to use the "%:keyword" in a capture: Do I need to store a
> link before calling org-capture ? Or do the call of org-capture will
> automatically store a link to where my point is before the call ?

> The manual page of template expansion did not explain it.
>

1. If there is %a placeholder in the template, org-capture stores link
   to the location from where you called org-capture

2. If there is no placeholder, the last stored link is used

> Also, if a capture template is selected after an org-protocol call, the
> documentation say that only 3 keywords are available: %:link’,
> ‘%:description’ and ‘%:annotation’.
>
> Is it possible to passe more keyword through an org-protocol call ?

Not directly. Additional keywords are stored inside undocumented %:query
keyword value.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Capture, template expansion and keyword for link type

[Max Nikulin]

On 11/07/2024 13:59, Sébastien Gendre wrote:
> I was reading the Org-mode manual, at section "10.1.3.2 Template
> expansion":
> https://orgmode.org/manual/Template-expansion.html
> 
> And I was a little bit confused by the "%:keyword". The manual say:
> "Specific information for certain link types, see below."
> 
> Where did this link come from ?
> 
> When is it defined, and from/to where ?

See the "Link type, Available keywords" table in this section. 
`org-capture' may be executed in various Emacs buffers and available 
keywords may depend on major mode.

> Is it possible to passe more keyword through an org-protocol call ?

Some time ago I tried %(exp) elisp snippets in templates (untested)

       "* [[%:link][%:description]]
#+BEGIN_QUOTE
%i
#+END_QUOTE
%(let ((bla (plist-get (plist-get org-store-link-plist :query) :bla)))
    (or bla "No bla"))"

emacsclient 
'org-protocol:/capture?template=s&title=Hello&body=World&url=http:%2F%2Fexample.com&bla=foo'

Re: Capture, template expansion and keyword for link type

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 2084 bytes --]

Max Nikulin <manikulin@gmail.com> writes:
> See the "Link type, Available keywords" table in this section.
> `org-capture' may be executed in various Emacs buffers and available
> keywords may depend on major mode.

Is it necessary to call "org-store-link" before calling "org-capture" to
extracet the informations used by theses keywords ?

Or did I missundertant how it work ?

I found the documentation unclear about this.

Is there a way to discover the keywords that a major mode provide to a
capture template ?



Max Nikulin <manikulin@gmail.com> writes:
> Some time ago I tried %(exp) elisp snippets in templates (untested)
>
>       "* [[%:link][%:description]]
> #+BEGIN_QUOTE
> %i
> #+END_QUOTE
> %(let ((bla (plist-get (plist-get org-store-link-plist :query) :bla)))
>    (or bla "No bla"))"
>
> emacsclient
> 'org-protocol:/capture?template=s&title=Hello&body=World&url=http:%2F%2Fexample.com&bla=foo'

A new parameter added to the org-protocol url is only accessible through
the ":query" key ? It will not create a new "%:keywoard" automatically ?



What I would love to do, is creating a Firefox extension that can
extract different metadata from known well known web site and pass them
to an Org-mode capture through org-protocol.

For example, for a book, extracting author, title, year, etc.

And then, I could simply create a capture template that would use the
keywords "%:author", "%:title", etc.

I was also thinking, instead of a Firefox extension, creating an Elisp
function that take a web page URL as parameter, extract the metadata
from the web page and then call Org-capture providing the keywords
"%:author", "%:title", etc, to the template.

But I don't know how to do the last part and I cant found documentation
about it. And with this second solution, I don't know how to make it
work with org-protocol. As an org-protocol call result directly in an
Org-capture call. And extracting metadata from Firefox give more
flexibility on manually selecting information to extract on the web page.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Capture, template expansion and keyword for link type

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 1680 bytes --]


Thank you for your reply.

I have write more, after the quotes below.

Ihor Radchenko <yantar92@posteo.net> writes:
> 1. If there is %a placeholder in the template, org-capture stores link
>    to the location from where you called org-capture
>
> 2. If there is no placeholder, the last stored link is used

But how the "%:keyword" information are built ?

What I have understand from the documentation, it has something to do
with a "link". But I found the documentation unclear about this.


The text help for "%:keyword" only say:
"Specific information for certain link types, see below."

And bellow it say:
"For specific link types, the following keywords are defined:"

And the footnote say:
"If you define your own link types (see Adding Hyperlink Types), any
property you store with org-store-link-props can be accessed in capture
templates in a similar way."

As I didn't plan to define custom link, and read all the manual part
about it, as a simple org-capture user I have difficulties to understand
how the "%:keywords" are generated and how I can know which ones a
available in which condition.

At least, based on what the section "10.1.3.2 Template expansion" of
Org-mode documentation tell me.

Mak Nikulin say that these "%:keyword" are created by major modes.


Ihor Radchenko <yantar92@posteo.net> writes:
> Not directly. Additional keywords are stored inside undocumented %:query
> keyword value.

So, I would need to use the "%(EXP)", and as "EXP", I need to write
Elisp code that will extract supplemental data passed on the
org-protocol url during the call ?


Best regards

-------
Gendre Sébastien

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Capture, template expansion and keyword for link type

[Max Nikulin]

On 12/07/2024 03:36, Sébastien Gendre wrote:
> Max Nikulin writes:
>> See the "Link type, Available keywords" table in this section.
>> `org-capture' may be executed in various Emacs buffers and available
>> keywords may depend on major mode.
> 
> Is it necessary to call "org-store-link" before calling "org-capture" to
> extracet the informations used by theses keywords ?
[...]
> I found the documentation unclear about this.

Have a look into `org-capture' code. It calls `org-store-link'.

> Is there a way to discover the keywords that a major mode provide to a
> capture template ?

See specific store link functions, e.g. `org-gnus-store-link'.

>> %(let ((bla (plist-get (plist-get org-store-link-plist :query) :bla)))
>>     (or bla "No bla"))"
>>
>> emacsclient
>> 'org-protocol:/capture?template=s&title=Hello&body=World&url=http:%2F%2Fexample.com&bla=foo'
> 
> A new parameter added to the org-protocol url is only accessible through
> the ":query" key ? It will not create a new "%:keywoard" automatically ?

With "capture" subprotocol it does not mapped to keywords.

> What I would love to do, is creating a Firefox extension that can
> extract different metadata from known well known web site and pass them
> to an Org-mode capture through org-protocol.
> 
> For example, for a book, extracting author, title, year, etc.

Not all books have authors in metadata. Some have editors since every 
chapter has its own author. To avoid handling such logic in capture 
templates I decided to resort to formatting inside an extension (or 
formatting performed by a dedicated tool if site has API, e.g. GitHub).

> And then, I could simply create a capture template that would use the
> keywords "%:author", "%:title", etc.

If you are using Emacs-30 I would suggest to keep away from org-protocol 
hacks and to rely on `server-eval-args-left' handled by a dedicated function

     emacsclient --eval '(my-capture)' 'my-proto://something?param=value'

For older versions you may either use backslash hell like in 
emacsclient-mail.desktop or to define custom subprotocol for org-protocol.

Re: Capture, template expansion and keyword for link type

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 2747 bytes --]


Thank you for your reply.
I wrote more after the quotes below.

Max Nikulin <manikulin@gmail.com> writes:
> Have a look into `org-capture' code. It calls `org-store-link'.

Thank you for this information.


Max Nikulin <manikulin@gmail.com> writes:
>> Is there a way to discover the keywords that a major mode provide to a
>> capture template ?
>
> See specific store link functions, e.g. `org-gnus-store-link'.

Reading the `org-gnus-store-link' function, I see that is set: type,
file, node, link and description.

I have seen that the variable `org-link-parameters' list all the defined
org links. With its different functions, including the store function
(associated with :store parameter).

I wonder if I can write an Elisp function that retrieve all the
properties set for each org link types and tell we at which mode they
are used. After all, with Elisp code could be data too.

But not now.

Anyway, thank you very much. I will explore starting from
`org-link-parameters', as it seems to have a lot of org links. 



Max Nikulin <manikulin@gmail.com> writes:
>> A new parameter added to the org-protocol url is only accessible
>> through
>> the ":query" key ? It will not create a new "%:keywoard" automatically ?
>
> With "capture" subprotocol it does not mapped to keywords.

This morning, I have explored how org-capture work. Especially the
capture subprotocol. I think I will need to make another subprotocol.
Maybe a "capture-plus" that will accept any keys and make all of them
accessible as a '%:keymord'.



Max Nikulin <manikulin@gmail.com> writes:
> Not all books have authors in metadata. Some have editors since every
> chapter has its own author. To avoid handling such logic in capture
> templates I decided to resort to formatting inside an extension (or
> formatting performed by a dedicated tool if site has API, e.g.
> GitHub).

Can you tell me more about this ?



Max Nikulin <manikulin@gmail.com> writes:
>> And then, I could simply create a capture template that would use the
>> keywords "%:author", "%:title", etc.
>
> If you are using Emacs-30 I would suggest to keep away from
> org-protocol hacks and to rely on `server-eval-args-left' handled by a
> dedicated function
>
>     emacsclient --eval '(my-capture)' 'my-proto://something?param=value'
>
> For older versions you may either use backslash hell like in
> emacsclient-mail.desktop or to define custom subprotocol for
> org-protocol.

Is there any change planned for org-protocole in Emacs 30 ?

The big advantage for org-protocole, is that it's based on an URL that
any external software can recognize and pass to Emacs and it's easy to
write a custom sub-protocole.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Capture, template expansion and keyword for link type

[Max Nikulin]

On 12/07/2024 23:34, Sébastien Gendre wrote:
> Max Nikulin writes:
>> See specific store link functions, e.g. `org-gnus-store-link'.
> 
> Reading the `org-gnus-store-link' function, I see that is set: type,
> file, node, link and description.

I see :from :to :subject :message-id :group, :date. Other keywords 
mentioned in the manual are added by `org-link-store-props'.

> I wonder if I can write an Elisp function that retrieve all the
> properties set for each org link types and tell we at which mode they
> are used. After all, with Elisp code could be data too.

It may require non-trivial analysis of code.

> I think I will need to make another subprotocol.
> Maybe a "capture-plus" that will accept any keys and make all of them
> accessible as a '%:keymord'.

I do not think there is any blocker that does not allow you to define 
your own subprotocol. If you find it useful then you will have 
opportunity to contribute it.

>> Not all books have authors in metadata. Some have editors since every
>> chapter has its own author. To avoid handling such logic in capture
>> templates I decided to resort to formatting inside an extension (or
>> formatting performed by a dedicated tool if site has API, e.g.
>> GitHub).
> 
> Can you tell me more about this ?

What particular you are interested in? Are you surprised that some books 
have several authors and some do not have it in citations? I believe 
that elisp code embedded into capture templates is inconvenient to 
debug, that is why I prefer to run formatter in some other way.

>> If you are using Emacs-30 I would suggest to keep away from
>> org-protocol hacks and to rely on `server-eval-args-left' handled by a
>> dedicated function
>>
>>      emacsclient --eval '(my-capture)' 'my-proto://something?param=value'
>>
>> For older versions you may either use backslash hell like in
>> emacsclient-mail.desktop or to define custom subprotocol for
>> org-protocol.
> 
> Is there any change planned for org-protocole in Emacs 30 ?

I do not expect it. Almost certainly only important fixes will be 
committed to that branch.

> The big advantage for org-protocole, is that it's based on an URL that
> any external software can recognize and pass to Emacs and it's easy to
> write a custom sub-protocole.

`server-eval-args-left' allows to do the same without a set of ugly 
enough hacks that were unavoidable to make org-protocol working.