use-package has been merged into emacs-29

use-package has been merged into emacs-29

[Stefan Kangas]

Hi Emacs,

Just to make this official: use-package has now landed on the emacs-29
branch.  This means, barring any major world disasters, solar storms, or
similar, use-package will officially be a part of Emacs 29.

I completed the final steps of the merge and rewrote the user manual.
However, the main credit naturally belongs to use-package's principal
author John Wiegley.

It's also worth highlighting the numerous contributors from the user
community writing patches, bug reports and documentation over the years.
These are the top 15 contributors (number of commits on the left):

    $ git shortlog -a -s -n | head -15
       615  John Wiegley
        37  Noam Postavsky
        34  Jonas Bernoulli
        26  Radon Rosborough
        22  Stefan Kangas
        17  Justin Talbott
        15  Phillip Lord
        11  Adam Spiers
        11  Damien Cassou
        11  Kaushal Modi
        10  Alex Branham
        10  Jimmy Yuen Ho Wong
         9  Ted Zlatanov
         8  Nicolas Richard
         8  Payas Relekar

Thanks also to Payas Relekar, without whose insistent posts to
emacs-devel, this merge would have never happened in time for Emacs 29.
Together with João Távora he also provided the substantial portion of
the merge scripts, which saved me a lot of typing.

Thanks all, and congratulations Emacs!

Re: use-package has been merged into emacs-29

[John Wiegley]

>>>>> Stefan Kangas <stefankangas@gmail.com> writes:

> Just to make this official: use-package has now landed on the emacs-29
> branch.  This means, barring any major world disasters, solar storms, or
> similar, use-package will officially be a part of Emacs 29.

> I completed the final steps of the merge and rewrote the user manual.

Fantastic news!! Thank you so much to Stefan and Payas and everyone else who
helped push this over the line. :)

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

Re: use-package has been merged into emacs-29

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

> Hi Emacs,
>
> Just to make this official: use-package has now landed on the emacs-29
> branch.  This means, barring any major world disasters, solar storms, or
> similar, use-package will officially be a part of Emacs 29.

Great!

A few comments on use-package.texi from briefly skimming the file:

- It appears to be mentioning a few packages that are not available on
  GNU ELPA or NonGNU ELPA (e.g. git-gutter+, eruby-mode, dash-at-point,
  ess, color-moccur, moccur-edit, unfill).  Should they be replaced
  with other packages to make sure the examples are consistently
  reproducible?

- Why is "Debian GNU/Linux" formatted using @code?

- Under the node "Byte-compiling", is the "@end group" in the
  "use-package ruby-mode" block intended to be placed where it is?

- Is "NonGNU" an acronym itself?

- Some packages are formatted as @file's (hydra, ivy, diminish, delight,
  ...).  Does this really make sense?

