Layer installation instructions

[TheBB]

Most layers tell you to install them by adding a line

(setq-default dotspacemacs-configuration-layers '(blabla))

to the dotfile. There are pretty frequently newbies on gitter making the mistake of taking this literally.

[syl20bnr]

Indeed, this point has been mentioned in the past and someone proposed something like:

(setq-default
;; ...
dotspacemacs-configuration-layers
  '(
    ;; ...
    blabla
    ;; ...
  )
;; ...
)

[syl20bnr]

Who has the motivation to do this ? :-)))

[d12frosted]

In my opinion, layers should not ever mention this installation step. In any case, in order to enable layer you have to add it to dotspacemacs-configuration-layers. So probably we have to write information about enabling modules in quick start and be fine with it.

The only thing that comes into my mind is layers like +lang/best-lang-ever. We have to say that you need to add best-lang-ever instead of +lang/best-lang-ever.

[d12frosted]

Another reason to avoid mentioning this installation step in layer readme file - it's much easier to change it in one place instead of dozens of files.

[ghoot]

To be friendly for beginners, if the default .spacemacs actually listed all available layers, with only some enabled, then with one mention in the Quickstart about where to enable, things should be easier to fathom, and also easier to maintain i.e. new layers don't need to repeat explicit install instructions in the layer docs (unless extra steps required).

However it would mean each new layer addition needs its layer added to the template .spacemacs.

New users often want to try out whats available quickly so listing all layers in the default config facilitates quick experimentation (and visibility) and probably before the new user is familiar with how to use the spacemacs help and docs. By the time you find your feet you manage your layer list however you like.

(setq-default
;; ...
dotspacemacs-configuration-layers
  '(
    all
    layers
    listed
    ;; only
    ;; some
    ;; enabled
    ;; ...
  )
;; ...
)

[robbyoconnor]

@ghoot all fine and dandy but that adds overhead for us to maintain that list.

[ghoot]

@robbyoconnor yeah. Once its in place to reflect the current layers it could then be a requirement of new layer submissions (low overhead). It's potentially a small tradeoff if there is benefit for newcomers to have easy access to the whole list in their initial config. Given the number of mentions this seems to get, might be worth it as a lo-fi stepping stone.

[robbyoconnor]

I disagree. Don't bloat the template.

[ghoot]

The template currently is oriented around informing the user of the possible feature settings and giving examples of their use, rather than an optimal config (rightly so). Adding more info re layers in that spirit isn't necessarily bloat.

Users don't explicitly need most of whats in the template as it is, but it's useful to see it there and informative, and layers are one of the key features that people seem to be attracted to. Obviously there's a disconnect for some users in taking the next step and adding layers.

I do agree listing them all is pretty lo-fi, and not pretty. I've seen it done before as a way of helping folk get going.

Anyway, was just thinking out loud.

[robbyoconnor]

I don't agree with THAT solution... currently it's not helpful -- I figured it out...others can too...I assume people aren't idiots...

[ghoot]

Haha, yeah well there is that :)

[syl20bnr]

I took the proposal of #4431 and applied it to all the layers. Should fix the ambiguity.
We can later add an example at one unique place.

Will be part of 0.105.3.