transient-common-command-prefix: New option

Author: tarsius

docs/transient.org

@@ -188,33 +188,56 @@ documentation string.
 #+cindex: common suffix commands
 
 A few shared suffix commands are available in all transients.  These
-suffix commands are not shown in the popup buffer by default.
+suffix commands are not shown permanently in every menu by default.
+Most of these commands share a common prefix key and pressing that key
+causes the common commands to be temporarily shown in the active menu.
 
-This includes the aborting commands mentioned in the previous section,
-as well as some other commands that are all bound to {{{kbdvar(C-x <KEY>)}}}.  After
-{{{kbd(C-x)}}} is pressed, a section featuring all these common commands is
-temporarily shown in the popup buffer.  After invoking one of them,
-the section disappears again.  Note, however, that one of these
-commands is described as “Show common permanently”; invoke that if you
-want the common commands to always be shown for all transients.
+- User Option: transient-show-common-commands ::
 
-- Key: C-x t (transient-toggle-common) ::
+  This option controls whether shared suffix commands are permanently
+  shown alongside the menu-specific infix and suffix commands.  By
+  default, the shared commands are not permanently shown to avoid
+  wasting precious space and overwhelming the user with too many
+  choices.
 
-  This command toggles whether the generic commands that are common to
-  all transients are always displayed or only after typing the
-  incomplete prefix key sequence {{{kbd(C-x)}}}.  This only affects the current
-  Emacs session.
+  If you prefer to always see these commands, then set this option to
+  a non-~nil~ value.  Alternatively the value can be toggled for the
+  current Emacs session only, using ~transient-toggle-common~, described
+  below.
 
-- User Option: transient-show-common-commands ::
+- User Option: transient-common-command-prefix ::
+
+  This option specifies the prefix key used in all transient menus
+  to invoke most of the shared commands, which are available in all
+  transient menus.  By default these bindings are only shown after
+  pressing that prefix key and before following that up with a valid
+  key binding (but see the previous option).
+
+  For historic reasons {{{kbd(C-x)}}} is used by default, but users are
+  encouraged to pick another key, preferably one that is not commonly
+  used in Emacs but is still convenient to them.
+
+  Usually, while a transient menu is active, the user cannot invoke
+  commands that are not bound in the menu itself.  For those menus it
+  does not matter, if {{{kbd(C-x)}}} or another commonly used prefix key is used
+  for common menu commands.  However, certain other, newer menus do
+  not suppress key bindings established outside the menu itself, and
+  in those cases a binding for a common menu command could shadow an
+  external binding.  For example, {{{kbd(C-x C-s)}}} could not be used to invoke
+  ~save-buffer~, if that binding is shadowed by the menu binding for
+  ~transient-save~.
+
+  Which key is most suitable depends on the user's preferences, but
+  good choices may include function keys and {{{kbd(C-z)}}} (for many keyboard
+  layouts {{{kbd(z)}}} is right next to {{{kbd(x)}}}, and invoking ~suspend-frame~, while a
+  transient menu is active, would not be a good idea anyway).
 
-  This option controls whether shared suffix commands are shown
-  alongside the transient-specific infix and suffix commands.  By
-  default, the shared commands are not shown to avoid overwhelming
-  the user with too many options.
+- Key: C-x t (transient-toggle-common) ::
 
-  While a transient is active, pressing {{{kbd(C-x)}}} always shows the common
-  commands.  The value of this option can be changed for the current
-  Emacs session by typing {{{kbd(C-x t)}}} while a transient is active.
+  This command toggles whether the generic commands, that are common
+  to all transients, are permanently displayed or only after typing
+  the incomplete prefix key sequence{{{kbd()}}}.  This only affects the current
+  Emacs session.
 
 The other common commands are described in either the previous or in
 one of the following sections.
@@ -236,6 +259,10 @@ suffix command, then the value is merely saved to the transient's
 history.  That value won't be used when the transient is next invoked,
 but it is easily accessible (see [[*Using History]]).
 
+Option ~transient-common-command-prefix~ controls the prefix key used
+in the following bindings.  For simplicity's sake the default, {{{kbd(C-x)}}},
+is shown below.
+
 - Key: C-x s (transient-set) ::
 
   This command saves the value of the active transient for this Emacs
@@ -267,6 +294,10 @@ value is saved to its history.  These values can be cycled through,
 the same way one can cycle through the history of commands that read
 user-input in the minibuffer.
 
+Option ~transient-common-command-prefix~ controls the prefix key used
+in the following bindings.  For simplicity's sake the default, {{{kbd(C-x)}}},
+is shown below.
+
 #+attr_texinfo: :compact t
 - Key: C-M-p (transient-history-prev) ::
 - Key: C-x p ::