- MELPA is mention under vindex `use-package-always-pin', is this ok.
  AFAIR there was some decision to not mention MELPA in the official
  documentation (currently this also appears to be the only instance).

- Under "Modes and interpreters", the file extension .rb is formatted
  using @samp, while (texinfo) @file implies that @file is the right
  macro for this situation.

- It appears that use-package is sometimes formatted using @code and
  sometimes not.  I can't make out a consistent rule.

- GNU ELPA is also inconsistently marked up as a single or two separate
  acronyms.

- There is still an instance of "see @ref" under the node "Global
  keybindings".

Re: use-package has been merged into emacs-29

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org,  John Wiegley <johnw@gnu.org>
> Date: Fri, 09 Dec 2022 16:09:24 +0000
> 
> - There is still an instance of "see @ref" under the node "Global
>   keybindings".

What is the problem with "see @ref"?

Re: use-package has been merged into emacs-29

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org,  John Wiegley <johnw@gnu.org>
>> Date: Fri, 09 Dec 2022 16:09:24 +0000
>> 
>> - There is still an instance of "see @ref" under the node "Global
>>   keybindings".
>
> What is the problem with "see @ref"?

If you are asking, I am assuming I am wrong.  My assumption was that
@pxref was preferable.

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org,  John Wiegley <johnw@gnu.org>
>> Date: Fri, 09 Dec 2022 16:09:24 +0000
>> 
>> A few comments on use-package.texi from briefly skimming the file:
>
> Thanks, but there's no need to post such comments: just go ahead and
> fix what needs to be fixed.  People who work on these changes are not
> angels: we make mistakes, and appreciate when others silently fix them
> when they spot them.

I am sorry if my comments had a negative tone -- I am certainly no
texinfo expert, so I'd rather discuss the questions before applying any
changes.

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org,  John Wiegley <johnw@gnu.org>
>> Date: Fri, 09 Dec 2022 16:09:24 +0000
>> 
>> - Some packages are formatted as @file's (hydra, ivy, diminish, delight,
>>   ...).  Does this really make sense?
>
> A package is usually a file, so @file is correct.  But sometimes the
> context is talking about a feature, and then @code or @samp is better.

I have also noticed there are a few instances of @file{<...>.el} vs
@file{<...>}.  Perhaps it makes sense to use @file when referring to the
packages as file names, and @code/@samp when referring to the package
name (if at all -- just like with my question whether use-package should
be formatted or not).

Re: use-package has been merged into emacs-29

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: stefankangas@gmail.com,  emacs-devel@gnu.org,  johnw@gnu.org
> Date: Fri, 09 Dec 2022 17:06:02 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > What is the problem with "see @ref"?
> 
> If you are asking, I am assuming I am wrong.  My assumption was that
> @pxref was preferable.

It is preferable when the cross-reference ends in a closing
parenthesis.  The case you are referring to has more text after the
cross-reference and before the closing parenthesis, right?

> > Thanks, but there's no need to post such comments: just go ahead and
> > fix what needs to be fixed.  People who work on these changes are not
> > angels: we make mistakes, and appreciate when others silently fix them
> > when they spot them.
> 
> I am sorry if my comments had a negative tone -- I am certainly no
> texinfo expert, so I'd rather discuss the questions before applying any
> changes.

You can consider yourself an expert, since you've uncovered the
problems and inconsistencies.

> >> - Some packages are formatted as @file's (hydra, ivy, diminish, delight,
> >>   ...).  Does this really make sense?
> >
> > A package is usually a file, so @file is correct.  But sometimes the
> > context is talking about a feature, and then @code or @samp is better.
> 
> I have also noticed there are a few instances of @file{<...>.el} vs
> @file{<...>}.  Perhaps it makes sense to use @file when referring to the
> packages as file names, and @code/@samp when referring to the package
> name (if at all -- just like with my question whether use-package should
> be formatted or not).

That was more or less what I tried to do.  But maybe I missed a few
places -- it's a large manual.

Re: use-package has been merged into emacs-29

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org,  John Wiegley <johnw@gnu.org>
> Date: Fri, 09 Dec 2022 16:09:24 +0000
> 
> A few comments on use-package.texi from briefly skimming the file:

Thanks, but there's no need to post such comments: just go ahead and
fix what needs to be fixed.  People who work on these changes are not
angels: we make mistakes, and appreciate when others silently fix them
when they spot them.

Re: use-package has been merged into emacs-29

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org,  John Wiegley <johnw@gnu.org>
> Date: Fri, 09 Dec 2022 16:09:24 +0000
> 
> - Some packages are formatted as @file's (hydra, ivy, diminish, delight,
>   ...).  Does this really make sense?

A package is usually a file, so @file is correct.  But sometimes the
context is talking about a feature, and then @code or @samp is better.

Re: use-package has been merged into emacs-29

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> - It appears to be mentioning a few packages that are not available on
>   GNU ELPA or NonGNU ELPA (e.g. git-gutter+, eruby-mode, dash-at-point,
>   ess, color-moccur, moccur-edit, unfill).  Should they be replaced
>   with other packages to make sure the examples are consistently
>   reproducible?

Yup.  All examples like that come from the old README.md.  I got rid of
most of them, but there are several left to fix.

I think we should replace them with either some made up package name
(e.g. "foo" or "some-package") or, in order of preference: built-in, GNU
ELPA, NonGNU ELPA.

IMO, replacing NonGNU ELPA with GNU ELPA packages is usually an
improvement, and so is replacing GNU ELPA packages with built-in ones.

> - MELPA is mention under vindex `use-package-always-pin', is this ok.
>   AFAIR there was some decision to not mention MELPA in the official
>   documentation (currently this also appears to be the only instance).

