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

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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 10 Dec 2022 03:57:02 -0800
> Cc: Eli Zaretskii <eliz@gnu.org>, John Wiegley <johnw@newartisans.com>
> 
> > +@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)

Yes, I get that.  I'm saying that we should perhaps use "library" more
and "package" less, because "package" is basically a misnomer here.

> > +@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 one where there are two values, not one, I guess?

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

I think we should do the latter regardlessly.

Thanks.

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

[Stefan Monnier]

> The answer to your first question is yes: the macro-expansion of
>
>     (use-package foo)
>
> is just
>
>     (require 'foo nil nil)

BTW, I can't resist mentioning that `require`ing a file like that should
be extremely rarely needed in an init file.  There's a good reason for
that: by convention, the mere act of loading a file should not affect
Emacs behavior very much, if at all, so those `require` will usually
just slow down startup for no good reason.

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

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

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.

> 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

I think in most cases, neither of them are good choices.
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).

Also, the wording in that paragraph is weird:

    This example loads a package only when the @samp{foo} package
    is installed.

since users should rarely care about "loading" (since, as
mentioned earlier, this should have mostly no visible effect).
`use-package` should be about configuring packages, not about loading
them (the `;;;###autoload` cookies should take care of the loading part
already).

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


        Stefan

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

[Philip Kaludercic]

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

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

Is this possible without breaking the backwards compatibility?

It would also be nice to have user options like
'use-package-always-defer' enabled by default, but that will certainly
break a number of configurations.

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

[Stefan Monnier]

Philip Kaludercic [2022-12-10 16:30:54] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> 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.
> Is this possible without breaking the backwards compatibility?

Without a doubt.  Here in Emacs we have almost 40 years of experience of
evolving things while preserving (some) backward compatibility.

> It would also be nice to have user options like
> 'use-package-always-defer' enabled by default, but that will certainly
> break a number of configurations.

Those users can always (setq use-package-always-defer nil) to recover
the old behavior.


        Stefan

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.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I'm saying that we should perhaps use "library" more and "package"
> less, because "package" is basically a misnomer here.

Right, then I understand what you're saying.  The problem here is that
"use-package" basically tries to hide away (or abstract, if you prefer)
the fact that packages and libraries are not the same thing.  Which
happens to work well 99 % of the time, but is also not a massive hurdle
for the final 1 %.  It is somewhat confusing, however, perhaps even more
so if you know the full story.

That said, I very much agree that we should try to be more precise when
possible.  Perhaps changing out "package" for "library" in several
places would be a good way to make things more clear.

>> 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 one where there are two values, not one, I guess?

