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.