It's only mentioned to explain how to work around its date-based
versioning scheme (by always installing packages from NonGNU ELPA
instead).  Which I think should be fine.

> - It appears that use-package is sometimes formatted using @code and
>   sometimes not.  I can't make out a consistent rule.

I've tried to follow this:

- Format use-package with no markup when referring to the package.
- Use @code{use-package} when referring to a macro call.

Does that make sense?

> - GNU ELPA is also inconsistently marked up as a single or two separate
>   acronyms.

In one sense, @acronym{GNU ELPA} is better, as that is the full name.
One way of looking at it is that the acronym for "GNU Emacs Lisp Package
Archive" is actually the acronym "GNUELPA", which we just happen to
typeset with a space for increased legibility.

But we also have @acronym{NonGNU ELPA}, and I guess we are now looking
at just a name that is not really an acronym at all?  So perhaps we
should just write out the names GNU ELPA and NonGNU ELPA without any
markup?  Because we also don't want "@acronym{NonGNU} @acronym{ELPA}", I
suppose?

Re: use-package has been merged into emacs-29

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 10 Dec 2022 12:34:03 -0800
> Cc: emacs-devel@gnu.org, John Wiegley <johnw@gnu.org>
> 
> In one sense, @acronym{GNU ELPA} is better, as that is the full name.
> One way of looking at it is that the acronym for "GNU Emacs Lisp Package
> Archive" is actually the acronym "GNUELPA", which we just happen to
> typeset with a space for increased legibility.

Please don't make @acronym have more than one word.  I tried to fix
those cases, but maybe I missed some.  It should be "@acronym{GNU}
@acronym{ELPA}" instead.

> But we also have @acronym{NonGNU ELPA}, and I guess we are now looking
> at just a name that is not really an acronym at all?  So perhaps we
> should just write out the names GNU ELPA and NonGNU ELPA without any
> markup?  Because we also don't want "@acronym{NonGNU} @acronym{ELPA}", I
> suppose?

It should be "NonGNU @acronym{ELPA}", I think.

Re: use-package has been merged into emacs-29

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Please don't make @acronym have more than one word.  I tried to fix
> those cases, but maybe I missed some.  It should be "@acronym{GNU}
> @acronym{ELPA}" instead.

