Use-package: Document `:defer-install` keyword

[Silex]

Both in the docstring and README.md

@raxod502: given you did most of the implementation, maybe you want to take a shot at this? I believe simply rewording the commit message of 53c70aff266fd3479ede22fbe275d09272e6bbae would work

[raxod502]

I'll get to it at some point. Thanks for pushing the issue; documentation is not a strong point of many of the current parts of use-package.

[Silex]

Yeah, I've opened around 3-4 of these tickets now. Whenever I encounter a undocumented keyword I make an issue, documentation is important, even if it is very minimalist.

To be honest I think that simply copying-adapting the commits messages or some parts of the discussion of the PR in the README and the docstring would take around 5 minutes and be sufficient...

I don't know why but a lot of people seem to think documentation has to be complicated and skip it instead of putting a somewhat decent one-liner explanation, which is often good enough and certainly better than nothing. :wink:

[Silex]

Heck, I don't even really know what :defer-install does, but would this guesstimate work?

defer-install: If true, installs the package only when necessary (when then package 
actually needs to be loaded). By default it is set to false. 
Also see variable `package-always-defer-install'.

package-always-defer-install: if set to true, make it so all `:ensure` package are
installed using `:defer-install`.

[thomasf]

I would probably prefer if all or most of the readme was moved into the docstring. It's annoying that all of the documentation isn't available from inside emacs..

Another solution could be to package the readme.md into the elpa package and add a use-package-readme function which just opens it in a read only buffer or something like that.

Sorry for going slightly off topic..

[Silex]

@thomasf: most packages uses the README for meaningful documentation. But sure, the docstring should also contain the basic explanations (e.g the keywords). I don't think it makes sense to show a lot of examples in the docstring (except maybe for the basic ones).

[thomasf]

yeah, info pages is the proper place for longer format documentation text inside of emacs so packaging the readme (less work) or converting it into info-format (better fit) would work as well.

I don't subscribe to the idea having lots of documetation in readme for any kind of project, it's much better if the readme just contain general description and project meta information and use a proper documentation system for the rest, there is usually a defacto standard for documentation for most languages or situations.

[thomasf]

Even if only a simple markdown format is used it's it's usually good to separate them into README, INSTALL, HACKING, USAGE, INSTALL or something like that in which case the USAGE one could be placed into the package.

Something like this:

.
├── docs
│   ├── hacking.md
│   ├── install.md
│   └── usage.md
└── README.md

If the documentation files structure looks like above http://www.mkdocs.org/ can be used inside a CI to generate a nice html based github pages as well.

[Silex]

Oh, yeah for sure what you suggest would be even better... but first things first :smile: First at least get everything somewhat documented, then think about organisation... tho maybe having a nice organisation would increase interest into documenting things. Mmmh.

[raxod502]

Oh, let me be clear, I feel just as strongly about documentation as you do. For instance, look at the docs for my project straight.el. The issue in this case is that I'm actually working on a replacement for use-package and therefore have issues related to use-package at a lower priority. But, I do promise to get to this.

By the way, that commit message you quoted was actually horribly out of date, since I later changed the approach. Sorry about that.

[alphapapa]

A thought: it seems to me that the UI would be clearer if :defer-install were replaced with something like :ensure defer, i.e.:

(use-package package
   :ensure defer)

While :ensure t might be better described as:

(use-package package
   :ensure immediate)

Although :ensure would probably be better named :install, so the examples would be like:

(use-package package
   :install defer)
(use-package package
   :install immediate)

That would be much less ambiguous, and documenting them would be much easier.

[raxod502]

I like how it looks. Unfortunately, I don't think that will work because we'd lose the ability to specify a custom package name:

(use-package tex-site
  :ensure auctex)

[alphapapa]

Well, I guess the non-package-name keywords could be quoted, i.e.

(use-package package
   :install :defer)
(use-package package
   :install :immediate)

Or if that seems too CL-like:

(use-package package
   :install 'defer)
(use-package package
   :install 'immediate)

That should disambiguate them from package names.

[raxod502]

What would be the equivalent of

(use-package tex-site
  :ensure auctex
  :defer-install t)

though?

[alphapapa]

Well, to me it seems like it should be:

(use-package auctex
  :install 'immediate)
(use-package tex-site
  :install 'defer)

Or if you really want to keep one conditional to the other, something like:

(use-package tex-site
  :install 'defer
  :needs auctex)

Because I find the combination of :defer, :defer-install, and :ensure a bit confusing, but maybe it's just me.

[vyp]

I think @alphapapa means

(use-package tex-site
  :install auctex 'defer)

? And I guess by default the second argument would be 'immediate?

Edit: oh

[alphapapa]

vyp's suggestion also seems reasonable, if you don't mind the mild ambiguity of the arguments to :install being free-floating. I guess it could also work like:

(use-package tex-site
  :install ('defer auctex))

In any case, I think the chief concern I have is that :ensure means "install this," but it's affected by :defer-install rather than :defer-ensure. I think it would be clearer if :ensure were :install. And it seems like :defer-install could then be obviated by a keyword argument to :install. Seems like it would be much clearer. But again, maybe it's just me. I don't use :ensure anyway, so maybe I should keep my ideas to myself. :)

[raxod502]

The additional quoting seems a little nonstandard to me, but honestly any of the things proposed here would be fine with me. As long as there's a way to replicate all the current use cases.

@alphapapa

(use-package auctex
  :install 'immediate)
(use-package tex-site
  :install 'defer)

that's different. It would install package auctex immediately and require the nonexistent auctex feature, then require the tex-site feature from the nonexistent tex-site package. Whereas what we want is to require the tex-site feature from the deferred package auctex.

I don't disagree that :ensure maybe should be :install. Or maybe :package?

[alphapapa]

It would install package auctex immediately and require the nonexistent auctex feature, then require the tex-site feature from the nonexistent tex-site package. Whereas what we want is to require the tex-site feature from the deferred package auctex.

I see, thanks. I'm not familiar with these packages.

I don't disagree that :ensure maybe should be :install. Or maybe :package?

I think using imperatives is clearer, since it causes action to be taken (i.e. it's not "packaging" anything).

[raxod502]

Yeah, auctex is weird like that. It was a bit eye-opening for me to realize that despite the name, use-package is centered around features, not packages. It's just that usually, the package name is the same as the feature name, and you can just pass :ensure t and use the default.

[vyp]

Yeah use-package should really be named use-feature in my opinion.