docs: README

README.org

@@ -0,0 +1,55 @@
+#+TITLE: perspective-exwm
+
+A couple of tricks and fixes to make using [[https://github.com/ch11ng/exwm][EXWM]] and [[https://github.com/nex3/perspective-el][perspective.el]] a better experience.
+
+* Installation
+While this package isn't available anywhere but here, you can install it directly from the repo, e.g.:
+#+begin_src emacs-lisp
+(use-package perspective-exwm
+  :straight (:host github :repo "SqrtMinusOne/perspective-ewxm.el"))
+#+end_src
+Or clone the repository, add the package to the =load-path= and load it with =require=.
+
+The package provides a minor mode, =perspective-exwm-mode=, which is meant to be loaded before =exwm-init=. For instance, if you use =use-package=:
+#+begin_src emacs-lisp
+(use-package exwm
+  :config
+  ...
+  (perspective-exwm-mode)
+  (exwm-init))
+#+end_src
+
+* Usage and details
+- =perspective-exwm-mode=
+  The mode does a couple of things:
+  - advises away a bug with half-killing the current perspective when closing a floating window. I haven't tested this as thoroughly, so run =M-x perspective-exwm-revive-perspectives= if the problem arises anyway.
+  - adjusts the name of the inital perspective in the new workspace. It tries to get the name from the =perspective-exwm-override-initial-name= variable and falls back to `main-<index>`.
+
+  I have the following in my configuration:
+  #+begin_src emacs-lisp
+  (setq perspective-exwm-override-initial-name
+      '((0 . "misc")
+        (1 . "core")
+        (2 . "browser")
+        (3 . "comms")
+        (4 . "dev")))
+  #+end_src
+
+  This also serves a purpose, because otherwise there are issues with multiple perspectives sharing the same scratch buffer.
+- =M-x perspective-exwm-cycle-exwm-buffers-forward=, =perspective-exwm-cycle-exwm-buffers-backward=
+  Cycles EXWM buffers in the current perspective.
+
+  [[./img/cycle-buffers.png]]
+
+  The buffer highlighted in yellow is the current one, the buffer highlighted in blue is shown in another window of the perspective so it will be omitted from the cycle.
+
+  Set =perspective-exwm-get-exwm-buffer-name= to customize the displayed name, by default it's =exwm-class-name=.
+
+- =M-x perspective-exwm-switch-perspective=
+  Select a perspective from the list of all perspectives on all workspaces.
+
+  [[./img/switch-perspective.png]]
+- =M-x perspective-exwm-copy-to-workspace=
+  Copy the current perspective to another EXWM workspace.
+- =M-x perspective-exwm-move-to-workspace=
+  Move the current perspective to another EXWM workspace.

perspective-exwm.el

@@ -158,7 +158,7 @@ detail."
 
 ;;;###autoload
 (defun perspective-exwm-copy-to-workspace (&optional move)
-  "Copy the current perspective to an EXWM workspace.
+  "Copy the current perspective to another EXWM workspace.
 
 If MOVE is t, move the perspective instead."
   (interactive)
@@ -171,6 +171,8 @@ If MOVE is t, move the perspective instead."
     (unless (= (cl-position target-workspace exwm-workspace--list)
                exwm-workspace-current-index)
       (with-selected-frame target-workspace
+        (when (gethash persp-name (perspectives-hash))
+          (error "Perspective with name \"%s\" already exists on the target workspace" persp-name))
         (puthash persp-name (copy-tree (copy-perspective persp)) (perspectives-hash))
         (with-perspective persp-name
           ;; (run-hooks 'persp-created-hook)
@@ -245,8 +247,6 @@ Overrides `persp-initial-frame-name' according to `perspective-exwm-override-ini
     (when to-switch
       (persp-switch (persp-name to-switch)))))
 
-
-
 ;;;###autoload
 (define-minor-mode perspective-exwm-mode
   "A minor mode for intergrating perspective.el and EXWM.