Remove the default key prefix when using Emacs 28 or later.

Discussion: https://github.com/nex3/perspective-el/issues/180.

3 files changed, 46 insertions, 15 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d937ea3..864e97e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Changed
 
+- **Breaking change:** (Emacs 28+ only): no longer provide a default `persp-mode-prefix-key`. It was `C-x x` in the past, which conflicts with key bindings shipping with Emacs 28. Users of Emacs 28 must now pick their own prefix key. The default remains unchanged for users of Emacs 27 and earlier.
 - `persp-remove-buffer`: do not kill/remove a perspective's last left buffer.
 - `persp-switch-to-buffer*`: tag with `'buffer` category so Marginalia can add its annotations.
 - `persp-other-buffer`: rewrite so it respects ignored buffer list.
diff --git a/README.md b/README.md
index e0a2062..1974b77 100644
--- a/README.md
+++ b/README.md
@@ -169,10 +169,12 @@ You should install Perspective from [MELPA](https://melpa.org/) or [MELPA Stable
 
 Users of [`use-package`](https://github.com/jwiegley/use-package) can install Perspective as follows:
 
-```
+```elisp
 (use-package perspective
   :bind
-  ("C-x C-b" . persp-list-buffers)   ; or use a nicer switcher, see below
+  ("C-x C-b" . persp-list-buffers)         ; or use a nicer switcher, see below
+  :custom
+  (persp-mode-prefix-key (kbd "C-c M-p"))  ; pick your own prefix key here
   :init
   (persp-mode))
 ```
@@ -181,8 +183,15 @@ Replace the binding for `C-x C-b`, the default Emacs buffer switcher, with one
 of the nicer implementations described in the [Buffer
 switchers](#buffer-switchers) section.
 
-Alternately, put `perspective.el` from this source repository in your load path
-and run `(require 'perspective)`.
+If not using `use-package`, put `perspective.el` from this source repository
+somewhere on your load path, and use something similar to this:
+
+```elisp
+(require 'perspective)
+(global-set-key (kbd "C-x C-b") 'persp-list-buffers)
+(customize-set-variable 'persp-mode-prefix-key (kbd "C-c M-p"))
+(persp-mode)
+```
 
 Users of Debian 9 or later or Ubuntu 16.04 or later may simply `apt-get install
 elpa-perspective`, though be aware that the stable version provided in these
@@ -191,12 +200,21 @@ repositories is likely to be (extremely) outdated.
 
 ## Usage
 
-To activate perspective use `(persp-mode)`. This creates a single default `main`
-perpsective.
-
-Commands are all prefixed by `C-x x` by default. To change the prefix key,
-customize `persp-mode-prefix-key`. Additionally, creating a key binding for
-`persp-mode-map` will also activate the prefix.
+To activate Perspective, use `(persp-mode)`. This creates a single default
+`main` perpsective.
+
+> :information_source: Since the release of Emacs 28, Perspective no longer
+> ships with a default command prefix. Users should pick a prefix comfortable
+> for them. In the days of Emacs 27 and earlier, the default prefix was `C-x x`.
+> This conflicts with bindings built into Emacs 28.
+
+To set a prefix key for all Perspective commands, customize
+`persp-mode-prefix-key`. Reasonable choices include `C-x x` (for users who don't
+care about the Emacs buffer-related commands this shadows), `C-z` (for users who
+don't suspend Emacs to shell background), `C-c C-p` (for users who don't mind
+the conflicting keys with `org-mode` and `markdown-mode`), `C-c M-p` (for users
+who don't mind the slightly awkward chord), and `H-p` (for users who don't mind
+relying exclusively on a non-standard Hyper modifier).
 
 The actual command keys (the ones pressed after the prefix) are defined in
 `perspective-map`. Here are the main commands defined in `perspective-map`:
diff --git a/perspective.el b/perspective.el
index ee6e8d4..31d36b1 100644
--- a/perspective.el
+++ b/perspective.el
@@ -73,7 +73,7 @@ instead of the full perspective list."
   :group 'perspective-mode
   :type 'boolean)
 
-(defcustom persp-mode-prefix-key (kbd "C-x x")
+(defcustom persp-mode-prefix-key (if (version< emacs-version "28.0") (kbd "C-x x") nil)
   "Prefix key to activate perspective-map."
   :group 'perspective-mode
   :set (lambda (sym value)
@@ -81,7 +81,8 @@ instead of the full perspective list."
                     (bound-and-true-p perspective-map))
            (persp-mode-set-prefix-key value))
          (set-default sym value))
-  :type 'key-sequence)
+  :type '(choice (const :tag "None" nil)
+                 key-sequence))
 
 (defcustom persp-interactive-completion-function
   (if ido-mode 'ido-completing-read 'completing-read)
@@ -124,6 +125,11 @@ save state when exiting Emacs."
   :group 'perspective-mode
   :type 'file)
 
+(defcustom persp-suppress-no-prefix-key-warning nil
+  "When non-nil, do not warn the user about `persp-mode-prefix-key' not being set."
+  :group 'perspective-mode
+  :type 'boolean)
+
 (defcustom persp-feature-flag-prevent-killing-last-buffer-in-perspective nil
   "Experimental feature flag: prevent killing the last buffer in a perspective."
   :group 'perspective-mode
@@ -357,7 +363,8 @@ Run with the activated perspective active.")
   "Sub-keymap for perspective-mode")
 
 (define-prefix-command 'perspective-map)
-(define-key persp-mode-map persp-mode-prefix-key 'perspective-map)
+(when persp-mode-prefix-key
+  (define-key persp-mode-map persp-mode-prefix-key 'perspective-map))
 
 (define-key perspective-map (kbd "s") 'persp-switch)
 (define-key perspective-map (kbd "k") 'persp-remove-buffer)
@@ -372,7 +379,6 @@ Run with the activated perspective active.")
 (define-key perspective-map (kbd "<right>") 'persp-next)
 (define-key perspective-map (kbd "p") 'persp-prev)
 (define-key perspective-map (kbd "<left>") 'persp-prev)
-(define-key perspective-map persp-mode-prefix-key 'persp-switch-last)
 (define-key perspective-map (kbd "m") 'persp-merge)
 (define-key perspective-map (kbd "u") 'persp-unmerge)
 (define-key perspective-map (kbd "g") 'persp-add-buffer-to-frame-global)
@@ -460,7 +466,8 @@ FRAME defaults to the currently selected frame."
 (defun persp-mode-set-prefix-key (newkey)
   "Set NEWKEY as the prefix key to activate persp-mode."
   (substitute-key-definition 'perspective-map nil persp-mode-map)
-  (define-key persp-mode-map newkey 'perspective-map))
+  (when newkey
+    (define-key persp-mode-map newkey 'perspective-map)))
 
 (defvar persp-protected nil
   "Whether a perspective error should cause persp-mode to be disabled.
@@ -1369,6 +1376,11 @@ named collections of buffers and window configurations."
         (setq read-buffer-function 'persp-read-buffer)
         (mapc 'persp-init-frame (frame-list))
         (setf (persp-current-buffers) (buffer-list))
+        (unless (or persp-mode-prefix-key persp-suppress-no-prefix-key-warning)
+          (display-warning
+           'perspective
+           (format-message "persp-mode-prefix-key is not set! If you see this warning, you are using Emacs 28 or later, and have not customized persp-mode-prefix-key. Please refer to the Perspective documentation for further information (https://github.com/nex3/perspective-el). To suppress this warning without choosing a prefix key, set persp-suppress-no-prefix-key-warning to `t'.")
+           :warning))
         (run-hooks 'persp-mode-hook))
     (persp--helm-disable)
     (ad-deactivate-regexp "^persp-.*")