(There's also @sc, if @acronym is too jarring.)

>> But we also have @acronym{NonGNU ELPA}, and I guess we are now looking
>> at just a name that is not really an acronym at all?  So perhaps we
>> should just write out the names GNU ELPA and NonGNU ELPA without any
>> markup?  Because we also don't want "@acronym{NonGNU} @acronym{ELPA}", I
>> suppose?
>
> It should be "NonGNU @acronym{ELPA}", I think.

Then half the name will be in smallcaps and the other one won't be,
right?  Doesn't that seem a bit unusual?

My preference here would probably be to just use the names with no
markup, just as we do with e.g. GNU/Linux.  We do that even if the first
half of that name is an acronym.  Would that work?

Re: use-package has been merged into emacs-29

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sun, 11 Dec 2022 17:19:35 -0800
> Cc: philipk@posteo.net, emacs-devel@gnu.org, johnw@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Please don't make @acronym have more than one word.  I tried to fix
> > those cases, but maybe I missed some.  It should be "@acronym{GNU}
> > @acronym{ELPA}" instead.
> 
> (There's also @sc, if @acronym is too jarring.)

Yes, but that'd have to be applied consistently.

> > It should be "NonGNU @acronym{ELPA}", I think.
> 
> Then half the name will be in smallcaps and the other one won't be,
> right?  Doesn't that seem a bit unusual?

@acronym doesn't produce small caps.

Re: use-package has been merged into emacs-29

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > (There's also @sc, if @acronym is too jarring.)
>
> Yes, but that'd have to be applied consistently.

Agreed.  The most important thing is to be consistent.

> > > It should be "NonGNU @acronym{ELPA}", I think.
> >
> > Then half the name will be in smallcaps and the other one won't be,
> > right?  Doesn't that seem a bit unusual?
>
> @acronym doesn't produce small caps.

Sorry, you're right.  The docs says that "the acronym is printed in
slightly smaller font" (in TeX).

Re: use-package has been merged into emacs-29

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

>> - It appears that use-package is sometimes formatted using @code and
>>   sometimes not.  I can't make out a consistent rule.
>
> I've tried to follow this:
>
> - Format use-package with no markup when referring to the package.
> - Use @code{use-package} when referring to a macro call.
>
> Does that make sense?

That does make sense, but I believe to have had found instances where
this was not the case.  I'll try and see if I can locate those again.

Also, this ties into the other point about the usage of @file.
Shouldn't the first case be wrapped in @file?

Re: use-package has been merged into emacs-29

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> That does make sense, but I believe to have had found instances where
> this was not the case.  I'll try and see if I can locate those again.

That will be appreciated, thanks.

> Also, this ties into the other point about the usage of @file.
> Shouldn't the first case be wrapped in @file?

I don't think we do that elsewhere, do we?  See e.g. eshell.texi or
eglot.texi.

My understanding is that it's "use-package" when referring to the
package as a whole, "@file{use-package}" when referring to the library
(i.e. use-package.el), and "@code{use-package}" when referring to the
macro by that name.

Re: use-package has been merged into emacs-29

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> That does make sense, but I believe to have had found instances where
>> this was not the case.  I'll try and see if I can locate those again.
>
> That will be appreciated, thanks.

I have taken a look again, and it appears I was mistaken.  That being
said, there are still a few places where I think it is not clear if
talking about the macro or the package would be correct.  E.g. compare
these two excerpts that refer to use package and a keyword:

                                                  With use-package, you
  can simplify this using the @code{:bind} keyword, as described in this
  section.

and

  @code{use-package} supports this with a @code{:map} modifier,
  taking the local keymap to bind to:

Both readings make sense, but the manual is talking about two different
things (to be fair: with a major overlap).

>> Also, this ties into the other point about the usage of @file.
>> Shouldn't the first case be wrapped in @file?
>
> I don't think we do that elsewhere, do we?  See e.g. eshell.texi or
> eglot.texi.
>
> My understanding is that it's "use-package" when referring to the
> package as a whole, "@file{use-package}" when referring to the library
> (i.e. use-package.el), and "@code{use-package}" when referring to the
> macro by that name.

Nevermind this, I see that there is only a single instance of
"@file{use-package}" left now, and it makes sense (it refers to the file
being loaded).

Re: use-package has been merged into emacs-29

[Payas Relekar]

Stefan Kangas <stefankangas@gmail.com> writes:

> Just to make this official: use-package has now landed on the emacs-29
> branch.  This means, barring any major world disasters, solar storms, or
> similar, use-package will officially be a part of Emacs 29.

Great news!

> I completed the final steps of the merge and rewrote the user manual.
> However, the main credit naturally belongs to use-package's principal
> author John Wiegley.

+1

> Thanks also to Payas Relekar, without whose insistent posts to
> emacs-devel, this merge would have never happened in time for Emacs 29.
> Together with João Távora he also provided the substantial portion of
> the merge scripts, which saved me a lot of typing.

You sir, are too kind :)
Thank you for doing the heavy work, and in time too!

> Thanks all, and congratulations Emacs!

Thanks,
Payas
--