Replace `org-speed-commands-user' by `org-speed-commands'

* etc/ORG-NEWS: Announce `org-speed-commands'.

* doc/org-manual.org (Speed Keys): Document `org-speed-commands'
instead of `org-speed-commands-user'.

* lisp/org-compat.el (org-speed-commands-user): Make an obsolete
variable.

* lisp/org-keys.el (org-speed-commands-user): Remove.
(org-speed-commands): Rename from `org-speed-commands-default' and
make a defcustom.  Add the docstring of `org-speed-commands-user'.
(org-speed-command-help): Throw a message about obsolete option
`org-speed-commands-user' when set in the user configuration.
(org-speed-command-activate): Update docstring.

Link: https://orgmode.org/list/87eeep3c1u.fsf@bzg.fr/

4 files changed, 60 insertions, 44 deletions

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 3008d5a..7649a70 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18656,14 +18656,14 @@ the variable ~org-use-speed-commands~ to a non-~nil~ value.  To
 trigger a Speed Key, point must be at the beginning of an Org
 headline, before any of the stars.
 
-#+vindex: org-speed-commands-user
+#+vindex: org-speed-commands
 #+findex: org-speed-command-help
 Org comes with a pre-defined list of Speed Keys.  To add or modify
-Speed Keys, customize the variable, ~org-speed-commands-user~.  For
-more details, see the variable's docstring.  With Speed Keys
-activated, {{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when
-point is at the beginning of an Org headline, shows currently active
-Speed Keys, including the user-defined ones.
+Speed Keys, customize the option ~org-speed-commands~.  For more
+details, see the variable's docstring.  With Speed Keys activated,
+{{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when point is at the
+beginning of an Org headline, shows currently active Speed Keys,
+including the user-defined ones.
 
 ** A Cleaner Outline View
 :PROPERTIES:
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 5bd3295..2f3e8af 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -13,7 +13,7 @@ Please send Org bug reports to mailto:emacs-orgmode@gnu.org.
 
 * Version 9.5 (not yet released)
 
-** Important announcements
+** Important announcements and breaking changes
 
 *** The =contrib/= now lives in a separate repository
 
@@ -41,6 +41,11 @@ latest unstable Org, please install from the Git repository.
 
 See https://orgmode.org/org.html#Installation for the details.
 
+*** ~org-speed-commands-user~ is obsolete, use ~org-speed-commands~
+
+Setting ~org-speed-commands-user~ in your configuration won't have any
+effect.  Please set ~org-speed-commands~ instead, which see.
+
 ** New options and settings
 *** Option ~org-hidden-keywords~ now also applies to #+SUBTITLE:
 
diff --git a/lisp/org-compat.el b/lisp/org-compat.el
index 3d45bed..112aa64 100644
--- a/lisp/org-compat.el
+++ b/lisp/org-compat.el
@@ -1202,6 +1202,11 @@ key."
 (eval-after-load 'session
   '(add-to-list 'session-globals-exclude 'org-mark-ring))
 
+;;;; Speed commands
+
+(make-obsolete-variable 'org-speed-commands-user
+                        "configure `org-speed-commands' instead." "9.5")
+
 (provide 'org-compat)
 
 ;; Local variables:
diff --git a/lisp/org-keys.el b/lisp/org-keys.el
index 07ff853..f04f87d 100644
--- a/lisp/org-keys.el
+++ b/lisp/org-keys.el
@@ -696,28 +696,6 @@ star at the beginning of the headline, you can do this:
 	  (const :tag "At beginning of headline stars" t)
 	  (function)))
 
-(defcustom org-speed-commands-user nil
-  "Alist of additional speed commands.
-This list will be checked before `org-speed-commands-default'
-when the variable `org-use-speed-commands' is non-nil
-and when the cursor is at the beginning of a headline.
-The car of each entry is a string with a single letter, which must
-be assigned to `self-insert-command' in the global map.
-The cdr is either a command to be called interactively, a function
-to be called, or a form to be evaluated.
-An entry that is just a list with a single string will be interpreted
-as a descriptive headline that will be added when listing the speed
-commands in the Help buffer using the `?' speed command."
-  :group 'org-structure
-  :type '(repeat :value ("k" . ignore)
-		 (choice :value ("k" . ignore)
-			 (list :tag "Descriptive Headline" (string :tag "Headline"))
-			 (cons :tag "Letter and Command"
-			       (string :tag "Command letter")
-			       (choice
-				(function)
-				(sexp))))))
-
 (defcustom org-speed-command-hook
   '(org-speed-command-activate org-babel-speed-command-activate)
   "Hook for activating speed commands at strategic locations.
@@ -737,7 +715,7 @@ hook.  The default setting is `org-speed-command-activate'."
   :version "24.1"
   :type 'hook)
 
-(defconst org-speed-commands-default
+(defcustom org-speed-commands
   '(("Outline Navigation")
     ("n" . (org-speed-move-safe 'org-next-visible-heading))
     ("p" . (org-speed-move-safe 'org-previous-visible-heading))
@@ -762,8 +740,7 @@ hook.  The default setting is `org-speed-command-activate'."
     ("l" . org-metaleft)
     ("R" . org-shiftmetaright)
     ("L" . org-shiftmetaleft)
-    ("i" . (progn (forward-char 1) (call-interactively
-				    'org-insert-heading-respect-content)))
+    ("i" . (progn (forward-char 1) (call-interactively 'org-insert-heading-respect-content)))
     ("^" . org-sort)
     ("w" . org-refile)
     ("a" . org-archive-subtree-default-with-confirmation)
@@ -782,8 +759,7 @@ hook.  The default setting is `org-speed-command-activate'."
     (":" . org-set-tags-command)
     ("e" . org-set-effort)
     ("E" . org-inc-effort)
-    ("W" . (lambda(m) (interactive "sMinutes before warning: ")
-	     (org-entry-put (point) "APPT_WARNTIME" m)))
+    ("W" . (lambda (m) (interactive "sMinutes before warning: ") (org-entry-put (point) "APPT_WARNTIME" m)))
     ("Agenda Views etc")
     ("v" . org-agenda)
     ("/" . org-sparse-tree)
@@ -792,7 +768,28 @@ hook.  The default setting is `org-speed-command-activate'."
     ("?" . org-speed-command-help)
     ("<" . (org-agenda-set-restriction-lock 'subtree))
     (">" . (org-agenda-remove-restriction-lock)))
-  "The default speed commands.")
+  "Alist of speed commands.
+
+The car of each entry is a string with a single letter, which
+must be assigned to `self-insert-command' in the global map.
+
+The cdr is either a command to be called interactively, a
+function to be called, or a form to be evaluated.
+
+An entry that is just a list with a single string will be
+interpreted as a descriptive headline that will be added when
+listing the speed commands in the Help buffer using the `?' speed
+command."
+  :group 'org-structure
+  :package-version '(Org . "9.5")
+  :type '(repeat :value ("k" . ignore)
+		 (choice :value ("k" . ignore)
+			 (list :tag "Descriptive Headline" (string :tag "Headline"))
+			 (cons :tag "Letter and Command"
+			       (string :tag "Command letter")
+			       (choice
+				(function)
+				(sexp))))))
 
 (defun org-print-speed-command (e)
   (if (> (length (car e)) 1)
@@ -814,12 +811,18 @@ hook.  The default setting is `org-speed-command-activate'."
   (interactive)
   (unless org-use-speed-commands
     (user-error "Speed commands are not activated, customize `org-use-speed-commands'"))
+  ;; FIXME: remove this warning for 9.6
+  (when (boundp 'org-speed-commands-user)
+    (message "`org-speed-command-user' is obsolete, please use `org-speed-commands'")
+    (sit-for 3))
   (with-output-to-temp-buffer "*Help*"
-    (princ "User-defined Speed commands\n===========================\n")
-    (mapc #'org-print-speed-command org-speed-commands-user)
-    (princ "\n")
-    (princ "Built-in Speed commands\n=======================\n")
-    (mapc #'org-print-speed-command org-speed-commands-default))
+    (princ "Speed commands\n==============\n")
+    (mapc #'org-print-speed-command
+          ;; FIXME: don't check `org-speed-commands-user' past 9.6
+          (if (boundp 'org-speed-commands-user)
+              (append org-speed-commands
+                      org-speed-commands-user)
+            org-speed-commands)))
   (with-current-buffer "*Help*"
     (setq truncate-lines t)))
 
@@ -835,13 +838,16 @@ If not, return to the original position and throw an error."
 
 (defun org-speed-command-activate (keys)
   "Hook for activating single-letter speed commands.
-`org-speed-commands-default' specifies a minimal command set.
-Use `org-speed-commands-user' for further customization."
+See `org-speed-commands' for configuring them."
   (when (or (and (bolp) (looking-at org-outline-regexp))
 	    (and (functionp org-use-speed-commands)
 		 (funcall org-use-speed-commands)))
-    (cdr (assoc keys (append org-speed-commands-user
-			     org-speed-commands-default)))))
+    (cdr (assoc keys
+                ;; FIXME: don't check `org-speed-commands-user' past 9.6
+                (if (boundp 'org-speed-commands-user)
+                    (append org-speed-commands
+                            org-speed-commands-user)
+                  org-speed-commands)))))
 
 
 ;;; Babel speed keys