keybindings have been removed ?

simonmichael commented 2 years ago

@redguardtoo thanks for your work on this (#87).

I'm trying to replicate the setup I had with Sergey Pashinin's 1.2.1 Package-Version: 20201217.1159. (Yours still says version 1.2.1, perhaps time to change that even if not released yet.)

I think as part of your refactoring you removed many keybindings and functions I was used to. Is there somewhere I can read more about this ? What is your reasoning / plan ?

Many thanks.

simonmichael commented 2 years ago

Here are some more details/notes from my new workgroups2 config.

;;;; Workgroups

;; https://github.com/pashinin/workgroups2

;; Note: before loading workgroups2
(setq wg-prefix-key "C-c C-x")

;; load and enable
(add-to-list 'load-path "~/.emacs.d/src/workgroups2/src")
(require 'workgroups2)
;; Note: some things best done before, not after, enabling workgroups-mode:
;;  save-place-mode, adding outline-magic to outline-mode-hook
(workgroups-mode 1)

;; for viewing/editing saved state
(add-to-list 'auto-mode-alist '("workgroups$" . emacs-lisp-mode))

(defun add-to-keymap (keymap prefix-key &rest keybinds)
  "Given a KEYMAP and its prefix key as a kbd string argument, return KEYMAP after adding all KEYBINDS. Each binding is a kbd string argument and a quoted callable."
  (while keybinds
    (define-key keymap (kbd (format "%s %s" prefix-key (car keybinds))) (cadr keybinds))
    (setq keybinds (cddr keybinds)))
  keymap)

;; Add bindings / re-enable old bindings from workgroups 1.2.1.
;; Note: after loading workgroup2
(add-to-keymap workgroups-mode-map wg-prefix-key
   "C-x"        'wg-open-workgroup
;;    "C-k"        'wg-kill-workgroup    ; gone
;;    "C-k"        'wg-delete-workgroup  ; non-interactive
;;    "C-y"        'wg-yank-wconfig      ; gone
;;    "C-m"        'wg-rename-workgroup  ; gone
;;    "C-s"        'wg-save-session      ; non-interactive; needed ? 
;;    "C-w"        'wg-save-session-as   ; non-interactive
;; more stuff; gone ? needed ?
;;    "M-k"        'wg-kill-workgroup-and-buffers
;;    "K"          'wg-delete-other-workgroups
;;    "C-z"        'wg-switch-to-previous-workgroup
;;    "C-j"        'wg-switch-to-workgroup-at-index
;;    "0"          'wg-switch-to-workgroup-at-index-0
;;    "1"          'wg-switch-to-workgroup-at-index-1
;;    "2"          'wg-switch-to-workgroup-at-index-2
;;    "3"          'wg-switch-to-workgroup-at-index-3
;;    "4"          'wg-switch-to-workgroup-at-index-4
;;    "5"          'wg-switch-to-workgroup-at-index-5
;;    "6"          'wg-switch-to-workgroup-at-index-6
;;    "7"          'wg-switch-to-workgroup-at-index-7
;;    "8"          'wg-switch-to-workgroup-at-index-8
;;    "9"          'wg-switch-to-workgroup-at-index-9
;;    "C-p"        'wg-switch-to-workgroup-left
;;    "p"          'wg-switch-to-workgroup-left
;;    "C-n"        'wg-switch-to-workgroup-right
;;    "n"          'wg-switch-to-workgroup-right
;;    "C-r"        'wg-revert-workgroup
;;    "r"          'wg-revert-workgroup
;;    "C-S-r"      'wg-revert-all-workgroups
;;    "R"          'wg-revert-all-workgroups
;;    "<left>"     'wg-undo-wconfig-change
;;    "<right>"    'wg-redo-wconfig-change
;;    "["          'wg-undo-wconfig-change
;;    "]"          'wg-redo-wconfig-change
;;    "C-d C-s"    'wg-save-wconfig
;;    "C-d C-'"    'wg-restore-saved-wconfig
;;    "C-d C-k"    'wg-kill-saved-wconfig
;;    "C-,"        'wg-offset-workgroup-left
;;    "C-."        'wg-offset-workgroup-right
;;    "C-t C-m"    'wg-toggle-mode-line-display
;;    "C-t C-d"    'wg-toggle-window-dedicated-p
;;    "!"          'wg-reset
;;    "?"          'wg-help
;;    ))
)

redguardtoo commented 2 years ago

wg-create-workgroup and wg-open-workgroup are core commands to the workflow,

user need save the current window/frame layout into a named workgroup
user need open a workgroup to load the layout by the name

Other commands are removed or by default invisible (without key bindings) after refactoring to minimize the maintaining cost.

The purpose of refactoring is to focus on the major strength of workgroups2(wg2). What makes wg2 different is that it can load all kind of special buffers. For example, wg2 can remember the page number of last opened pdf file.

Removing non-essential functions makes wg2 more lightweight but more powerful at the same time.

For example, I replaced wg-completing-read with completing-read, so the filtering/searching/navigating work groups could be handled by modern selection frameworks (helm, ivy ....)

simonmichael commented 2 years ago

@redguardtoo: understood. As a result, it feels like starting over with a new package (workgroups3 ?).

Here are questions I had as a user, and my current answers/guesses - please correct my misunderstandings. Perhaps it is useful for docs ?

What is a workgroup ?

The window layout (and buffers) of a single frame, named and saved persistently.

What kinds of buffer can be in a workgroup ?

Buffers visiting files, and a growing number of special buffers, including org-agenda, shell, magit-status, help.

How do I install workgroups2 ?

Install the workgroups2 package from Melpa (and load it with (require 'workgroups2) ?). Or to run the latest unreleased dev version, git clone https://github.com/pashinin/workgroups2 as eg ~/.emacs.d/src/workgroups2, then

(add-to-list 'load-path "~/.emacs.d/src/workgroups2/src")
(require 'workgroups2)

This makes the wg-create-workgroup and wg-open-workgroup functions available, without keybindings.

How do I create a workgroup ?

M-x wg-create-workgroup. It will save the current frame's window layout, prompting for a name. This workgroup will be available in future emacs sessions also.

Where are workgroups saved ?

In wg-session-file, which is ~/.emacs_workgroups by default. You can customize it or set it, eg (setq wg-session-file "~/.emacs.d/workgroups").

How do I load/switch to a workgroup ?

M-x wg-open-workgroup. It will prompt for the name of a previously created workgroup, and restore its windows and (where possible) buffers.

How do I adjust an existing workgroup ?

Configure the new window layout, then wg-create-workgroup again, reusing the existing workgroup's name.

How do I rename a workgroup ?

Switch to the workgroup with wg-open-workgroup to activate its window layout.
Use wg-create-workgroup to save it with a new name.
Delete the workgroup with the old name.

How do I delete a workgroup ?

M-x wg-kill-workgroup.

What is workgroups-mode for, should I enable it ?

(workgroups-mode 1) activates workgroups mode, which does these things:

Sets up keybindings for wg-create-workgroup and wg-open-workgroup (C-c z C-c and C-c z C-v by default)
Loads the first saved workgroup from wg-session-file, or creates one named "First workgroup" if there are none. This can be disabled by setting wg-session-load-on-start.

You should enable workgroups mode if you'd like a workgroup to be loaded when you start Emacs, or if you'd like to use workgroups2's default keybindings.

How can I change that prefix key ?

Eg: (setq wg-prefix-key "C-c C-x"). This must be done before enabling workgroups mode.

What are some other things best done before, not after, enabling workgroups mode ?

Enabling save-place-mode.

Are workgroups saved when I exit Emacs ?

No, each workgroup is saved just once: when you create it with wg-create-workgroup.

What happens if I run an Emacs daemon and multiple clients ?

Each client will be aware of the all the latest saved workgroups.

What happens if I run multiple Emacs instances ?

Multiple Emacs instances writing to wg-session-file is currently not supported; workgroups created in all but the last-exiting instance can be overwritten and lost. So, if you run multiple Emacs instances, create new workgroups in only one of them.

redguardtoo commented 2 years ago

For the question "How do I delete a workgroup ?" You can use M-x wg-kill-workgroup now.

Could you update your comment. I will point the comment from README. In the future I will updated doc using your FAQ.

simonmichael commented 2 years ago

Nice! Comment updated.

panaak commented 2 years ago

Does this mean you removed the functions:

wg-switch-to-previous-workgroup

wg-switch-to-workgroup-left

wg-switch-to-workgroup-right

wg-offset-workgroup-left

wg-offset-workgroup-right

and you do not plan to re-enable them? That is pretty unfortunate, since these ones are pretty essential for me. :(

redguardtoo commented 2 years ago

Does this mean you removed the functions:
wg-switch-to-previous-workgroup

wg-switch-to-workgroup-left

wg-switch-to-workgroup-right

wg-offset-workgroup-left

wg-offset-workgroup-right
and you do not plan to re-enable them? That is pretty unfortunate, since these ones are pretty essential for me. :(

It's using api completing-read now. You can use completion ui package (helm, ivy, ...) for navigation.

panaak commented 2 years ago

That's nice, but I don't need to complete. I need to assign keybindings to switch to workgroup left/right and offset it likewise. Or if it is possible, I don't know how?

redguardtoo commented 2 years ago

(wg-workgroup-names) returns all the workgroup names. You can write your own command to navigate in the list.

The original navigation commands duplicate the functionalities of 3rd party completion ui framwork. And they takes lots of efforts to maintain. So they are removed.

mukundzare commented 2 years ago

One more question to consider for the FAQ: How does workgroups2 differ from other similar packages like perspective?

redguardtoo commented 2 years ago

wg2 supports lots of special buffers out of box.

And users can setup to support more types of special buffer.

https://github.com/pashinin/workgroups2/blob/master/README.org#support-special-buffer

pashinin / workgroups2