Re: [nongnu] elpa/org-contrib eaef050f28: lisp/ox-bibtex.el (org-bibtex-goto-citation): Add missing require

Re: [nongnu] elpa/org-contrib eaef050f28: lisp/ox-bibtex.el (org-bibtex-goto-citation): Add missing require

[Stefan Monnier]

> diff --git a/lisp/ox-bibtex.el b/lisp/ox-bibtex.el
> index 743fd7da2a..8cdf390cf2 100644
> --- a/lisp/ox-bibtex.el
> +++ b/lisp/ox-bibtex.el
> @@ -157,9 +157,11 @@ to `org-bibtex-citation-p' predicate."
>  (defvar org-bibtex-file nil
>    "Org file of BibTeX entries.")
>  
> +(declare-function obe-citations "org-bibtex-extras" ())
>  (defun org-bibtex-goto-citation (&optional citation)
>    "Visit a citation given its ID."
>    (interactive)
> +  (require 'org-bibtex-extras)
>    (let ((citation (or citation (completing-read "Citation: " (obe-citations)))))
>      (find-file (or org-bibtex-file
>  		   (error "`org-bibtex-file' has not been configured")))

The `declare-function` should be placed right next (after) the
`require`.  In practice it (currently) makes no difference (because of
technical details of how `declare-function` is (currently) implemented),
but in theory it clarifies that you do not intend to claim that it's safe
to call `obe-citations` from anywhere within `ox-bibtex`, but only from
within `org-bibtex-goto-citation`.


        Stefan

Re: [nongnu] elpa/org-contrib eaef050f28: lisp/ox-bibtex.el (org-bibtex-goto-citation): Add missing require

[Ihor Radchenko]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> The `declare-function` should be placed right next (after) the
> `require`.  In practice it (currently) makes no difference (because of
> technical details of how `declare-function` is (currently) implemented),
> but in theory it clarifies that you do not intend to claim that it's safe
> to call `obe-citations` from anywhere within `ox-bibtex`, but only from
> within `org-bibtex-goto-citation`.

Interesting.
I am wondering if byte-compiler can somehow detect such scenarios and
throw a warning.

-- 
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: [nongnu] elpa/org-contrib eaef050f28: lisp/ox-bibtex.el (org-bibtex-goto-citation): Add missing require

[Stefan Monnier]

Ihor Radchenko [2024-01-30 15:19:47] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> The `declare-function` should be placed right next (after) the
>> `require`.  In practice it (currently) makes no difference (because of
>> technical details of how `declare-function` is (currently) implemented),
>> but in theory it clarifies that you do not intend to claim that it's safe
>> to call `obe-citations` from anywhere within `ox-bibtex`, but only from
>> within `org-bibtex-goto-citation`.
>
> Interesting.
> I am wondering if byte-compiler can somehow detect such scenarios and
> throw a warning.

In theory, if you "fix" the code as I suggested and call `obe-citations`
from outside of `org-bibtex-goto-citation`., the byte-compiler could
emit a warning.  Is that what you mean?

If you mean that the byte-compiler should warn about the current code,
it's kind of impossible: `declare-function` is specifically designed
to tell the compiler about the fact that a function is available when
the compiler doesn't know it.

IOW in order to figure out that the warning is ill-placed the compiler
would need to know how/when that function is defined, thus making
the declaration unnecessary anyway.

But yes, we could try and improve the tooling that checks those
`declare-function`s, tho currently we only provide checks to make sure
the function is indeed defined in the specified file.  We don't try
to figure out if that function will indeed be loaded/available at the
point the `declare-function` is placed (which is a much more difficult
problem).


        Stefan

Re: [nongnu] elpa/org-contrib eaef050f28: lisp/ox-bibtex.el (org-bibtex-goto-citation): Add missing require

