Re: emacs-29 acd462b0306: ; Improve the use-package manual

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> branch: emacs-29
> commit acd462b0306ead1b47278e810e11a3d66e4dd2cc
> Author: Eli Zaretskii <eliz@gnu.org>
> Commit: Eli Zaretskii <eliz@gnu.org>
>
>     ; Improve the use-package manual

Thanks, these changes were all for the better.

> +@c So, confusingly, (use-package foo) actually means to use the
> +@c _library_ foo.el, not all of the _package_ foo's libraries?
> +@c Should this be explicitly explained here?
>  Note that a ``package'' is different from an Emacs Lisp ``library''.
>  The above declaration tells use-package to load the @emph{library}
> -@file{foo.el}, which the overwhelming majority of cases also resides
> -in a @emph{package} named @code{foo}.  But the @code{foo} package
> -might also contain a library named @file{foo-extra.el}.  If that
> -library is not loaded automatically, you will need a separate
> -@code{use-package} declaration to make sure that it is.  This manual
> -will often use these terms interchangeably, as this distinction does
> -not usually matter, but you should keep it in mind for the cases when
> -it does.
> +@file{foo.el}, which in the overwhelming majority of cases also
> +resides in a @emph{package} named @code{foo}.  But the package
> +@code{foo} might also contain a library named @file{foo-extra.el}.  If
> +that library is not loaded automatically, you will need a separate
> +@code{use-package} declaration to make sure that it is loaded when
> +needed.  This manual will often use the terms ``package'' and
> +``library'' interchangeably, as this distinction does not usually
> +matter, but you should keep it in mind for the cases when it does.

The answer to your first question is yes: the macro-expansion of

    (use-package foo)

is just

    (require 'foo nil nil)

But this can be somewhat confusing to users because the declaration:

    (use-package foo :ensure t)

Will macro expand to something that basically amounts to:

    (unless (package-installed-p 'foo)
      (package-install 'foo))
    (require 'foo nil nil)

This can be worked around with

    (use-package foo :ensure foo-package)

Which would expand to something like:

    (unless (package-installed-p 'foo-package)
      (package-install 'foo-package))
    (require 'foo nil nil)

I think this is a good choice in practice (that is, I can't think of a
better one), as the package name and the library to require is the same
in the vast majority of cases.  There are some exceptions, of course,
but they are pretty rare.  For example, I have no such packages in my
init file and I have 100+ packages installed.

However, it does risk causing some confusion about the precise meaning
of "(use-package foo)".  The old documentation didn't really say
anything about this point, and my attempt to explain it is quoted above.

There is also an attempt to explain it in the section on :ensure.

> +@c FIXME: Too many redundant examples?  E.g., why do we need both an
> +@c example for system-type and window-system? or both of the last 2
> +@c examples?

I think we can drop either the window-system example or the system-type
example.  But I don't know which one is more useful.

The last two examples, using package-installed-p and locate-library, are
more important to keep, as users have reported issues specifically
related to not knowing what the difference is between them, for example:

    https://github.com/jwiegley/use-package/issues/693

Alternatively, we could perhaps consider changing the docstring of
`package-installed-p' to just let people know of `locate-library' (and
maybe even when to use it).