Re: Adding use-package to core

[Philip Kaludercic]

Stefan Kangas <stefankangas@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> 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.
>
> I didn't follow the discussion, but it seems like adding it to GNU ELPA
> is being worked on.  That is good.

Actually it is done, but I advised Payas to postpone it until the
documentation is ready, which makes the package more useful.  Even if
use-package isn't added in time for 29, working on the issue would still
be useful for the ELPA initiative.

> But I think one question remains, unless I missed some important part of
> the discussion (and please forgive me if I did):

(None of this was discussed, to my recollection)

> We need to figure out how development will proceed after adding it to
> emacs.git.  I see three options:
>
> 1. Development will continue as before, in the old repository and forge
>    (currently GitHub).  This case is different from Eglot, and AFAIU
>    more like cc-mode, org-mode (or previously Gnus):
>
>    - Development mainly takes place externally.
>    - When a new version of use-package is released, it is manually
>      synched (a.k.a. copied) to emacs.git and committed as basically
>      "new version".  [So to read the full git log, one would need to
>      clone use-package.git -- we don't preserve it.]
>    - Someone needs to be in charge of (presumably manually) synching
>      changes in emacs.git back to use-package.git.
>
> 2. Development moves to emacs.git wholesale, along the same lines as we
>    did with eglot.  This would take more work, and I guess collaboration
>    and active interest from John.
>
> 3. We wait until we can include GNU ELPA packages in the Emacs
>    distribution.  AFAIK, this is not actively worked on, and would in
>    practice mean that we just wait until someone steps up to volunteer
>    for that (i.e. we effectively do nothing, for now).
>
> On balance, the first option (1) seems to me the best one here, as
> use-package development is already quite established externally and it
> seems smart to leverage that existing community to our advantage.  The
> main advantage we are looking for here is to ship use-package with
> Emacs, and we already get that with option 1.

FWIW I agree, and think this has worked well enough for a number of
larger packages (another example are the Modus Themes).  It is sad that
the revision history is broken, but that is a limitation of Git IMO.

> Perhaps, in this case, it also doesn't make sense to make use-package
> into a :core package.  We would then just need to worry about synching
> the latest version of use-package to emacs.git before releasing a new
> version of Emacs.  We would not have to update it all the time just to
> get it released on GNU ELPA.

I cannot evaluate this, but isn't use-package a relatively stable
package, that is mostly being bug-fixed?  There really aren't that many
new features being added all the time, so this might not be that
important.  Or am I mistaken?

> I've CC:ed John in case he has anything to add.
>
>>     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.
>
> Agreed.
>
>> 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:
>
> I think we should be able to just use the section "Getting started" from
> README.md.  I think we can just comment out the sections
> "Issues/Requests" and "Debugging Tools" until they are actually written.

Someone has to make that choice, and I am fine if you are the one who
decides to do so.

> However, the documentation seems to be currently written in Org-mode,
> from where it is exported using Hugo[1] to a website:
>
>     https://jwiegley.github.io/use-package/getting-started/
>
> If it is important to continue doing that, I think we should work with
> the org-mode sources rather than the texinfo ones.  It would be useful
> if John could let us know if he has any preferences in this regard.

No, we have recently decided to scrap that documentation source in
favour of the documentation generated on elpa.gnu.org -- that is if I
understood everything correctly.

> As for the formatting issues in the org->texinfo conversion, I believe
> that Org-mode has largely solved them.  With some luck, it should be a
> small matter of imitating what they did.  In any case, it should be
> possible to find solutions and/or workarounds.

Really?  How does Org-mode distinguish between @key, @kbd, @code and
@var?

> So all in all, the documentation will take some work, but nothing too
> crazy.

If you think so, that is great.

> The harder job going forward will be keeping use-package.{org,texi}
> up-to-date with README.md, if that will continue to be an important
> source of documentation.  Perhaps README.md should be restricted in
> scope to make that job easier.

I think this is a good idea in general.  Long READMEs are easy to get
lost in.  If a file asks you to read it, then it should at the very
least be kind enough to keep it short and only focus on pointing you to
the relevant information, that would ideally be found somewhere else.