branch: externals/transient
commit 3f103b67789f0ec54009b5465f8ca66beee3a217
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
docs: Relegate the old introduction and introduce the term "menu"
---
README.org | 52 +---------
docs/transient.org | 270 +++++++++++++++++++++------------------------------
docs/transient.texi | 275 +++++++++++++++++++++-------------------------------
lisp/transient.el | 24 +----
4 files changed, 231 insertions(+), 390 deletions(-)
diff --git a/README.org b/README.org
index 160471f52b..874f00c936 100644
--- a/README.org
+++ b/README.org
@@ -1,52 +1,8 @@
-* Transient commands
+* Transient command menus
-Taking inspiration from prefix keys and prefix arguments, Transient
-implements a similar abstraction involving a prefix command, infix
-arguments and suffix commands. We could call this abstraction a
-"transient command", but because it always involves at least two
-commands (a prefix and a suffix) we prefer to call it just a
-"transient".
-
-#+begin_quote
- Transient keymaps are a feature provided by Emacs. Transients as
- implemented by this package involve the use of transient keymaps.
-
- Emacs provides a feature that it calls "prefix commands". When we
- talk about "prefix commands" in Transient's documentation, then we
- mean our own kind of "prefix commands", unless specified otherwise.
- To avoid ambiguity we sometimes use the terms "transient prefix
- command" for our kind and "regular prefix command" for Emacs' kind.
-#+end_quote
-
-When the user calls a transient prefix command, then a transient
-(temporary) keymap is activated, which binds the transient's infix and
-suffix commands, and functions that control the transient state are
-added to ~pre-command-hook~ and ~post-command-hook~. The available
-suffix and infix commands and their state are shown in a popup buffer
-until the transient is exited by invoking a suffix command.
-
-Calling an infix command causes its value to be changed. How that is
-done depends on the type of the infix command. The simplest case is
-an infix command that represents a command-line argument that does not
-take a value. Invoking such an infix command causes the switch to be
-toggled on or off. More complex infix commands may read a value from
-the user, using the minibuffer.
-
-Calling a suffix command usually causes the transient to be exited;
-the transient keymaps and hook functions are removed, the popup buffer
-no longer shows information about the (no longer bound) suffix
-commands, the values of some public global variables are set, while
-some internal global variables are unset, and finally the command is
-actually called. Suffix commands can also be configured to not exit
-the transient.
-
-A suffix command can, but does not have to, use the infix arguments in
-much the same way it can choose to use or ignore the prefix arguments.
-For a suffix command that was invoked from a transient the variable
-~transient-current-suffixes~ and the function ~transient-args~ serve about
-the same purpose as the variables ~prefix-arg~ and ~current-prefix-arg~ do
-for any command that was called after the prefix arguments have been
-set using a command such as ~universal-argument~.
+Transient is the library used to implement the keyboard-driven “menus”
+in [[https://github.com/magit/magit/][Magit]]. It is distributed as a
separate package, so that it can be
+used to implement similar menus in [[https://melpa.org/#/transient][other
packages]].
[[http://readme.emacsair.me/transient.png]]
diff --git a/docs/transient.org b/docs/transient.org
index 7153d4aa2a..78c1f04a50 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -11,33 +11,13 @@
#+setupfile: .orgconfig
-Taking inspiration from prefix keys and prefix arguments, Transient
-implements a similar abstraction involving a prefix command, infix
-arguments and suffix commands. We could call this abstraction a
-“transient command”, but because it always involves at least two
-commands (a prefix and a suffix) we prefer to call it just a
-“transient”.
-
-When the user calls a transient prefix command, a transient
-(temporary) keymap is activated, which binds the transient's infix
-and suffix commands, and functions that control the transient state
-are added to ~pre-command-hook~ and ~post-command-hook~. The available
-suffix and infix commands and their state are shown in a popup buffer
-until the transient is exited by invoking a suffix command.
+Transient is the library used to implement the keyboard-driven “menus”
+in Magit. It is distributed as a separate package, so that it can be
+used to implement similar menus in other packages.
-Calling an infix command causes its value to be changed, possibly by
-reading a new value in the minibuffer.
-
-Calling a suffix command usually causes the transient to be exited
-but suffix commands can also be configured to not exit the transient.
-
-#+begin_quote
-The second part of this manual, which describes how to modify existing
-transients and create new transients from scratch, can be hard to
-digest if you are just getting started. A useful resource to get over
-that hurdle is Psionic K's interactive tutorial, available at
-https://github.com/positron-solutions/transient-showcase.
-#+end_quote
+This manual can be bit hard to digest when getting started. A useful
+resource to get over that hurdle is Psionic K's interactive tutorial,
+available at https://github.com/positron-solutions/transient-showcase.
#+texinfo: @noindent
This manual is for Transient version 0.5.0.
@@ -46,140 +26,13 @@ This manual is for Transient version 0.5.0.
:END:
* Introduction
-Taking inspiration from prefix keys and prefix arguments, Transient
-implements a similar abstraction involving a prefix command, infix
-arguments and suffix commands. We could call this abstraction a
-“transient command”, but because it always involves at least two
-commands (a prefix and a suffix) we prefer to call it just a
-“transient”.
-
-#+cindex: transient prefix command
-#+begin_quote
-Transient keymaps are a feature provided by Emacs. Transients as
-implemented by this package involve the use of transient keymaps.
-
-Emacs provides a feature that it calls {{{dfn(prefix commands)}}}. When we
-talk about “prefix commands” in this manual, then we mean our own kind
-of “prefix commands”, unless specified otherwise. To avoid ambiguity
-we sometimes use the terms {{{dfn(transient prefix command)}}} for our kind and
-“regular prefix command” for Emacs' kind.
-#+end_quote
-
-When the user calls a transient prefix command, a transient
-(temporary) keymap is activated, which binds the transient's infix and
-suffix commands, and functions that control the transient state are
-added to ~pre-command-hook~ and ~post-command-hook~. The available suffix
-and infix commands and their state are shown in a popup buffer until
-the transient state is exited by invoking a suffix command.
-
-Calling an infix command causes its value to be changed. How that is
-done depends on the type of the infix command. The simplest case is
-an infix command that represents a command-line argument that does not
-take a value. Invoking such an infix command causes the switch to be
-toggled on or off. More complex infix commands may read a value from
-the user, using the minibuffer.
-
-Calling a suffix command usually causes the transient to be exited;
-the transient keymaps and hook functions are removed, the popup buffer
-no longer shows information about the (no longer bound) suffix
-commands, the values of some public global variables are set, while
-some internal global variables are unset, and finally the command is
-actually called. Suffix commands can also be configured to not exit
-the transient.
-
-A suffix command can, but does not have to, use the infix arguments in
-much the same way any command can choose to use or ignore the prefix
-arguments. For a suffix command that was invoked from a transient, the
-variable ~transient-current-suffixes~ and the function ~transient-args~
-serve about the same purpose as the variables ~prefix-arg~ and
-~current-prefix-arg~ do for any command that was called after the prefix
-arguments have been set using a command such as ~universal-argument~.
-
-The information shown in the popup buffer while a transient is active
-looks a bit like this:
-
-#+begin_example
-,-----------------------------------------
-|Arguments
-| -f Force (--force)
-| -a Annotate (--annotate)
-|
-|Create
-| t tag
-| r release
-`-----------------------------------------
-#+end_example
+Transient is the library used to implement the keyboard-driven {{{dfn(menus)}}}
+in Magit. It is distributed as a separate package, so that it can be
+used to implement similar menus in other packages.
-#+begin_quote
-This is a simplified version of ~magit-tag~. Info manuals do not
-support images or colored text, so the above “screenshot” lacks some
-information; in practice you would be able to tell whether the
-arguments ~--force~ and ~--annotate~ are enabled or not, based on their
-color.
-#+end_quote
-
-#+cindex: command dispatchers
-Transient can be used to implement simple “command dispatchers”. The
-main benefit then is that the user can see all the available commands
-in a popup buffer, which can be thought of as a “menus”. That is
-useful by itself because it frees the user from having to remember all
-the keys that are valid after a certain prefix key or command.
-Magit's ~magit-dispatch~ (on {{{kbd(C-x M-g)}}}) command is an example of using
-Transient to merely implement a command dispatcher.
-
-In addition to that, Transient also allows users to interactively pass
-arguments to commands. These arguments can be much more complex than
-what is reasonable when using prefix arguments. There is a limit to
-how many aspects of a command can be controlled using prefix
-arguments. Furthermore, what a certain prefix argument means for
-different commands can be completely different, and users have to read
-documentation to learn and then commit to memory what a certain prefix
-argument means to a certain command.
-
-Transient suffix commands, on the other hand, can accept dozens of
-different arguments without the user having to remember anything.
-When using Transient, one can call a command with arguments that are
-just as complex as when calling the same function non-interactively
-from Lisp.
-
-Invoking a transient suffix command with arguments is similar to
-invoking a command in a shell with command-line completion and history
-enabled. One benefit of the Transient interface is that it remembers
-history not only on a global level (“this command was invoked using
-these arguments, and previously it was invoked using those other
-arguments”), but also remembers the values of individual arguments
-independently. See [[*Using History]].
-
-After a transient prefix command is invoked, {{{kbdvar(C-h <KEY>)}}} can be
used to
-show the documentation for the infix or suffix command that
{{{kbdvar(<KEY>)}}} is
-bound to (see [[*Getting Help for Suffix Commands]]), and infixes and
-suffixes can be removed from the transient using {{{kbdvar(C-x l <KEY>)}}}.
Infixes
-and suffixes that are disabled by default can be enabled the same way.
-See [[*Enabling and Disabling Suffixes]].
-
-Transient ships with support for a few different types of specialized
-infix commands. A command that sets a command line option, for example,
-has different needs than a command that merely toggles a boolean flag.
-Additionally, Transient provides abstractions for defining new types,
-which the author of Transient did not anticipate (or didn't get around
-to implementing yet).
-
-Note that suffix commands also support regular prefix arguments. A
-suffix command may even be called with both infix and prefix arguments
-at the same time. If you invoke a command as a suffix of a transient
-prefix command, but also want to pass prefix arguments to it, then
-first invoke the prefix command, and only after doing that invoke the
-prefix arguments, before finally invoking the suffix command. If you
-instead began by providing the prefix arguments, then those would
-apply to the prefix command, not the suffix command. Likewise, if you
-want to change infix arguments before invoking a suffix command with
-prefix arguments, then change the infix arguments before invoking the
-prefix arguments. In other words, regular prefix arguments always
-apply to the next command, and since transient prefix, infix and
-suffix commands are just regular commands, the same applies to them.
-(Regular prefix keys behave differently because they are not commands
-at all, instead they are just incomplete key sequences, and those
-cannot be interrupted with prefix commands.)
+This manual can be bit hard to digest when getting started. A useful
+resource to get over that hurdle is Psionic K's interactive tutorial,
+available at https://github.com/positron-solutions/transient-showcase.
* Usage
** Invoking Transients
@@ -850,6 +703,105 @@ functions only ~transient-get-suffix~ and
~transient-suffix-put~ may
signal an error.
* Defining New Commands
+** Technical Introduction
+
+Taking inspiration from prefix keys and prefix arguments, Transient
+implements a similar abstraction involving a prefix command, infix
+arguments and suffix commands.
+
+When the user calls a transient prefix command, a transient
+(temporary) keymap is activated, which binds the transient's infix and
+suffix commands, and functions that control the transient state are
+added to ~pre-command-hook~ and ~post-command-hook~. The available suffix
+and infix commands and their state are shown in a popup buffer until
+the transient state is exited by invoking a suffix command.
+
+Calling an infix command causes its value to be changed. How that is
+done depends on the type of the infix command. The simplest case is
+an infix command that represents a command-line argument that does not
+take a value. Invoking such an infix command causes the switch to be
+toggled on or off. More complex infix commands may read a value from
+the user, using the minibuffer.
+
+Calling a suffix command usually causes the transient to be exited;
+the transient keymaps and hook functions are removed, the popup buffer
+no longer shows information about the (no longer bound) suffix
+commands, the values of some public global variables are set, while
+some internal global variables are unset, and finally the command is
+actually called. Suffix commands can also be configured to not exit
+the transient.
+
+A suffix command can, but does not have to, use the infix arguments in
+much the same way any command can choose to use or ignore the prefix
+arguments. For a suffix command that was invoked from a transient, the
+variable ~transient-current-suffixes~ and the function ~transient-args~
+serve about the same purpose as the variables ~prefix-arg~ and
+~current-prefix-arg~ do for any command that was called after the prefix
+arguments have been set using a command such as ~universal-argument~.
+
+#+cindex: command dispatchers
+Transient can be used to implement simple “command dispatchers”. The
+main benefit then is that the user can see all the available commands
+in a popup buffer, which can be thought of as a “menus”. That is
+useful by itself because it frees the user from having to remember all
+the keys that are valid after a certain prefix key or command.
+Magit's ~magit-dispatch~ (on {{{kbd(C-x M-g)}}}) command is an example of using
+Transient to merely implement a command dispatcher.
+
+In addition to that, Transient also allows users to interactively pass
+arguments to commands. These arguments can be much more complex than
+what is reasonable when using prefix arguments. There is a limit to
+how many aspects of a command can be controlled using prefix
+arguments. Furthermore, what a certain prefix argument means for
+different commands can be completely different, and users have to read
+documentation to learn and then commit to memory what a certain prefix
+argument means to a certain command.
+
+Transient suffix commands, on the other hand, can accept dozens of
+different arguments without the user having to remember anything.
+When using Transient, one can call a command with arguments that are
+just as complex as when calling the same function non-interactively
+from Lisp.
+
+Invoking a transient suffix command with arguments is similar to
+invoking a command in a shell with command-line completion and history
+enabled. One benefit of the Transient interface is that it remembers
+history not only on a global level (“this command was invoked using
+these arguments, and previously it was invoked using those other
+arguments”), but also remembers the values of individual arguments
+independently. See [[*Using History]].
+
+After a transient prefix command is invoked, {{{kbdvar(C-h <KEY>)}}} can be
used to
+show the documentation for the infix or suffix command that
{{{kbdvar(<KEY>)}}} is
+bound to (see [[*Getting Help for Suffix Commands]]), and infixes and
+suffixes can be removed from the transient using {{{kbdvar(C-x l <KEY>)}}}.
Infixes
+and suffixes that are disabled by default can be enabled the same way.
+See [[*Enabling and Disabling Suffixes]].
+
+Transient ships with support for a few different types of specialized
+infix commands. A command that sets a command line option, for example,
+has different needs than a command that merely toggles a boolean flag.
+Additionally, Transient provides abstractions for defining new types,
+which the author of Transient did not anticipate (or didn't get around
+to implementing yet).
+
+Note that suffix commands also support regular prefix arguments. A
+suffix command may even be called with both infix and prefix arguments
+at the same time. If you invoke a command as a suffix of a transient
+prefix command, but also want to pass prefix arguments to it, then
+first invoke the prefix command, and only after doing that invoke the
+prefix arguments, before finally invoking the suffix command. If you
+instead began by providing the prefix arguments, then those would
+apply to the prefix command, not the suffix command. Likewise, if you
+want to change infix arguments before invoking a suffix command with
+prefix arguments, then change the infix arguments before invoking the
+prefix arguments. In other words, regular prefix arguments always
+apply to the next command, and since transient prefix, infix and
+suffix commands are just regular commands, the same applies to them.
+(Regular prefix keys behave differently because they are not commands
+at all, instead they are just incomplete key sequences, and those
+cannot be interrupted with prefix commands.)
+
** Defining Transients
A transient consists of a prefix command and at least one suffix
diff --git a/docs/transient.texi b/docs/transient.texi
index 5dc809826f..f128819c55 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -44,34 +44,13 @@ General Public License for more details.
@node Top
@top Transient User and Developer Manual
-Taking inspiration from prefix keys and prefix arguments, Transient
-implements a similar abstraction involving a prefix command, infix
-arguments and suffix commands. We could call this abstraction a
-``transient command'', but because it always involves at least two
-commands (a prefix and a suffix) we prefer to call it just a
-``transient''.
-
-When the user calls a transient prefix command, a transient
-(temporary) keymap is activated, which binds the transient's infix
-and suffix commands, and functions that control the transient state
-are added to @code{pre-command-hook} and @code{post-command-hook}. The
available
-suffix and infix commands and their state are shown in a popup buffer
-until the transient is exited by invoking a suffix command.
-
-Calling an infix command causes its value to be changed, possibly by
-reading a new value in the minibuffer.
-
-Calling a suffix command usually causes the transient to be exited
-but suffix commands can also be configured to not exit the transient.
-
-@quotation
-The second part of this manual, which describes how to modify existing
-transients and create new transients from scratch, can be hard to
-digest if you are just getting started. A useful resource to get over
-that hurdle is Psionic K's interactive tutorial, available at
-@uref{https://github.com/positron-solutions/transient-showcase}.
+Transient is the library used to implement the keyboard-driven ``menus''
+in Magit. It is distributed as a separate package, so that it can be
+used to implement similar menus in other packages.
-@end quotation
+This manual can be bit hard to digest when getting started. A useful
+resource to get over that hurdle is Psionic K's interactive tutorial,
+available at @uref{https://github.com/positron-solutions/transient-showcase}.
@noindent
This manual is for Transient version 0.5.0.
@@ -109,6 +88,7 @@ Usage
Defining New Commands
+* Technical Introduction::
* Defining Transients::
* Binding Suffix and Infix Commands::
* Defining Suffix and Infix Commands::
@@ -144,142 +124,13 @@ Suffix Methods
@node Introduction
@chapter Introduction
-Taking inspiration from prefix keys and prefix arguments, Transient
-implements a similar abstraction involving a prefix command, infix
-arguments and suffix commands. We could call this abstraction a
-``transient command'', but because it always involves at least two
-commands (a prefix and a suffix) we prefer to call it just a
-``transient''.
-
-@cindex transient prefix command
-@quotation
-Transient keymaps are a feature provided by Emacs. Transients as
-implemented by this package involve the use of transient keymaps.
-
-Emacs provides a feature that it calls @dfn{prefix commands}. When we
-talk about ``prefix commands'' in this manual, then we mean our own kind
-of ``prefix commands'', unless specified otherwise. To avoid ambiguity
-we sometimes use the terms @dfn{transient prefix command} for our kind and
-``regular prefix command'' for Emacs' kind.
+Transient is the library used to implement the keyboard-driven @dfn{menus}
+in Magit. It is distributed as a separate package, so that it can be
+used to implement similar menus in other packages.
-@end quotation
-
-When the user calls a transient prefix command, a transient
-(temporary) keymap is activated, which binds the transient's infix and
-suffix commands, and functions that control the transient state are
-added to @code{pre-command-hook} and @code{post-command-hook}. The available
suffix
-and infix commands and their state are shown in a popup buffer until
-the transient state is exited by invoking a suffix command.
-
-Calling an infix command causes its value to be changed. How that is
-done depends on the type of the infix command. The simplest case is
-an infix command that represents a command-line argument that does not
-take a value. Invoking such an infix command causes the switch to be
-toggled on or off. More complex infix commands may read a value from
-the user, using the minibuffer.
-
-Calling a suffix command usually causes the transient to be exited;
-the transient keymaps and hook functions are removed, the popup buffer
-no longer shows information about the (no longer bound) suffix
-commands, the values of some public global variables are set, while
-some internal global variables are unset, and finally the command is
-actually called. Suffix commands can also be configured to not exit
-the transient.
-
-A suffix command can, but does not have to, use the infix arguments in
-much the same way any command can choose to use or ignore the prefix
-arguments. For a suffix command that was invoked from a transient, the
-variable @code{transient-current-suffixes} and the function
@code{transient-args}
-serve about the same purpose as the variables @code{prefix-arg} and
-@code{current-prefix-arg} do for any command that was called after the prefix
-arguments have been set using a command such as @code{universal-argument}.
-
-The information shown in the popup buffer while a transient is active
-looks a bit like this:
-
-@example
-,-----------------------------------------
-|Arguments
-| -f Force (--force)
-| -a Annotate (--annotate)
-|
-|Create
-| t tag
-| r release
-`-----------------------------------------
-@end example
-
-@quotation
-This is a simplified version of @code{magit-tag}. Info manuals do not
-support images or colored text, so the above ``screenshot'' lacks some
-information; in practice you would be able to tell whether the
-arguments @code{--force} and @code{--annotate} are enabled or not, based on
their
-color.
-
-@end quotation
-
-@cindex command dispatchers
-Transient can be used to implement simple ``command dispatchers''. The
-main benefit then is that the user can see all the available commands
-in a popup buffer, which can be thought of as a ``menus''. That is
-useful by itself because it frees the user from having to remember all
-the keys that are valid after a certain prefix key or command.
-Magit's @code{magit-dispatch} (on @kbd{C-x M-g}) command is an example of using
-Transient to merely implement a command dispatcher.
-
-In addition to that, Transient also allows users to interactively pass
-arguments to commands. These arguments can be much more complex than
-what is reasonable when using prefix arguments. There is a limit to
-how many aspects of a command can be controlled using prefix
-arguments. Furthermore, what a certain prefix argument means for
-different commands can be completely different, and users have to read
-documentation to learn and then commit to memory what a certain prefix
-argument means to a certain command.
-
-Transient suffix commands, on the other hand, can accept dozens of
-different arguments without the user having to remember anything.
-When using Transient, one can call a command with arguments that are
-just as complex as when calling the same function non-interactively
-from Lisp.
-
-Invoking a transient suffix command with arguments is similar to
-invoking a command in a shell with command-line completion and history
-enabled. One benefit of the Transient interface is that it remembers
-history not only on a global level (``this command was invoked using
-these arguments, and previously it was invoked using those other
-arguments''), but also remembers the values of individual arguments
-independently. See @ref{Using History}.
-
-After a transient prefix command is invoked, @kbd{C-h @var{KEY}} can be used to
-show the documentation for the infix or suffix command that @kbd{@var{KEY}} is
-bound to (see @ref{Getting Help for Suffix Commands}), and infixes and
-suffixes can be removed from the transient using @kbd{C-x l @var{KEY}}. Infixes
-and suffixes that are disabled by default can be enabled the same way.
-See @ref{Enabling and Disabling Suffixes}.
-
-Transient ships with support for a few different types of specialized
-infix commands. A command that sets a command line option, for example,
-has different needs than a command that merely toggles a boolean flag.
-Additionally, Transient provides abstractions for defining new types,
-which the author of Transient did not anticipate (or didn't get around
-to implementing yet).
-
-Note that suffix commands also support regular prefix arguments. A
-suffix command may even be called with both infix and prefix arguments
-at the same time. If you invoke a command as a suffix of a transient
-prefix command, but also want to pass prefix arguments to it, then
-first invoke the prefix command, and only after doing that invoke the
-prefix arguments, before finally invoking the suffix command. If you
-instead began by providing the prefix arguments, then those would
-apply to the prefix command, not the suffix command. Likewise, if you
-want to change infix arguments before invoking a suffix command with
-prefix arguments, then change the infix arguments before invoking the
-prefix arguments. In other words, regular prefix arguments always
-apply to the next command, and since transient prefix, infix and
-suffix commands are just regular commands, the same applies to them.
-(Regular prefix keys behave differently because they are not commands
-at all, instead they are just incomplete key sequences, and those
-cannot be interrupted with prefix commands.)
+This manual can be bit hard to digest when getting started. A useful
+resource to get over that hurdle is Psionic K's interactive tutorial,
+available at @uref{https://github.com/positron-solutions/transient-showcase}.
@node Usage
@chapter Usage
@@ -1005,6 +856,106 @@ signal an error.
@node Defining New Commands
@chapter Defining New Commands
+@node Technical Introduction
+@section Technical Introduction
+
+Taking inspiration from prefix keys and prefix arguments, Transient
+implements a similar abstraction involving a prefix command, infix
+arguments and suffix commands.
+
+When the user calls a transient prefix command, a transient
+(temporary) keymap is activated, which binds the transient's infix and
+suffix commands, and functions that control the transient state are
+added to @code{pre-command-hook} and @code{post-command-hook}. The available
suffix
+and infix commands and their state are shown in a popup buffer until
+the transient state is exited by invoking a suffix command.
+
+Calling an infix command causes its value to be changed. How that is
+done depends on the type of the infix command. The simplest case is
+an infix command that represents a command-line argument that does not
+take a value. Invoking such an infix command causes the switch to be
+toggled on or off. More complex infix commands may read a value from
+the user, using the minibuffer.
+
+Calling a suffix command usually causes the transient to be exited;
+the transient keymaps and hook functions are removed, the popup buffer
+no longer shows information about the (no longer bound) suffix
+commands, the values of some public global variables are set, while
+some internal global variables are unset, and finally the command is
+actually called. Suffix commands can also be configured to not exit
+the transient.
+
+A suffix command can, but does not have to, use the infix arguments in
+much the same way any command can choose to use or ignore the prefix
+arguments. For a suffix command that was invoked from a transient, the
+variable @code{transient-current-suffixes} and the function
@code{transient-args}
+serve about the same purpose as the variables @code{prefix-arg} and
+@code{current-prefix-arg} do for any command that was called after the prefix
+arguments have been set using a command such as @code{universal-argument}.
+
+@cindex command dispatchers
+Transient can be used to implement simple ``command dispatchers''. The
+main benefit then is that the user can see all the available commands
+in a popup buffer, which can be thought of as a ``menus''. That is
+useful by itself because it frees the user from having to remember all
+the keys that are valid after a certain prefix key or command.
+Magit's @code{magit-dispatch} (on @kbd{C-x M-g}) command is an example of using
+Transient to merely implement a command dispatcher.
+
+In addition to that, Transient also allows users to interactively pass
+arguments to commands. These arguments can be much more complex than
+what is reasonable when using prefix arguments. There is a limit to
+how many aspects of a command can be controlled using prefix
+arguments. Furthermore, what a certain prefix argument means for
+different commands can be completely different, and users have to read
+documentation to learn and then commit to memory what a certain prefix
+argument means to a certain command.
+
+Transient suffix commands, on the other hand, can accept dozens of
+different arguments without the user having to remember anything.
+When using Transient, one can call a command with arguments that are
+just as complex as when calling the same function non-interactively
+from Lisp.
+
+Invoking a transient suffix command with arguments is similar to
+invoking a command in a shell with command-line completion and history
+enabled. One benefit of the Transient interface is that it remembers
+history not only on a global level (``this command was invoked using
+these arguments, and previously it was invoked using those other
+arguments''), but also remembers the values of individual arguments
+independently. See @ref{Using History}.
+
+After a transient prefix command is invoked, @kbd{C-h @var{KEY}} can be used to
+show the documentation for the infix or suffix command that @kbd{@var{KEY}} is
+bound to (see @ref{Getting Help for Suffix Commands}), and infixes and
+suffixes can be removed from the transient using @kbd{C-x l @var{KEY}}. Infixes
+and suffixes that are disabled by default can be enabled the same way.
+See @ref{Enabling and Disabling Suffixes}.
+
+Transient ships with support for a few different types of specialized
+infix commands. A command that sets a command line option, for example,
+has different needs than a command that merely toggles a boolean flag.
+Additionally, Transient provides abstractions for defining new types,
+which the author of Transient did not anticipate (or didn't get around
+to implementing yet).
+
+Note that suffix commands also support regular prefix arguments. A
+suffix command may even be called with both infix and prefix arguments
+at the same time. If you invoke a command as a suffix of a transient
+prefix command, but also want to pass prefix arguments to it, then
+first invoke the prefix command, and only after doing that invoke the
+prefix arguments, before finally invoking the suffix command. If you
+instead began by providing the prefix arguments, then those would
+apply to the prefix command, not the suffix command. Likewise, if you
+want to change infix arguments before invoking a suffix command with
+prefix arguments, then change the infix arguments before invoking the
+prefix arguments. In other words, regular prefix arguments always
+apply to the next command, and since transient prefix, infix and
+suffix commands are just regular commands, the same applies to them.
+(Regular prefix keys behave differently because they are not commands
+at all, instead they are just incomplete key sequences, and those
+cannot be interrupted with prefix commands.)
+
@node Defining Transients
@section Defining Transients
diff --git a/lisp/transient.el b/lisp/transient.el
index d5ef863ba7..baba2569b6 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -28,27 +28,9 @@
;;; Commentary:
-;; Taking inspiration from prefix keys and prefix arguments, Transient
-;; implements a similar abstraction involving a prefix command, infix
-;; arguments and suffix commands. We could call this abstraction a
-;; "transient command", but because it always involves at least two
-;; commands (a prefix and a suffix) we prefer to call it just a
-;; "transient".
-
-;; When the user calls a transient prefix command, then a transient
-;; (temporary) keymap is activated, which binds the transient's infix
-;; and suffix commands, and functions that control the transient state
-;; are added to `pre-command-hook' and `post-command-hook'. The
-;; available suffix and infix commands and their state are shown in
-;; the echo area until the transient is exited by invoking a suffix
-;; command.
-
-;; Calling an infix command causes its value to be changed, possibly
-;; by reading a new value in the minibuffer.
-
-;; Calling a suffix command usually causes the transient to be exited
-;; but suffix commands can also be configured to not exit the
-;; transient state.
+;; Transient is the library used to implement the keyboard-driven menus
+;; in Magit. It is distributed as a separate package, so that it can be
+;; used to implement similar menus in other packages.
;;; Code:
