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

[Stefan Monnier]

>> I think this part of `use-package` is a result of its having been
>> designed before things like `package.el` became common practice (the
>> main effect of which (in this respect) has been to make `;;;###autoload`
>> cookies usable in all packages without any extra work on the package's
>> author's side).
>
> Agreed.  Another thing is that `use-package' also tries hard to be
> package manager agnostic, and that also shows in places.  I wonder if
> that's somehow also connected to the above.

Im not sufficiently familiar with all the package managers out there,
but my impression is that it shouldn't make much difference in
this respect.

> Is it true that some of the other package managers don't setup
> autoloads, or do they all do that?

If so, I think it's a problem for them.

More specifically, I think setting up autoloads is part of "installing
a package" and not part of "customizing a package".

This difference is relevant when we need a "clean/vanilla setup"
(e.g. for compilation/flymake purposes) in which case we want
dependencies to be "fully installed" but not customized.

Historically, `use-package` has tended to conflate the two.

>> (A similar "old style" thingy is that (use-package foo-mode :mode
>> ".bar\\'") will setup an autoload for the `foo-mode` function, whereas
>> that autoload should have already been setup by the package's own
>> installation).
> I agree that it's usually redundant (or should be, at any rate), but it
> also doesn't hurt, does it?

It hurts in the sense that a subsequent `fboundp` may return non-nil
even though the package is actually not installed.

> IOW, I'm asking if you think it's necessary to do something about
> this, either in our code or documentation, wether in the short-term
> or medium?

I'm not sure what we should do in the short term, but I think we should
keep this in mind when writing the doc to try and encourage writing
`use-package` snippets which are "forward compatible" (e.g. don't
depend on whether the file gets `require`d, etc...) and to help the
users think with a clear distinction between what should be part of
installation and what should be part of customization (so they will
know when to report a bug for a missing autoload cookie instead of
cargo-culting a `use-package` snippet which works around the problem
giving the impression that Emacs is more difficult to use/customize
than it really is).

>> Instead better choices will usually look like `:if (fboundp '...)`
>> (which should be a lot faster than `locate-library` and doesn't care
>> how the package was installed).
> Ah, good point.  This is indeed the best solution for packages installed
> with package.el, but unfortunately not for manually installed packages.

Indeed, `use-package` is great for truly manually installed packages.
But these should be a very small minority nowadays, and we should (and
do) work towards making it even more rare (e.g. with things like
`package-vc`).

The doc should focus on the more common case where packages are properly
installed with some tool that already sets up the
maintainer-provided autoloads.

> I am now starting to lean towards setting up a section in the
> "Installing packages" chapter for manual package installations, and
> just moving all stuff relevant only to that there.

Sounds great!

> I am also very much starting to lean towards moving the explanations
> that should only affect users of third-party package managers to the
> info node `(use-package) Other package managers'.

I don't know enough about what those differences are to judge, so I'll
trust your judgment on that.

>>> 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).
>> This doesn't sound right since those two are only distantly related.
> Hmm, are they?  The latter seems like a more general version of the
> former to me, so I'm probably missing something.

`locate-library` is normally intended to tell you where a file is
along `load-path`.

`package-installed-p` tells you whether a package is installed, which
could even be true when the package is not activated (i.e. isn't in
`load-path`).

> People on the use-package issue tracker have asked if
> `package-installed-p' will only tell them about packages installed using
> package.el.  Because they use some other package manager that doesn't
> register packages in package.el (I guess), or they have just added some
> directories to load-path.

Indeed, `package-installed-p` is quite specific to `package.el`.

> Perhaps we should just say that those other package managers should be
> fixed to better integrate with package.el?  (Note that we already
> provide `use-package-ensure-function', but that only covers :ensure and
> not :if.)

To me testing `package-installed-p` is a bit like testing the Emacs
version instead of checking the actual thing you need: sometimes it's
the better choice, but usually it's not.


        Stefan