Re: Adding use-package to core

[Stefan Kangas]

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.

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

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.

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

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.

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.

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

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.

Footnotes:
[1]  https://gohugo.io/