Subject: RE: bug#19914: 25.0.50; `org-store-link' invokes function to add to `org-store-link-functions' twice

From: Drew Adams <[email-masked]>
Date: Sat, 21 Feb 2015 10:01:03 -0800 (PST)

> This means that it will have done its thing TWICE: once just to check
> whether it should/could do its thing and another time so that it does
> its thing.

Also, the doc of `org-store-link-functions' says nothing about the
function being called twice.  It says only:

"Each function should check if it is responsible for creating
 this link (for example by looking at the major mode).
 If not, it must exit and return nil.
 If yes, it should return a non-nil value after a calling
 `org-store-link-props' with a list of properties and values."

(And "a calling" is a typo - it should be "calling".)

This doc is essentially a spec telling you what a function for this
list should do.  From the doc, its purpose is to (a) check whether
it should call `org-store-link-props' and (b) if so, call it and
return non-nil, else return nil (without calling it).

Nothing suggests that the function, if invoked to define a link,
will be invoked twice: once for (a) (even though (b) will also be
done then) and a second time for (b).

---

Also wrt the doc:

The functions on `org-store-link-functions' do not really "create
and store a link", AFAICT.  They merely define a link.  It is
`org-store-link' that uses this definition to create and store a
link.  The most that these functions do is invoke
`org-store-link-props', and that neither creates nor stores a link.

Whether you think of "creating" a link as inserting it somewhere
or just adding it to `org-stored-links' (in which case "creating"
the link is synonymous with "storing" it), the functions on
`org-store-link-functions' do not, themselves, update
`org-stored-links'.  Putting a link on that list is the only thing
that could reasonably be considered "storing" a link, AFAICT.
(Hence the name of function `org-store-link'.)