Wording "layout" and "workspace"

[matleh]

Disclosure: I am not a native English speaker, so what I say here may be due to this fact.

It took me a considerate amount of time to figure out what "layouts" and "workspaces" are all about. Part of this difficulty is due to the counter-intuitive use of the words layout and workspace.

As far as I understand, a layout in Spacemacs is a sub-set of open buffers and a workspace is an arrangement of several buffers within that. To my foreign-language understanding of the words "layout" and "workspace" it would make more sense to use them the other way around.

A workspace very often corresponds to a project - if I change to a different task, I change the "space I work on - the work-space", so this intuitively corresponds to a set of file/buffers associated with that task.

A layout, on the other hand, is usually understood to mean a visual arrangement of things. If I say I change the layout, I mean that I still work on the same things, but look at it differently.

Maybe it is too late already to change the wording, or the existing wording is already established in the Emacs community (like window and frame meaning something different in Emacs than to the rest of the world). However I wanted to share my experience in case there is a way to make the meaning of these great features more "accessible" for new users.

[syl20bnr]

I'm aware of this but cannot change it without confusing a lot of people already using Spacemacs. It has also a lot of ramifications into the code base and documentation and even up to key bindings! Additionally the wording can make sense but this is not the most obvious one I agree. So we can consider this technical debt but to me it is not as far as documentation is consistent and wording is making sense (which it does here).

[d12frosted]

I do like that this question was asked, because when I just started using layouts I couldn't really understand it as well. Some people might remember me asking for several times about difference between eyebrowse (workspaces) and perspectives (layouts) back when Spacemacs had them as separate layers. It even turned out that they can be used both at the same time.

In any case, I do agree that at this point the change of names is far from being great idea. A lot of stuff is tied on these names.

P. S. Documentation on layouts and workspaces is available only on develop right now. I don't mean layer readme file, but a section in documentation file (develop).

[syl20bnr]

Ah indeed the doc is not yet in master, it will be only in the next version which should be released this month after I document better Ivy and helm. Funny thing is that we see my struggle in the doc with the term workspace where they are mentioned as sub-layouts in the doc :-)

[d12frosted]

Funny thing is that we see my struggle in the doc with the term workspace where they are mentioned as sub-layouts in the doc

Indeed. But I think it's a good explanation of how they are used in Spacemacs.

[darkfeline]

I think a huge amount of confusion can be decreased by renaming layout to something else starting with l, since the key point is that layout doesn't convey the meaning of tying a group of buffers together.

[bryanbecker]

I agree. I'm a native speaker, and I had to spend a considerable amount of effort wrapping my head around these concepts before I realized they were emacs specific words.

I did some thesaurus searching, but it's quite hard to find a word that begins with 'L' that conveys this idea. Here are some that I found that may be of use:

• Lock
• Lump (eww)
• Local
• Logic (logical group)

Alternatively, could use a word that doesn't begin with 'L', but that contains L, such as "elipses", althogh I can't think of any good ones.

[aniketd]

Just came across this issue and was blessed with all I ever needed to understand what I was doing wrong trying to figure out persp-mode.

To figure out what "layouts" and "workspaces" are all about, part of the difficulty is due to the counter-intuitive use of the words 'layout' and 'workspace'. A layout in Spacemacs is a sub-set of open buffers and a workspace is an arrangement of several buffers within that. Yes, that's how it is. A workspace very often corresponds to a project - if I change to a different task, I change the "space I work on - the work-space", so this intuitively corresponds to a set of file/buffers associated with that task. A layout, on the other hand, is usually understood to mean a visual arrangement of things. If I say I change the layout, I mean that I still work on the same things, but look at it differently. But thats not how it is with Spacemacs.

That cherry-picked (slightly modified) excerpt, @matleh, could go into the documentation as bold-quote! Which will make this thing very clear, and it will also account for the technical debt @syl20bnr mentioned, as it belongs to all of us.

[deb0ch]

I still feel just as strongly that the two names should be reversed in both the docs and the code.

I even think that it could be scriptable to some extent, with some reviewing.

As for the already existing users, this way is so much more obvious that they would not be confused for more than a few seconds.

This is an awful technical debt that we really should get rid of, and I'm sure that it prevents a lot of users from even using the feature, as it makes it a lot harder to understand.

[a13ph]

Reversing layout <-> workspace makes more sense than keeping them, semantically.

Then it would be something like "You work on a set of buffers depending on workspace. But you can arrange your work differently with different layouts"

I'll manage either way. But Emacs has enough of backwards and otherwise idiosyncratic terms. Being understandable (more often than not) without reading documentation is preferable to just good documentation.

Though now that this feature is on master branch - I feel that there's no perfect solution. Only tradeoffs.