@@ -354,8 +385,8 @@ For suffixes, 0 is also valid; it means that the suffix is not
 displayed at any level.
 
 The levels of individual transients and/or their individual suffixes
-can be changed interactively, by invoking the transient and then
-pressing {{{kbd(C-x l)}}} to enter the “edit” mode, see below.
+can be changed interactively, by invoking the menu and entering its
+“edit” mode using the command ~transient-set-level~, as described below.
 
 The default level for both transients and their suffixes is 4.  The
 ~transient-default-level~ option only controls the default for
@@ -376,6 +407,10 @@ available even if the user lowers the transient level.
   This option names the file that is used to persist the levels of
   transients and their suffixes between Emacs sessions.
 
+Option ~transient-common-command-prefix~ controls the prefix key used
+in the following bindings.  For simplicity's sake the default, {{{kbd(C-x)}}},
+is shown below.
+
 - Key: C-x l (transient-set-level) ::
 
   This command enters edit mode.  When edit mode is active, then all
@@ -497,7 +532,7 @@ Values]], in [[* Using History]] and in [[* Enabling and Disabling Suffixes]].
 :UNNUMBERED: notoc
 :END:
 
-Also see [[* Common Suffix Commands]].
+Two more essential options are documented in [[* Common Suffix Commands]].
 
 - User Option: transient-show-popup ::
 
@@ -520,17 +555,6 @@ Also see [[* Common Suffix Commands]].
     the popup is shown after that many seconds of inactivity (using
     the absolute value).
 
-- User Option: transient-show-common-commands ::
-
-  This option controls whether shared suffix commands are shown
-  alongside the transient-specific infix and suffix commands.  By
-  default, the shared commands are not shown to avoid overwhelming
-  the user with too many options.
-
-  While a transient is active, pressing {{{kbd(C-x)}}} always shows the common
-  commands.  The value of this option can be changed for the current
-  Emacs session by typing {{{kbd(C-x t)}}} while a transient is active.
-
 - User Option: transient-show-during-minibuffer-read ::
 
   This option controls whether the transient menu continues to be
@@ -2627,51 +2651,6 @@ See https://github.com/magit/transient/wiki/Comparison-with-prefix-keys-and-univ
 
 See https://github.com/magit/transient/wiki/Comparison-with-other-packages.
 
-** Why did some of the key bindings change?
-:PROPERTIES:
-:UNNUMBERED: notoc
-:END:
-
-You may have noticed that the bindings for some of the common commands
-do *not* have the prefix {{{kbd(C-x)}}} and that furthermore some of these commands
-are grayed out while others are not.  That unfortunately is a bit
-confusing if the section of common commands is not shown permanently,
-making the following explanation necessary.
-
-The purpose of usually hiding that section but showing it after the
-user pressed the respective prefix key is to conserve space and not
-overwhelm users with too much noise, while allowing the user to
-quickly list common bindings on demand.
-
-That however should not keep us from using the best possible key
-bindings.  The bindings that do use a prefix do so to avoid wasting
-too many non-prefix bindings, keeping them available for use in
-individual transients.  The bindings that do not use a prefix and that
-are *not* grayed out are very important bindings that are *always*
-available, even when invoking the “common command key prefix” or *any
-other* transient-specific prefix.  The non-prefix keys that *are* grayed
-out however, are not available when any incomplete prefix key sequence
-is active.  They do not use the “common command key prefix” because it
-is likely that users want to invoke them several times in a row and
-e.g., {{{kbd(M-p M-p M-p)}}} is much more convenient than {{{kbd(C-x M-p C-x M-p C-x M-p)}}}.
-
-You may also have noticed that the “Set” command is bound to {{{kbd(C-x s)}}},
-while Magit-Popup used to bind {{{kbd(C-c C-c)}}} instead.  I have seen several
-users praise the latter binding (sic), so I did not change it
-willy-nilly.  The reason that I changed it is that using different
-prefix keys for different common commands, would have made the
-temporary display of the common commands even more confusing, i.e.,
-after pressing {{{kbd(C-c)}}} all the bindings that begin with the {{{kbd(C-x)}}} prefix
-would be grayed out.
-
-Using a single prefix for common commands key means that all other
-potential prefix keys can be used for transient-specific commands
-*without* the section of common commands also popping up.  {{{kbd(C-c)}}} in
-particular is a prefix that I want to (and already do) use for Magit, and
-also using that for a common command would prevent me from doing so.
-
-(See also the next question.)
-
 ** Why does {{{kbd(q)}}} not quit popups anymore?
 :PROPERTIES:
 :UNNUMBERED: notoc