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

[Stefan Kangas]

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

> BTW, I can't resist mentioning that `require`ing a file like that should
> be extremely rarely needed in an init file.

I agree, and I've therefore tried to make sure that the manual
discourages `require' as much as possible.  (If I did a sufficiently
good job is another question.)

> 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.  Is it true that some of the
other package managers don't setup autoloads, or do they all do that?

> (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?  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?

> It would be nice to try and evolve `use-package` towards a default
> behavior that's more aligned with current best practices rather than
> what was done back when installing a package meant reading the
> "Commentary:" section and copying a chunk of ELisp code into your
> init file.

I couldn't agree more.

> 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.

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.  Most users will
presumably not be doing that anyways, these days (and those that do will
be able to find it in that chapter).

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'.

IOW, I think it's worth making the documentation even more
package.el-oriented, which incidentally should be possible while also
improving the documentation for non-package.el users (by moving
everything they need to know to one place).  That way everybody wins, I
think.

>> 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.

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.

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.)

PS. All in all, some very interesting points here.  Thanks.