P.S. Tabs may also be contenders... https://www.nngroup.com/articles/tabs-used-right/ Though nowadays people are too used to quite a different notion of a tab.

[syl20bnr]

There are two possibilities, a damage control one and an ambitious one which could annoy a lot of users (whereas being saner in the long term).

1. We rename workspaces as sub-layouts and so we ditch the semantic of workspaces and just build our own semantic of a layout (like we started to do before integrating eyebrowse workspaces into layouts)
2. take a deep breath and read it quickly: we switch workspace and layer semantic and switch SPC k and SPC l, k for workspace and l for lisp. SPC l w becomes SPC k l. There seems to be less work when read quickly :-)

[syl20bnr]

I'm in for the solution 2. Any objection ?

[deb0ch]

I'm all in for solution 2, just I'll have time for the big work (and all the rest) only in a few weeks :smile_cat:

If I understood right, solution 2 is to:

• rename workspaces -> layouts in the ui, the docs and the code,
• rename layouts -> workspaces in the ui, the docs and the code,
• move SPC k to SPC l (more mnemonic for lisp)
• assign SPC k to the new meaning of worKspace (persp-mode)
• assign SPC k l to what was SPC l w (eyebrowse)

I would also like to make some additional proposals:

• find a more direct binding for eyebrowse than SPC k l: bind the lisp stuff (less widely used) to SPC L and bind eyebrowse transient state so SPC l
• allow toggling between workspace and layout transient states using the same key: l and w would both be available in both transient states and lead to the other transient state. Repeatedly pressing l would keep toggling between them, same for w.

Also, is there any code / comments / docs to modify in the packages themselves, or is the layouts / workspaces wording specific to Spacemacs ?

[planigan]

I just read #8587, which seems relevant here. I am still pretty confused by layouts/workspaces in spacemacs after ~2 months of daily use. If you're going to significantly change how things work with regard to layouts/workspaces, please make sure that the documentation improves along with the other changes. More visuals and use cases would be great.

[quicknir]

@syl20bnr I strongly agree with @deb0ch's suggestion to use SPC k and SPC l for workspaces/layouts, and use SPC L for lisp. I've never been a big fan of SPC k because I feel like it is doing major mode specific stuff at the global leader key level; many of the commands don't do very sensible things in non-lisp languages.

Also, I'd like to link this back to an issue I raised a little bit ago: https://github.com/syl20bnr/spacemacs/issues/6763. While doing this, I think that the layouts/workspace transient states should be made more consistent with other things. I appreciate that some of the functionality makes more sense when you can see what's open, but not all, and especially for workspaces I'm not sure why everything is only available as a transient state. In other words I think that:

• SPC l . should be layout transient state, SPC k . should be workspace transient state
• SPC l d should delete the current layout, SPC k d should delete current workspace, SPC l b should be buffer in layout, SPC l l should be helm layouts, etc, these are all examples that don't need to be in the transient state (or at least not exclusively).

If we can divide up the work in a logical way so as not to step on one another I'm willing to help with this.

[Millani]

I don't know to which extent these changes proposed here have been already implemented, but I never understood why, instead of originally calling them (a) layoutsand (b) workspaces, they were not called, respectively, something like (a) desktops and (b) layouts or (a) sessions and (b) layouts.

Sure, it still poses the problem of calling something layouts that had a different meaning from before ( (b) workspaces->layouts). But it at least removes the analogous problem from the other, more often used, concept ( (a) layouts->desktops/sessions).

To improve on that further, one could also call the current (b) workspaces something like winlayouts, which would avoid confusion with the current naming and also retain the initial letter w, thus having:

layouts -> desktops (or sessions) workspaces -> winlayouts

[syl20bnr]

I will start to work on this soon, this is a deep change that I'm willing to tackle myself, at least at the beginning (not sure where I will stop exactly 😃 ).

I guess most of us agree about what we need to do:

• swap meaning of terms workspace and layout
• SPC k for workspaces
• SPC l for layouts
• move lisp functions under the major mode prefix. With the shortcut , for SPC m we keep the same amount of keystrokes and it feels more natural as @quicknir said, so lisp commands will be under , l (really under SPC m l) or something even more ergonomic.
• have binding consistency between SPC k and SPC l

[vendethiel]

Just a question on that matter... For now, :w closes the whole workspace, what's going to happen now?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Please let us know if this issue is still valid!

[nixmaniack]

Should be kept open I believe.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Please let us know if this issue is still valid!

[vendethiel]

Bump

[syl20bnr]

Ahah this is one is tough. I still want to do what's described here: https://github.com/syl20bnr/spacemacs/issues/6200#issuecomment-356197108

But I feel we should do it after we release a new stable because this is a pretty disruptive one already.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Please let us know if this issue is still valid!

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Please let us know if this issue is still valid!

[vendethiel]