Re: Adding use-package to core

[Philip Kaludercic]

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:

txt2NmgyPjLID.txt
Description: Text document

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