The examples we have are:

    :if (eq system-type 'gnu/linux)

and

    :if (memq window-system '(ns x))

Do you mean that the `window-system' one is the more useful one?

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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 10 Dec 2022 12:34:20 -0800
> Cc: emacs-devel@gnu.org, johnw@newartisans.com
> 
> >> 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 one where there are two values, not one, I guess?
> 
> The examples we have are:
> 
>     :if (eq system-type 'gnu/linux)
> 
> and
> 
>     :if (memq window-system '(ns x))
> 
> Do you mean that the `window-system' one is the more useful one?

Yes, because the other one is just a special case.

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org,  Eli Zaretskii <eliz@gnu.org>,  John Wiegley
>  <johnw@newartisans.com>
> Date: Sat, 10 Dec 2022 17:01:13 -0500
> 
> >> 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.

But please don't ignore the use case of someone installing packages
manually, or from places that don't support package.el's methods.  It
could be just a bunch of Lisp under site-lisp.  For example, some
programs come with Emacs interface packages that they install under
site-lisp; examples include ID Utils, Guile, etc.

IOW, package.el doesn't solve all the aspects of managing unbundled
Lisp libraries for Emacs.

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

[Stefan Monnier]

>> >> 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 one where there are two values, not one, I guess?
>> 
>> The examples we have are:
>> 
>>     :if (eq system-type 'gnu/linux)
>> 
>> and
>> 
>>     :if (memq window-system '(ns x))
>> 
>> Do you mean that the `window-system' one is the more useful one?
>
> Yes, because the other one is just a special case.

OTOH testing `window-system` in the init file is not a good idea.
It will fail to do what is expected when used in `early-init.el`, and
similarly when used with the daemon.
So we probably shouldn't promote the practice in our examples.


        Stefan

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

[John Yates]

I am responding solely to this thread's subject, not to any
recent detailed points.

I have employed a use-package since my most recent emacs
bankruptcy five or so years back.  Early on I struggled
to come up with an appropriate ordering of keywords.
Clearly many are purely declarative.  But some result
in declarations and/or executable code.

Hence this use-package comment in my .init file:

;; Order insensitive metadata (neither introduces nor references any
symbols, nor executes any code):
;; :disabled         - turn off a troublesome or currently unused package
;; :straight         -
;; :pin              - pin the package to an archive
;; :ensure           - causes package(s) to be installed automatically
if not already present on your system
;; :defer            - suppress non-auto-deferred loading if you know
that another package will load this one
;; :demand           - prevent automatic deferred loading
;; :no-require       - inhibit loading package at compile time (e.g.
just need eval-after-load functionality)
;; :requires         - suppress if feature(s) not available at time of
use-package decl (= :if (featurep 'foo))
;; :load             - :load keyword overrides :no-require
;; :after            - delay loading until (:all PKG...) (default) or
(:any PKG...) are loaded
;; :catch            - override use-package-expand-minimally
;; :blackout         -
;; :diminish         - support for diminish.el (if installed).
;; :delight          - support for delight.el (if installed)
;;
;; Order sensitive (may introduce, reference or modify symbols, and/or
may execute code):
;; :load-path        - append to load-path before loading; relative
paths are expanded within user-emacs-directory
;; :defines          - introduce dummy variable declarations solely
for the sake of the byte-compiler
;; :functions        - introduce dummy function declarations solely
for the sake of the byte-compiler
;; :preface          - definition to silence byte-compiler and to be
used in :if tests
;; :if :when :unless - predicate initialization and loading
;; :custom           - custom-set or set-default each variable
definition; does not modify custom-file
;; :custom-face      - customize-set-faces each face definition; does
not modify custom-file
;; :general          - is this correct?
;; :bind(*)          - ( ( <global-key> . <command> )... :map
<package-local-map> ( <local-key> . <command> )... )
;;                     * = overriding all minor mode bindings
;; :bind-keymap(*)   - ( <package-prefix-key> . <map-in-package> )
;;                     * = overriding all minor mode bindings
;; :interpreter      - extend interpreter-mode-alist; use cons if
package name does not end with -mode
;; :mode             - extend auto-mode-alist; use cons if package
name does not end with -mode
;; :magic            - extend magic-mode-alist; use cons if package
name does not end with -mode
;; :magic-fallback   - extend magic-fallback-mode-alist; use cons if
package name does not end with -mode
;; :hook             - see
https://github.com/jwiegley/use-package/blob/master/README.md#hooks
;; :commands         - creates autoloads and defers loading of the
module until commands are used
;; :init             - code executed unconditionally before package is
loaded (and even when not loaded)
;; :config           - execute code after a package is loaded (perhaps
lazily); could even be a use-package form
;; :hydra            -

Since, at least in my theory, the keywords in the first
grouping are order-insensitive, I list them in the order
that I choose to have them appear in my use-package forms.

I am sure that my  comment includes errors.  Thus I would
love to see something similar but more authoritative in
the new manual.

/john

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

[Stefan Kangas]

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

> OTOH testing `window-system` in the init file is not a good idea.
> It will fail to do what is expected when used in `early-init.el`, and
> similarly when used with the daemon.
> So we probably shouldn't promote the practice in our examples.

Right.  So `system-type' it is, then?

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

[Stefan Kangas]

John Yates <john@yates-sheets.org> writes:

> I have employed a use-package since my most recent emacs
> bankruptcy five or so years back.  Early on I struggled
> to come up with an appropriate ordering of keywords.
> Clearly many are purely declarative.  But some result
> in declarations and/or executable code.
>
> Hence this use-package comment in my .init file:
>
> ;; Order insensitive metadata (neither introduces nor references any
> symbols, nor executes any code):
[...]
> ;; Order sensitive (may introduce, reference or modify symbols, and/or
> may execute code):

What do you mean by "ordering of keywords"?  AFAIU, keywords are
processed in the order they appear in `use-package-keywords'.

I'm not sure why `use-package-keywords' is a defcustom though.  It
should only ever be changed by people implementing new keywords, and not
by users, IIUC.

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

[John Wiegley]

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

>> It would also be nice to have user options like
>> 'use-package-always-defer' enabled by default, but that will certainly
>> break a number of configurations.

> Those users can always (setq use-package-always-defer nil) to recover the
> old behavior.

This should *not* be enabled by default.

Basically, `:demand` and `:defer` are considered overrides, which basically
short-circuit the intelligent in use-package that figures out when a deferred
load would offer the most benefit. The `-always-` variables cause these
overrides to be applied globally, but this is almost always a bad choice,
since it means giving up one of the reasons why use-package exists in the
first place: to figure out when things should be deferred, but not deferring
them when it's unhelpful.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

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

[Philip Kaludercic]

John Wiegley <johnw@newartisans.com> writes:

>>>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>>> It would also be nice to have user options like
>>> 'use-package-always-defer' enabled by default, but that will certainly
>>> break a number of configurations.
>
>> Those users can always (setq use-package-always-defer nil) to
>> recover the
>> old behavior.
>
> This should *not* be enabled by default.
>
> Basically, `:demand` and `:defer` are considered overrides, which
> basically short-circuit the intelligent in use-package that figures
> out when a deferred load would offer the most benefit. The `-always-`
> variables cause these overrides to be applied globally, but this is
> almost always a bad choice, since it means giving up one of the
> reasons why use-package exists in the first place: to figure out when
> things should be deferred, but not deferring them when it's unhelpful.

Most configurations I see online do use `use-package-always-defer' by
setting it to t, so it might be worth considering what use-package was
meant to do, and how it is being used.  It has been mentioned elsewhere
that use-package has a number of implicit assumptions that stem from
before the wide-spread usage of package.el and reliable autoloads.
Or at least that is how I make sense of keywords like :mode, :magit,
:interpreter, etc. which almost all package should set on their own (and
if they don't, they should.  It doesn't make sense to make every user
configure these things manually when it is well known that ".foo" is the
conventional file extension of foo-mode).

(It is by relying on the above assumptions that setup.el is under 800
lines long, without size ever having had been a priority (including
documentation and docstrings).)

I think it would be nice to see some space for use-package to evolve
along with the changing circumstances, requirements and expectations,
especially given how it is part of the core now, so the audience will
only grow.