Re: Adding use-package to core

[Philip Kaludercic <philipk@posteo.net>]

[-- Attachment #1: Type: text/plain, Size: 3430 bytes --]

Stefan Kangas <stefankangas@gmail.com> writes:

> Payas Relekar <relekarpayas@gmail.com> writes:
>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>>>> 1. Get use-package in ELPA
>>>>> 2. Complete all documentation
>>>>> 3. Prepare documentation in texinfo
>>>>>    Will cross that bridge when 2 is done.
>>>
>>> While we are at it, is there a rationale for this order?  I mean, there
>>> is no hurry, right? My misunderstanding was that the order was 2 -> 3 ->
>>> 1.  Or are you planning to have use-package ready for Emacs 29?
>>
>> If you mean merging use-package into emacs.git, that will definitely not
>> be happening (at least if I'm the only one working on it).
> [...]
>> From my understanding, ELPA has less stringent requirements for
>> documentation and testing compared to core. Since I cannot commit enough
>> time to complete all the tasks before expected 29 branch-off, ELPA is a
>> good compromise IMO.
>
> OK, I'll bite.  I have time to dedicate to this task; perhaps we can
> move quickly enough for Emacs 29.  Ultimately, the decision will be with
> the maintainers, but it seems to me that use-package.el itself is in
> shape for inclusion.

That would certainly be great1

> Could you write up a summary of what needs doing before we can add
> use-package to emacs.git?  Is it just a matter of writing up some more
> documentation, or is there more that needs doing?

Payas and I can up with the following list

  1. Get use-package in ELPA
  2. Complete all documentation
  3. Prepare documentation in texinfo
     Will cross that bridge when 2 is done.
  4. Add all relevant files to emacs.git
     TBD when 3 is done.
  5. Ensure everything loads properly

The first point has been done, but hasn't been finalised.  The most
tricky part IMO right now is to complete the .texi documentation.  Take
a look at

https://raw.githubusercontent.com/jwiegley/use-package/master/use-package.texi

I have previously commented on what has do be done here
(<87o7v37sqh.fsf@posteo.net>, <871qqhby2k.fsf@posteo.net>):

    Take a look at use-package.texi in the use-package repository.  There
    are currently two TODO that ought to be addressed.  And as the file is
    generated, the texinfo markup is probably not as idiomatic as it ought
    to be.  There are at least a few instances where @code is used instead
    of @kbd, @key or @var.  @ref where @xref/@pxref might be better.  Content-wise
    a few sections such as how to install the package will be outdated, and
    I'd rephrase the sections that mention MELPA to use ELPA examples.  I
    also notice that the spacing is inconsistent, and one should try to keep
    ensure that each full stop is followed by two spaces.

My worry here are the TODO sections -- they either have to be removed or
expanded:

--8<---------------cut here---------------start------------->8---
@node Getting Started
@chapter Getting Started

TODO@. For now, see @code{README.md}.
--8<---------------cut here---------------end--------------->8---

If the manual is pointing to the README, we might just have to convert
the Markdown document to Texi and clean it up.  My hunch is that the
README isn't written like a good manual, so it won't be that easy.

... On the other hand, if this TODO really just wants the "Getting
Started" section from the README, this should be trivial.  All one would
need is to clean up the following that I quickly converted using Pandoc:


[-- Attachment #2: Type: text/plain, Size: 1918 bytes --]

Here is the simplest @code{use-package} declaration:

@verbatim
;; This is only needed once, near the top of the file
(eval-when-compile
  ;; Following line is not needed if use-package.el is in ~/.emacs.d
  (add-to-list 'load-path "<path where use-package is installed>")
  (require 'use-package))

(use-package foo)
@end verbatim

This loads in the package @code{foo}, but only if @code{foo} is
available on your system. If not, a warning is logged to the
@code{*Messages*} buffer.

Use the @code{:init} keyword to execute code before a package is loaded.
It accepts one or more forms, up to the next keyword:

@verbatim
(use-package foo
  :init
  (setq foo-variable t))
@end verbatim

Similarly, @code{:config} can be used to execute code after a package is
loaded. In cases where loading is done lazily (see more about
autoloading below), this execution is deferred until after the autoload
occurs:

@verbatim
(use-package foo
  :init
  (setq foo-variable t)
  :config
  (foo-mode 1))
@end verbatim

As you might expect, you can use @code{:init} and @code{:config}
together:

@verbatim
(use-package color-moccur
  :commands (isearch-moccur isearch-all)
  :bind (("M-s O" . moccur)
         :map isearch-mode-map
         ("M-o" . isearch-moccur)
         ("M-O" . isearch-moccur-all))
  :init
  (setq isearch-lazy-highlight t)
  :config
  (use-package moccur-edit))
@end verbatim

In this case, I want to autoload the commands @code{isearch-moccur} and
@code{isearch-all} from @code{color-moccur.el}, and bind keys both at
the global level and within the @code{isearch-mode-map} (see next
section). When the package is actually loaded (by using one of these
commands), @code{moccur-edit} is also loaded, to allow editing of the
@code{moccur} buffer.

If you autoload no-interactive function, please use @code{:autoload}.

@verbatim
(use-package org-crypt
  :autoload org-crypt-use-before-save-magic)
@end verbatim

[-- Attachment #3: Type: text/plain, Size: 663 bytes --]


--8<---------------cut here---------------start------------->8---
@node Debugging Tools
@chapter Debugging Tools

TODO
--8<---------------cut here---------------end--------------->8---

This is a more technical topic that probably has to be written by
someone who is knowledgeable with the internals and implementation
details of use-package.  Either we find someone like that -- who has
time -- or the chapter is removed for now.

>> As for the order rationale, getting use-package to ELPA means less
>> friction and more users can try it out, more feedback, more eyeballs,
>> basically.
>
> If we get it into core, we can make it into a :core package.

Right.