[Ihor Radchenko]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I am wondering if byte-compiler can somehow detect such scenarios and
>> throw a warning.
>
> In theory, if you "fix" the code as I suggested and call `obe-citations`
> from outside of `org-bibtex-goto-citation`., the byte-compiler could
> emit a warning.  Is that what you mean?

I mean an opposite: if `declare-function' is called globally, but the
actual function is only called by a single function in the file, emit
warning.

What you suggest also makes sense.

-- 
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: [nongnu] elpa/org-contrib eaef050f28: lisp/ox-bibtex.el (org-bibtex-goto-citation): Add missing require

[Stefan Monnier]

Ihor Radchenko [2024-01-30 18:59:59] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>>> I am wondering if byte-compiler can somehow detect such scenarios and
>>> throw a warning.
>>
>> In theory, if you "fix" the code as I suggested and call `obe-citations`
>> from outside of `org-bibtex-goto-citation`., the byte-compiler could
>> emit a warning.  Is that what you mean?
>
> I mean an opposite: if `declare-function' is called globally, but the
> actual function is only called by a single function in the file, emit
> warning.

I see.  Not sure it would be very useful: the issue is not "it's only
used here" but "it's only *available* here" (because of the
`require`).


        Stefan

Re: [nongnu] elpa/org-contrib eaef050f28: lisp/ox-bibtex.el (org-bibtex-goto-citation): Add missing require

[Ihor Radchenko]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I mean an opposite: if `declare-function' is called globally, but the
>> actual function is only called by a single function in the file, emit
>> warning.
>
> I see.  Not sure it would be very useful: the issue is not "it's only
> used here" but "it's only *available* here" (because of the
> `require`).

Does it mean that you would not recommend moving declare-function inside
function if that function does not have require?

-- 
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: [nongnu] elpa/org-contrib eaef050f28: lisp/ox-bibtex.el (org-bibtex-goto-citation): Add missing require

[Stefan Monnier]

Ihor Radchenko [2024-01-30 22:11:14] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>>> I mean an opposite: if `declare-function' is called globally, but the
>>> actual function is only called by a single function in the file, emit
>>> warning.
>> I see.  Not sure it would be very useful: the issue is not "it's only
>> used here" but "it's only *available* here" (because of the
>> `require`).
> Does it mean that you would not recommend moving declare-function inside
> function if that function does not have require?

The `declare-function` tells the compiler "trust me, this function will
exist by the time we reach this point in the code".

Often as a programmer, what makes me confident to say such a thing is
that I just did a `require`, but not always.

Other times it's because I'm within a function which is placed on a hook
called by that other package, so even though I'm not explicitly loading
that package, I know that *if* the function is run, then presumably the
package is loaded.

Other times it's because I'm within a conditional branch that
corresponds to a particular version of Emacs (or some dependency) which
tells me that that function should be defined.

Yet other times, it's because I know the whole file will not be
used/usable without such and such other package, yet I can't `require`
that other package (e.g. because I don't want it as a hard dependency,
or to avoid a circular dependency, ...).

The pace where to put it depends on the specifics of the case.


        Stefan

Re: [nongnu] elpa/org-contrib eaef050f28: lisp/ox-bibtex.el (org-bibtex-goto-citation): Add missing require

[Emanuel Berg]

Stefan Monnier wrote:

>> Does it mean that you would not recommend moving
>> declare-function inside function if that function does not
>> have require?
>
> The `declare-function` tells the compiler "trust me, this
> function will exist by the time we reach this point in the
> code".
>
> Often as a programmer, what makes me confident to say such
> a thing is that I just did a `require`, but not always [...]

If you have a lexical let-closure (a `let' or `let*' at
top-level and a `defun' within it) and byte-compile the file,
the byte-compiler will warn the function isn't known to be
defined it it is refered to in the code. So after the defun
one can use `declare-function', either inside the closure or
after it.

I have mentioned it a couple of times so I know it is
well-known, and probably a bug or area of possible improvement
in the byte-compiler.

-- 
underground experts united
https://dataswamp.org/~incal