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
+“transient command”, but because it always involves at least two
commands (a prefix and a suffix) we prefer to call it just a
-``transient''.
+“transient”.
When the user calls a transient prefix command, a transient
(temporary) keymap is activated, which binds the transient's infix
* Getting Help for Suffix Commands::
* Enabling and Disabling Suffixes::
* Other Commands::
-* Other Options::
+* Configuration::
Defining New Commands
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
+“transient command”, but because it always involves at least two
commands (a prefix and a suffix) we prefer to call it just a
-``transient''.
+“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.
-@cindex transient prefix command
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
+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 the Emacs' kind.
+“regular prefix command” for Emacs' kind.
@end quotation
@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
+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
+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. 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 @code{C-x M-g}) command is
+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.
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
+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 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''),
+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.
@xref{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
+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 (@pxref{Getting Help for Suffix Commands}), and infixes and
-suffixes can be removed from the transient using @kbd{C-x l @var{key}}. Infixes
+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.
@xref{Enabling and Disabling Suffixes}.
* Getting Help for Suffix Commands::
* Enabling and Disabling Suffixes::
* Other Commands::
-* Other Options::
+* Configuration::
@end menu
@node Invoking Transients
@section Invoking Transients
+
@cindex invoking transients
A transient prefix command is invoked like any other command by
There are two kinds of commands that are available after invoking a
transient prefix command; infix and suffix commands. Infix commands
set some value (which is then shown in a popup buffer), without
-leaving the transient. Suffix commands, on the other hand, usually quit
-the transient and they may use the values set by the infix commands,
-i.e.@: the infix @strong{arguments}.
+leaving the transient. Suffix commands, on the other hand, usually
+quit the transient and they may use the values set by the infix
+commands, i.e., the infix @strong{arguments}.
Instead of setting arguments to be used by a suffix command, infix
commands may also set some value by side-effect, e.g., by setting the
@node Aborting and Resuming Transients
@section Aborting and Resuming Transients
+
@cindex aborting transients
@cindex resuming transients
@cindex quit transient
-To quit the transient without invoking a suffix command press @code{C-g}.
+To quit the transient without invoking a suffix command press @kbd{C-g}.
Key bindings in transient keymaps may be longer than a single event.
After pressing a valid prefix key, all commands whose bindings do not
A transient prefix command can be bound as a suffix of another
transient. Invoking such a suffix replaces the current transient
-state with a new transient state, i.e.@: the available bindings change
+state with a new transient state, i.e., the available bindings change
and the information displayed in the popup buffer is updated
accordingly. Pressing @kbd{C-g} while a nested transient is active only
quits the innermost transient, causing a return to the previous
@kbd{M-x transient-resume}.
@table @asis
+@item @kbd{C-g} (@code{transient-quit-seq})
+@itemx @kbd{C-g} (@code{transient-quit-one})
@kindex C-g
-@findex transient-quit-seq
-@item @kbd{C-g} @tie{}@tie{}@tie{}@tie{}(@code{transient-quit-seq})
@kindex C-g
+@findex transient-quit-seq
@findex transient-quit-one
-@item @kbd{C-g} @tie{}@tie{}@tie{}@tie{}(@code{transient-quit-one})
-
This key quits the currently active incomplete key sequence, if any,
or else the current transient. When quitting the current transient,
it returns to the previous transient, if any.
doc string.
@table @asis
+@item @kbd{C-q} (@code{transient-quit-all})
@kindex C-q
@findex transient-quit-all
-@item @kbd{C-q} @tie{}@tie{}@tie{}@tie{}(@code{transient-quit-all})
-
This command quits the currently active incomplete key sequence, if
any, and all transients, including the active transient and all
suspended transients, if any.
+@item @kbd{C-z} (@code{transient-suspend})
@kindex C-z
@findex transient-suspend
-@item @kbd{C-z} @tie{}@tie{}@tie{}@tie{}(@code{transient-suspend})
-
Like @code{transient-quit-all}, this command quits an incomplete key
sequence, if any, and all transients. Additionally, it saves the
stack of transients so that it can easily be resumed (which is
-particularly useful if you quickly need to do ``something else'', and
+particularly useful if you quickly need to do “something else” and
the stack is deeper than a single transient, and/or you have already
changed the values of some infix arguments).
If another stack is already saved, then saving a new stack discards
the previous stack.
-@kindex M-x transient-resume
+@item @kbd{M-x transient-resume}
@findex transient-resume
-@item @kbd{M-x transient-resume} @tie{}@tie{}@tie{}@tie{}(@code{transient-resume})
-
This command resumes the previously suspended stack of transients,
if any.
@end table
@node Common Suffix Commands
@section Common Suffix Commands
+
@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.
-This includes the aborting commands mentioned in the previous section, as
-well as some other commands that are all bound to @kbd{C-x @var{key}}. After
+This includes the aborting commands mentioned in the previous section,
+as well as some other commands that are all bound to @kbd{C-x @var{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.
+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.
@table @asis
+@item @kbd{C-x t} (@code{transient-toggle-common})
@kindex C-x t
@findex transient-toggle-common
-@item @kbd{C-x t} @tie{}@tie{}@tie{}@tie{}(@code{transient-toggle-common})
-
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.
-
@end table
@defopt 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
Emacs session by typing @kbd{C-x t} while a transient is active.
@end defopt
-The other common commands are described in either the previous or
-in one of the following sections.
+The other common commands are described in either the previous or in
+one of the following sections.
Some of Transient's key bindings differ from the respective bindings
of Magit-Popup; see @ref{FAQ} for more information.
@node Saving Values
@section Saving Values
+
@cindex saving values of arguments
After setting the infix arguments in a transient, the user can save
invoked. There are a few exceptions, though. Some transients are
designed so that the value that they use is stored externally as the
buffer-local value of some variable. Invoking such a transient again
-uses the buffer-local value.@footnote{
-@code{magit-diff} and @code{magit-log} are two prominent examples, and their
+uses the buffer-local value. @footnote{@code{magit-diff} and @code{magit-log} are two prominent examples, and their
handling of buffer-local values is actually a bit more complicated
than outlined above and even customizable.}
but it is easily accessible (@pxref{Using History}).
@table @asis
+@item @kbd{C-x s} (@code{transient-set})
@kindex C-x s
@findex transient-set
-@item @kbd{C-x s} @tie{}@tie{}@tie{}@tie{}(@code{transient-set})
-
This command saves the value of the active transient for this Emacs
session.
+@item @kbd{C-x C-s} (@code{transient-save})
@kindex C-x C-s
@findex transient-save
-@item @kbd{C-x C-s} @tie{}@tie{}@tie{}@tie{}(@code{transient-save})
-
Save the value of the active transient persistently across Emacs
sessions.
+@item @kbd{C-x C-k} (@code{transient-save})
+@kindex C-x C-k
+@findex transient-save
+Clear the set and saved value of the active transient.
@end table
@defopt transient-values-file
-
This option names the file that is used to persist the values of
transients between Emacs sessions.
@end defopt
@node Using History
@section Using History
+
@cindex value history
Every time the user invokes a suffix command the transient's current
user-input in the minibuffer.
@table @asis
+@item @kbd{C-M-p} (@code{transient-history-prev})
+@itemx @kbd{C-x p}
@kindex C-M-p
-@findex transient-history-prev
-@item @kbd{C-M-p} @tie{}@tie{}@tie{}@tie{}(@code{transient-history-prev})
@kindex C-x p
@findex transient-history-prev
-@item @kbd{C-x p} @tie{}@tie{}@tie{}@tie{}(@code{transient-history-prev})
-
This command switches to the previous value used for the active
transient.
+@item @kbd{C-M-n} (@code{transient-history-next})
+@itemx @kbd{C-x n}
@kindex C-M-n
-@findex transient-history-next
-@item @kbd{C-M-n} @tie{}@tie{}@tie{}@tie{}(@code{transient-history-next})
@kindex C-x n
@findex transient-history-next
-@item @kbd{C-x n} @tie{}@tie{}@tie{}@tie{}(@code{transient-history-next})
-
This command switches to the next value used for the active
transient.
@end table
In addition to the transient-wide history, Transient of course
supports per-infix history. When an infix reads user-input using the
-minibuffer, the user can use the regular minibuffer history
-commands to cycle through previously used values. Usually the same
-keys as those mentioned above are bound to those commands.
+minibuffer, the user can use the regular minibuffer history commands
+to cycle through previously used values. Usually the same keys as
+those mentioned above are bound to those commands.
Authors of transients should arrange for different infix commands that
read the same kind of value to also use the same history key
Both kinds of history are saved to a file when Emacs is exited.
@defopt transient-history-file
-
This option names the file that is used to persist the history of
transients and their infixes between Emacs sessions.
@end defopt
@defopt transient-history-limit
-
This option controls how many history elements are kept at the time
the history is saved in @code{transient-history-file}.
@end defopt
@node Getting Help for Suffix Commands
@section Getting Help for Suffix Commands
+
@cindex getting help
Transients can have many suffixes and infixes that the user might not
transient.
@table @asis
+@item @kbd{C-h} (@code{transient-help})
@kindex C-h
@findex transient-help
-@item @kbd{C-h} @tie{}@tie{}@tie{}@tie{}(@code{transient-help})
-
-This command enters help mode. When help mode is active,
-typing a key shows information about the suffix command that the key
-is normally bound to (instead of invoking it). Pressing @kbd{C-h} a
-second time shows information about the @emph{prefix} command.
+This command enters help mode. When help mode is active, typing a
+key shows information about the suffix command that the key normally
+is bound to (instead of invoking it). Pressing @kbd{C-h} a second time
+shows information about the @emph{prefix} command.
After typing a key, the stack of transient states is suspended and
information about the suffix command is shown instead. Typing @kbd{q} in
@node Enabling and Disabling Suffixes
@section Enabling and Disabling Suffixes
+
@cindex enabling suffixes
@cindex disabling suffixes
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.
+pressing @kbd{C-x l} to enter the “edit” mode, see below.
The default level for both transients and their suffixes is 4. The
@code{transient-default-level} option only controls the default for
available even if the user lowers the transient level.
@defopt transient-default-level
-
This option controls which suffix levels are made available by
default. It sets the transient-level for transients for which the
user has not set that individually.
@end defopt
@defopt transient-levels-file
-
This option names the file that is used to persist the levels of
transients and their suffixes between Emacs sessions.
@end defopt
@table @asis
+@item @kbd{C-x l} (@code{transient-set-level})
@kindex C-x l
@findex transient-set-level
-@item @kbd{C-x l} @tie{}@tie{}@tie{}@tie{}(@code{transient-set-level})
-
This command enters edit mode. When edit mode is active, then all
infixes and suffixes that are currently usable are displayed along
with their levels. The colors of the levels indicate whether they
To exit edit mode press @kbd{C-g}.
Note that edit mode does not display any suffixes that are not
-currently usable. @code{magit-rebase}, for example, shows different suffixes
-depending on whether a rebase is already in progress or not. The
-predicates also apply in edit mode.
+currently usable. @code{magit-rebase}, for example, shows different
+suffixes depending on whether a rebase is already in progress or
+not. The predicates also apply in edit mode.
Therefore, to control which suffixes are available given a certain
state, you have to make sure that that state is currently active.
window, and the key bindings are the same as for @code{scroll-up-command} and
@code{scroll-down-command} in other buffers.
-@findex transient-scroll-up arg
@deffn Command transient-scroll-up arg
-
-This command scrolls text of transient popup window upward @var{arg}
-lines. If @var{arg} is @code{nil}, then it scrolls near full screen. This
+This command scrolls text of transient popup window upward @var{ARG}
+lines. If @var{ARG} is @code{nil}, then it scrolls near full screen. This
is a wrapper around @code{scroll-up-command} (which see).
@end deffn
-@findex transient-scroll-down arg
@deffn Command transient-scroll-down arg
-
-This command scrolls text of transient popup window down @var{arg}
-lines. If @var{arg} is @code{nil}, then it scrolls near full screen. This
+This command scrolls text of transient popup window down @var{ARG}
+lines. If @var{ARG} is @code{nil}, then it scrolls near full screen. This
is a wrapper around @code{scroll-down-command} (which see).
@end deffn
-@node Other Options
-@section Other Options
+@node Configuration
+@section Configuration
-@defopt transient-show-popup
+More options are described in @ref{Common Suffix Commands}, in @ref{Saving Values}, in @ref{Using History} and in @ref{Enabling and Disabling Suffixes}.
+
+@anchor{Essential Options}
+@subheading Essential Options
+
+Also see @ref{Common Suffix Commands}.
+@defopt transient-show-popup
This option controls whether the current transient's infix and
suffix commands are shown in the popup buffer.
If @code{t} (the default) then the popup buffer is shown as soon as a
transient prefix command is invoked.
-
@item
If @code{nil}, then the popup buffer is not shown unless the user
explicitly requests it, by pressing an incomplete prefix key
sequence.
-
@item
If a number, then the a brief one-line summary is shown instead of
the popup buffer. If zero or negative, then not even that summary
The popup is shown when the user explicitly requests it by
pressing an incomplete prefix key sequence. Unless this is zero,
-the popup is shown after that many seconds of inactivity
-(using the absolute value).
+the popup is shown after that many seconds of inactivity (using
+the absolute value).
@end itemize
@end defopt
@defopt transient-enable-popup-navigation
-
This option controls whether navigation commands are enabled in the
transient popup buffer.
While a transient is active the transient popup buffer is not the
current buffer, making it necessary to use dedicated commands to act
on that buffer itself. This is disabled by default. If this option
-is non-nil, then the following features are available:
+is non-@code{nil}, then the following features are available:
@itemize
@item
-@key{UP} moves the cursor to the previous suffix.
-@key{DOWN} moves the cursor to the next suffix.
-@key{RET} invokes the suffix the cursor is on.
-
+@kbd{@key{UP}} moves the cursor to the previous suffix.
@item
-@key{mouse-1} invokes the clicked on suffix.
-
+@kbd{@key{DOWN}} moves the cursor to the next suffix.
+@item
+@kbd{@key{RET}} invokes the suffix the cursor is on.
+@item
+@kbd{mouse-1} invokes the clicked on suffix.
@item
@kbd{C-s} and @kbd{C-r} start isearch in the popup buffer.
@end itemize
@end defopt
@defopt transient-display-buffer-action
-
This option specifies the action used to display the transient popup
buffer. The transient popup buffer is displayed in a window using
-@code{(display-buffer @var{buffer} transient-display-buffer-action)}.
+@code{(display-buffer @var{BUFFER} transient-display-buffer-action)}.
-The value of this option has the form @code{(@var{function} . @var{alist})},
-where @var{function} is a function or a list of functions. Each such
+The value of this option has the form @code{(@var{FUNCTION} . @var{ALIST})},
+where @var{FUNCTION} is a function or a list of functions. Each such
function should accept two arguments: a buffer to display and an
-alist of the same form as @var{alist}. @xref{Choosing Window,,,elisp,},
+alist of the same form as @var{ALIST}. @xref{Choosing Window,,,elisp,},
for details.
The default is:
@end lisp
This displays the window at the bottom of the selected frame.
-Another useful @var{function} is @code{display-buffer-below-selected}, which
+Another useful @var{FUNCTION} is @code{display-buffer-below-selected}, which
is what @code{magit-popup} used by default. For more alternatives see
@ref{Buffer Display Action Functions,,,elisp,}, and see @ref{Buffer Display
Action Alists,,,elisp,}.
want to change the value of @code{transient-mode-line-format}.
@end defopt
-@defopt transient-mode-line-format
+@anchor{Accessibility Options}
+@subheading Accessibility Options
+
+@defopt transient-force-single-column
+This option controls whether the use of a single column to display
+suffixes is enforced. This might be useful for users with low
+vision who use large text and might otherwise have to scroll in two
+dimensions.
+@end defopt
+
+@anchor{Auxiliary Options}
+@subheading Auxiliary Options
+@defopt transient-mode-line-format
This option controls whether the transient popup buffer has a
mode-line, separator line, or neither.
If @code{line} (the default), then the buffer also has no mode-line, but a
thin line is drawn instead, using the background color of the face
-@code{transient-separator}. Text-mode frames cannot display thin lines, and
-therefore fall back to treating @code{line} like @code{nil}.
+@code{transient-separator}. Text-mode frames cannot display thin lines,
+and therefore fall back to treating @code{line} like @code{nil}.
Otherwise this can be any mode-line format. @xref{Mode Line
Format,,,elisp,}, for details.
@end defopt
-@defopt transient-read-with-initial-input
+@defopt transient-semantic-coloring
+This option controls whether prefixes and suffixes are colored in
+a Hydra-like fashion.
-This option controls whether the last history element is used as the
-initial minibuffer input when reading the value of an infix argument
-from the user. If @code{nil}, there is no initial input and the first
-element has to be accessed the same way as the older elements.
+If non-@code{nil}, then the key binding of each suffix is colorized to
+indicate whether it exits the transient state or not. The color of
+the prefix is indicated using the line that is drawn when the value
+of @code{transient-mode-line-format} is @code{line}.
+
+For more information about how Hydra uses colors see
+@uref{https://github.com/abo-abo/hydra#color} and
+@uref{https://oremacs.com/2015/02/19/hydra-colors-reloaded}.
@end defopt
@defopt transient-highlight-mismatched-keys
-
This option controls whether key bindings of infix commands that do
not match the respective command-line argument should be highlighted.
For other infix commands this option has no effect.
@end defopt
@defopt transient-substitute-key-function
-
This function is used to modify key bindings. If the value of this
option is @code{nil} (the default), then no substitution is performed.
@end lisp
@end defopt
-@defopt transient-detect-key-conflicts
+@defopt transient-read-with-initial-input
+This option controls whether the last history element is used as the
+initial minibuffer input when reading the value of an infix argument
+from the user. If @code{nil}, there is no initial input and the first
+element has to be accessed the same way as the older elements.
+@end defopt
+
+@defopt transient-hide-during-minibuffer-read
+This option controls whether the transient buffer is hidden while
+user input is being read in the minibuffer.
+@end defopt
+
+@defopt transient-align-variable-pitch
+This option controls whether columns are aligned pixel-wise in the
+popup buffer.
+
+If this is non-@code{nil}, then columns are aligned pixel-wise to support
+variable-pitch fonts. Keys are not aligned, so you should use a
+fixed-pitch font for the @code{transient-key} face. Other key faces
+inherit from that face unless a theme is used that breaks that
+relationship.
+
+This option is intended for users who use a variable-pitch font for
+the @code{default} face.
+@end defopt
+
+@defopt transient-force-fixed-pitch
+This option controls whether to force the use of a monospaced font
+in popup buffer. Even if you use a proportional font for the
+@code{default} face, you might still want to use a monospaced font in
+transient's popup buffer. Setting this option to @code{t} causes @code{default}
+to be remapped to @code{fixed-pitch} in that buffer.
+@end defopt
+
+@anchor{Developer Options}
+@subheading Developer Options
+These options are mainly intended for developers.
+
+@defopt transient-detect-key-conflicts
This option controls whether key binding conflicts should be
-detected at the time the transient is invoked. If so, this
-results in an error, which prevents the transient from being used.
-Because of that, conflicts are ignored by default.
+detected at the time the transient is invoked. If so, this results
+in an error, which prevents the transient from being used. Because
+of that, conflicts are ignored by default.
-Conflicts cannot be determined earlier, i.e.@: when the transient is
+Conflicts cannot be determined earlier, i.e., when the transient is
being defined and when new suffixes are being added, because at that
time there can be false-positives. It is actually valid for
multiple suffixes to share a common key binding, provided the
enabled at a time.
@end defopt
-@defopt transient-force-fixed-pitch
+@defopt transient-highlight-higher-levels
+This option controls whether suffixes that would not be available by
+default are highlighted.
-This option controls whether to force the use of a monospaced font
-in popup buffer. Even if you use a proportional font for the
-@code{default} face, you might still want to use a monospaced font in
-transient's popup buffer. Setting this option to @code{t} causes @code{default}
-to be remapped to @code{fixed-pitch} in that buffer.
+When non-@code{nil} then the descriptions of suffixes are highlighted if
+their level is above 4, the default of @code{transient-default-level}.
+Assuming you have set that variable to 7, this highlights all
+suffixes that won't be available to users without them making the
+same customization.
@end defopt
@node Modifying Existing Transients
@chapter Modifying Existing Transients
+
@cindex modifying existing transients
-To an extent, transients can be customized interactively, see @ref{Enabling and Disabling Suffixes}. This section explains how existing transients
-can be further modified non-interactively.
+To an extent, transients can be customized interactively, see
+@ref{Enabling and Disabling Suffixes}. This section explains how existing
+transients can be further modified non-interactively.
The following functions share a few arguments:
@itemize
@item
-@var{prefix} is a transient prefix command, a symbol.
-
+@var{PREFIX} is a transient prefix command, a symbol.
@item
-@var{suffix} is a transient infix or suffix specification in the same form
+@var{SUFFIX} is a transient infix or suffix specification in the same form
as expected by @code{transient-define-prefix}. Note that an infix is a
-special kind of suffix. Depending on context ``suffixes'' means
-``suffixes (including infixes)'' or ``non-infix suffixes''. Here it
+special kind of suffix. Depending on context “suffixes” means
+“suffixes (including infixes)” or “non-infix suffixes”. Here it
means the former. @xref{Suffix Specifications}.
-@var{suffix} may also be a group in the same form as expected by
+@var{SUFFIX} may also be a group in the same form as expected by
@code{transient-define-prefix}. @xref{Group Specifications}.
@item
-@var{loc} is a command, a key vector, a key description (a string as
+@var{LOC} is a command, a key vector, a key description (a string as
returned by @code{key-description}), or a list specifying coordinates (the
last element may also be a command or key). For example @code{(1 0 -1)}
identifies the last suffix (@code{-1}) of the first subgroup (@code{0}) of the
second group (@code{1}).
-If @var{loc} is a list of coordinates, then it can be used to identify a
+If @var{LOC} is a list of coordinates, then it can be used to identify a
group, not just an individual suffix command.
The function @code{transient-get-suffix} can be useful to determine whether
@end itemize
These functions operate on the information stored in the
-@code{transient--layout} property of the @var{prefix} symbol. Suffix entries in
-that tree are not objects but have the form @code{(@var{level}
-@var{class} @var{plist})}, where
-@var{plist} should set at least @code{:key}, @code{:description} and
-@code{:command}.
-
-@defun transient-insert-suffix prefix loc suffix
+@code{transient--layout} property of the @var{PREFIX} symbol. Suffix entries in
+that tree are not objects but have the form @code{(@var{LEVEL} @var{CLASS} @var{PLIST})}, where
+@var{PLIST} should set at least @code{:key}, @code{:description} and @code{:command}.
-This function inserts suffix or group @var{suffix} into @var{prefix}
-before @var{loc}.
+@defun transient-insert-suffix prefix loc suffix &optional keep-other
@end defun
-
-@defun transient-append-suffix prefix loc suffix
-
-This function inserts suffix or group @var{suffix} into @var{prefix}
-after @var{loc}.
+@defun transient-append-suffix prefix loc suffix &optional keep-other
+These functions insert the suffix or group @var{SUFFIX} into @var{PREFIX} before
+or after @var{LOC}.
+
+Conceptually adding a binding to a transient prefix is similar to
+adding a binding to a keymap, but this is complicated by the fact
+that multiple suffix commands can be bound to the same key, provided
+they are never active at the same time, see @ref{Predicate Slots}.
+
+Unfortunately both false-positives and false-negatives are possible.
+To deal with the former use non-nil @var{KEEP-OTHER@.} To deal with the
+latter remove the conflicting binding explicitly.
@end defun
@defun transient-replace-suffix prefix loc suffix
-
-This function replaces the suffix or group at @var{loc} in @var{prefix} with
-suffix or group @var{suffix}.
+This function replaces the suffix or group at @var{LOC} in @var{PREFIX} with
+suffix or group @var{SUFFIX}.
@end defun
@defun transient-remove-suffix prefix loc
-
-This function removes the suffix or group at @var{loc} in @var{prefix}.
+This function removes the suffix or group at @var{LOC} in @var{PREFIX}.
@end defun
@defun transient-get-suffix prefix loc
-
-This function returns the suffix or group at @var{loc} in @var{prefix}. The
+This function returns the suffix or group at @var{LOC} in @var{PREFIX}. The
returned value has the form mentioned above.
@end defun
@defun transient-suffix-put prefix loc prop value
-
-This function edits the suffix or group at @var{loc} in @var{prefix},
-by setting the @var{prop} of its plist to @var{value}.
+This function edits the suffix or group at @var{LOC} in @var{PREFIX}, by setting
+the @var{PROP} of its plist to @var{VALUE}.
@end defun
Most of these functions do not signal an error if they cannot perform
the requested modification. The functions that insert new suffixes
-show a warning if @var{loc} cannot be found in @var{prefix}, without
-signaling an error. The reason for doing it like this is that
-establishing a key binding (and that is what we essentially are trying
-to do here) should not prevent the rest of the configuration from
-loading. Among these functions only @code{transient-get-suffix} and
-@code{transient-suffix-put} may signal an error.
+show a warning if @var{LOC} cannot be found in @var{PREFIX} without signaling an
+error. The reason for doing it like this is that establishing a key
+binding (and that is what we essentially are trying to do here) should
+not prevent the rest of the configuration from loading. Among these
+functions only @code{transient-get-suffix} and @code{transient-suffix-put} may
+signal an error.
@node Defining New Commands
@chapter Defining New Commands
that is used to invoke that transient.
@defmac transient-define-prefix name arglist [docstring] [keyword value]@dots{} group@dots{} [body@dots{}]
-
-This macro defines @var{name} as a transient prefix command and binds the
+This macro defines @var{NAME} as a transient prefix command and binds the
transient's infix and suffix commands.
-@var{arglist} are the arguments that the prefix command takes.
-@var{docstring} is the documentation string and is optional.
+@var{ARGLIST} are the arguments that the prefix command takes.
+@var{DOCSTRING} is the documentation string and is optional.
These arguments can optionally be followed by keyword-value pairs.
Each key has to be a keyword symbol, either @code{:class} or a keyword
@code{transient-prefix} class is used if the class is not specified
explicitly.
-@var{group}s add key bindings for infix and suffix commands and specify
+@var{GROUP}s add key bindings for infix and suffix commands and specify
how these bindings are presented in the popup buffer. At least one
-@var{group} has to be specified. @xref{Binding Suffix and Infix Commands}.
+@var{GROUP} has to be specified. @xref{Binding Suffix and Infix Commands}.
-The @var{body} is optional. If it is omitted, then @var{arglist} is ignored and
+The @var{BODY} is optional. If it is omitted, then @var{ARGLIST} is ignored and
the function definition becomes:
@lisp
(transient-setup 'NAME))
@end lisp
-If @var{body} is specified, then it must begin with an @code{interactive} form
-that matches @var{arglist}, and it must call @code{transient-setup}. It may,
+If @var{BODY} is specified, then it must begin with an @code{interactive} form
+that matches @var{ARGLIST}, and it must call @code{transient-setup}. It may,
however, call that function only when some condition is satisfied.
@cindex scope of a transient
All transients have a (possibly @code{nil}) value, which is exported when
suffix commands are called, so that they can consume that value.
For some transients it might be necessary to have a sort of
-secondary value, called a ``scope''. Such a scope would usually be
+secondary value, called a “scope”. Such a scope would usually be
set in the command's @code{interactive} form and has to be passed to the
setup function:
Users and third-party packages can add additional bindings using
functions such as @code{transient-insert-suffix} (@pxref{Modifying
-Existing Transients}). These functions take a ``suffix
-specification'' as one of their arguments, which has the same form as
+Existing Transients}). These functions take a “suffix
+specification” as one of their arguments, which has the same form as
the specifications used in @code{transient-define-prefix}.
@menu
@node Group Specifications
@subsection Group Specifications
+
@cindex group specifications
The suffix and infix commands of a transient are organized in groups.
Group specifications then have this form:
@lisp
-[@{@var{level}@} @{@var{description}@}
- @{@var{keyword} @var{value}@}...
- @var{element}...]
+[@{@var{LEVEL}@} @{@var{DESCRIPTION}@}
+ @{@var{KEYWORD} @var{VALUE}@}...
+ @var{ELEMENT}...]
@end lisp
-The @var{level} is optional and defaults to 4. @xref{Enabling and
+The @var{LEVEL} is optional and defaults to 4. @xref{Enabling and
Disabling Suffixes}.
-The @var{description} is optional. If present, it is used as the heading of
+The @var{DESCRIPTION} is optional. If present, it is used as the heading of
the group.
-The @var{keyword}-@var{value} pairs are optional. Each keyword has to be a
+The @var{KEYWORD}-@var{VALUE} pairs are optional. Each keyword has to be a
keyword symbol, either @code{:class} or a keyword argument supported by the
constructor of that class.
@itemize
@item
One of these keywords, @code{:description}, is equivalent to specifying
-@var{description} at the very beginning of the vector. The recommendation
+@var{DESCRIPTION} at the very beginning of the vector. The recommendation
is to use @code{:description} if some other keyword is also used, for
-consistency, or @var{description} otherwise, because it looks better.
+consistency, or @var{DESCRIPTION} otherwise, because it looks better.
@item
-Likewise @code{:level} is equivalent to @var{level}.
+Likewise @code{:level} is equivalent to @var{LEVEL}.
@item
Other important keywords include the @code{:if...} keywords. These
keywords control whether the group is available in a certain
situation.
-For example, one group of the @code{magit-rebase} transient uses
-@code{:if magit-rebase-in-progress-p}, which contains the suffixes
-that are useful while rebase is already in progress; and another that uses
+For example, one group of the @code{magit-rebase} transient uses @code{:if
+ magit-rebase-in-progress-p}, which contains the suffixes that are
+useful while rebase is already in progress; and another that uses
@code{:if-not magit-rebase-in-progress-p}, which contains the suffixes that
initiate a rebase.
@end lisp
@item
-The value of @code{:setup-children}, if non-@code{nil}, is a function
-that takes two arguments the group object itself and a list of children.
-The children are given as a, potentially empty, list consisting
+The value of @code{:setup-children}, if non-@code{nil}, is a function that takes
+two arguments the group object itself and a list of children.
+The children are given as a (potentially empty) list consisting
of either group or suffix specifications. It can make arbitrary
changes to the children including constructing new children from
scratch. Also see @code{transient-setup-children}.
descriptions.
@end itemize
-The @var{element}s are either all subgroups (vectors), or all suffixes
+The @var{ELEMENT}s are either all subgroups (vectors), or all suffixes
(lists) and strings. (At least currently no group type exists that
would allow mixing subgroups with commands at the same level, though
in principle there is nothing that prevents that.)
-If the @var{element}s are not subgroups, then they can be a mixture of lists
+If the @var{ELEMENT}s are not subgroups, then they can be a mixture of lists
that specify commands and strings. Strings are inserted verbatim.
The empty string can be used to insert gaps between suffixes, which is
particularly useful if the suffixes are outlined as a table.
Variables are supported inside group specifications. For example in
place of a direct subgroup specification, a variable can be used whose
-value is a vector that qualifies as a group specification. Likewise, a
-variable can be used where a suffix specification is expected. Lists
-of group or suffix specifications are also supported. Indirect
+value is a vector that qualifies as a group specification. Likewise,
+a variable can be used where a suffix specification is expected.
+Lists of group or suffix specifications are also supported. Indirect
specifications are resolved when the transient prefix is being
defined.
@node Suffix Specifications
@subsection Suffix Specifications
+
@cindex suffix specifications
A transient's suffix and infix commands are bound when the transient
individual suffix command.
The same form is also used when later binding additional commands
-using functions such as @code{transient-insert-suffix},
-see @ref{Modifying Existing Transients}.
+using functions such as @code{transient-insert-suffix}, see @ref{Modifying Existing Transients}.
-Note that an infix is a special kind of suffix. Depending on context
-``suffixes'' means ``suffixes (including infixes)'' or ``non-infix
-suffixes''. Here it means the former.
+Note that an infix is a special kind of suffix. Depending on context
+“suffixes” means “suffixes (including infixes)” or “non-infix
+suffixes”. Here it means the former.
Suffix specifications have this form:
@lisp
-([@var{level}]
- [@var{key}] [@var{description}]
- @var{command}|@var{argument} [@var{keyword} @var{value}]...)
+([@var{LEVEL}]
+ [@var{KEY}] [@var{DESCRIPTION}]
+ @var{COMMAND}|@var{ARGUMENT} [@var{KEYWORD} @var{VALUE}]...)
@end lisp
-@var{level}, @var{key} and @var{description} can also be specified using the @var{keyword}s
+@var{LEVEL}, @var{KEY} and @var{DESCRIPTION} can also be specified using the @var{KEYWORD}s
@code{:level}, @code{:key} and @code{:description}. If the object that is associated with
-@var{command} sets these properties, then they do not have to be specified
+@var{COMMAND} sets these properties, then they do not have to be specified
here. You can however specify them here anyway, possibly overriding
the object's values just for the binding inside this transient.
@itemize
@item
-@var{level} is the suffix level, an integer between 1 and 7.
+@var{LEVEL} is the suffix level, an integer between 1 and 7.
@xref{Enabling and Disabling Suffixes}.
@item
-@var{key} is the key binding, either a vector or key description string.
+@var{KEY} is the key binding, either a vector or key description string.
@item
-@var{description} is the description, either a string or a function that
+@var{DESCRIPTION} is the description, either a string or a function that
returns a string. The function should be a lambda expression to
avoid ambiguity. In some cases a symbol that is bound as a function
would also work but to be safe you should use @code{:description} in that
@itemize
@item
-Usually @var{command} is a symbol that is bound as a function, which has
+@var{COMMAND} should be a symbol that is bound as a function, which has
to be defined or at least autoloaded as a command by the time the
containing prefix command is invoked.
with it (as would be the case if @code{transient-define-suffix} or
@code{transient-define-infix} were used to define it).
-The command can also be a closure or lambda expression, but that
-should only be used for dynamic transients whose suffixes are
-defined when the prefix command is invoked. See information about
-the @code{:setup-children} function in @ref{Group Specifications}.
+Anonymous, dynamically defined suffix commands are also support.
+See information about the @code{:setup-children} function in @ref{Group Specifications}.
As mentioned above, the object that is associated with a command can
be used to set the default for certain values that otherwise have to
be set in the suffix specification. Therefore if there is no object,
-then you have to make sure to specify the @var{key} and the @var{description}.
+then you have to make sure to specify the @var{KEY} and the @var{DESCRIPTION}.
As a special case, if you want to add a command that might be neither
defined nor autoloaded, you can use a workaround like:
:if (lambda () (featurep 'no-library))))
@end lisp
-Instead of @code{featurep} you could also use @code{require} with a
-non-nil value for @var{noerror}.
+Instead of @code{featurep} you could also use @code{require} with a non-@code{nil} value
+for @var{NOERROR}.
@item
The mandatory argument can also be a command-line argument, a
Unless the class is specified explicitly, the appropriate class is
guessed based on the long argument. If the argument ends with @samp{=}
-(e.g. @samp{--format=}) then @code{transient-option} is used, otherwise
+(e.g., @samp{--format=}) then @code{transient-option} is used, otherwise
@code{transient-switch}.
@end itemize
-Finally, details can be specified using optional
-@var{keyword}-@var{value} pairs.
+Finally, details can be specified using optional @var{KEYWORD}-@var{VALUE} pairs.
Each keyword has to be a keyword symbol, either @code{:class} or a keyword
argument supported by the constructor of that class. See @ref{Suffix Slots}.
@node Defining Suffix and Infix Commands
@section Defining Suffix and Infix Commands
+
@cindex defining suffix commands
@cindex defining infix commands
-Note that an infix is a special kind of suffix. Depending on context
-``suffixes'' means ``suffixes (including infixes)'' or ``non-infix
-suffixes''.
+Note that an infix is a special kind of suffix. Depending on context
+“suffixes” means “suffixes (including infixes)” or “non-infix
+suffixes”.
@defmac transient-define-suffix name arglist [docstring] [keyword value]@dots{} body@dots{}
+This macro defines @var{NAME} as a transient suffix command.
-This macro defines @var{name} as a transient suffix command.
-
-@var{arglist} are the arguments that the command takes.
-@var{docstring} is the documentation string and is optional.
+@var{ARGLIST} are the arguments that the command takes.
+@var{DOCSTRING} is the documentation string and is optional.
These arguments can optionally be followed by keyword-value pairs.
Each keyword has to be a keyword symbol, either @code{:class} or a keyword
@code{transient-suffix} class is used if the class is not specified
explicitly.
-The @var{body} must begin with an @code{interactive} form that matches @var{arglist}.
+The @var{BODY} must begin with an @code{interactive} form that matches @var{ARGLIST}.
The infix arguments are usually accessed by using @code{transient-args}
inside @code{interactive}.
@end defmac
@defmac transient-define-infix name arglist [docstring] [keyword value]@dots{}
+This macro defines @var{NAME} as a transient infix command.
-This macro defines @var{name} as a transient infix command.
-
-@var{arglist} is always ignored (but mandatory never-the-less) and
-reserved for future use. @var{docstring} is the documentation string and
+@var{ARGLIST} is always ignored (but mandatory never-the-less) and
+reserved for future use. @var{DOCSTRING} is the documentation string and
is optional.
The keyword-value pairs are mandatory. All transient infix commands
methods are different for different infix command classes. In rare
cases the above command function might not be suitable, even if you
define your own infix command class. In that case you have to use
-@code{transient-suffix-command} to define the infix command and use @code{t} as
-the value of the @code{:transient} keyword.
+@code{transient-define-suffix} to define the infix command and use @code{t} as the
+value of the @code{:transient} keyword.
@end defmac
@defmac transient-define-argument name arglist [docstring] [keyword value]@dots{}
-
-This macro defines @var{name} as a transient infix command.
+This macro defines @var{NAME} as a transient infix command.
This is an alias for @code{transient-define-infix}. Only use this alias
to define an infix command that actually sets an infix argument.
@node Using Infix Arguments
@section Using Infix Arguments
-@cindex using infix arguments
The functions and the variables described below allow suffix commands
to access the value of the transient from which they were invoked;
@code{prefix-arg} serves for prefix arguments.
@defun transient-args prefix
-
This function returns the value of the transient prefix command
-@var{prefix}.
+@var{PREFIX}.
If the current command was invoked from the transient prefix command
-@var{prefix}, then it returns the active infix arguments. If the current
-command was not invoked from @var{prefix}, then it returns the set, saved
-or default value for @var{prefix}.
+@var{PREFIX}, then it returns the active infix arguments. If the current
+command was not invoked from @var{PREFIX}, then it returns the set, saved
+or default value for @var{PREFIX}.
@end defun
@defun transient-arg-value arg args
-
-This function return the value of @var{arg} as it appears in @var{args}.
+This function return the value of @var{ARG} as it appears in @var{ARGS}.
For a switch a boolean is returned. For an option the value is
returned as a string, using the empty string for the empty value,
-or @code{nil} if the option does not appear in @var{args}.
+or @code{nil} if the option does not appear in @var{ARGS}.
@end defun
@defun transient-suffixes prefix
-
This function returns the suffixes of the transient prefix command
-@var{prefix}. This is a list of objects. This function should only be
+@var{PREFIX}. This is a list of objects. This function should only be
used if you need the objects (as opposed to just their values) and
-if the current command is not being invoked from @var{prefix}.
+if the current command is not being invoked from @var{PREFIX}.
@end defun
@defvar transient-current-suffixes
-
The suffixes of the transient from which this suffix command was
invoked. This is a list of objects. Usually it is sufficient to
instead use the function @code{transient-args}, which returns a list of
values. In complex cases it might be necessary to use this variable
-instead, i.e.@: if you need access to information beside the value.
+instead, i.e., if you need access to information beside the value.
@end defvar
@defvar transient-current-prefix
-
The transient from which this suffix command was invoked. The
returned value is a @code{transient-prefix} object, which holds information
associated with the transient prefix command.
@end defvar
@defvar transient-current-command
-
The transient from which this suffix command was invoked. The
returned value is a symbol, the transient prefix command.
@end defvar
@node Transient State
@section Transient State
+
@cindex transient state
-Invoking a transient prefix command ``activates'' the respective
-transient, i.e.@: it puts a transient keymap into effect, which binds
+Invoking a transient prefix command “activates” the respective
+transient, i.e., it puts a transient keymap into effect, which binds
the transient's infix and suffix commands.
The default behavior while a transient is active is as follows:
transient remains active.
@item
-Invoking a (non-infix) suffix command ``deactivates'' the transient
+Invoking a (non-infix) suffix command “deactivates” the transient
state by removing the transient keymap and performing some
additional cleanup.
@item
Invoking a command that is bound in a keymap other than the
transient keymap is disallowed and trying to do so results in a
-warning. This does not ``deactivate'' the transient.
+warning. This does not “deactivate” the transient.
@end itemize
But these are just the defaults. Whether a certain command
-deactivates or ``exits'' the transient is configurable. There is more
-than one way in which a command can be ``transient'' or ``non-transient'';
-the exact behavior is implemented by calling a so-called ``pre-command''
+deactivates or “exits” the transient is configurable. There is more
+than one way in which a command can be “transient” or “non-transient”;
+the exact behavior is implemented by calling a so-called “pre-command”
function. Whether non-suffix commands are allowed to be called is
configurable per transient.
@itemize
@item
@code{t} is equivalent to @code{transient--do-stay}.
-
@item
@code{nil} is equivalent to @code{transient--do-exit}.
-
@item
If @code{transient} is unbound (and that is actually the default for
non-infix suffixes) then the value of the prefix's
@end itemize
@item
-A suffix command can be a prefix command itself, i.e. a
-``sub-prefix''. While a sub-prefix is active we nearly always want
-@kbd{C-g} to take the user back to the ``super-prefix''. However in rare
+A suffix command can be a prefix command itself, i.e., a
+“sub-prefix”. While a sub-prefix is active we nearly always want
+@kbd{C-g} to take the user back to the “super-prefix”. However in rare
cases this may not be desirable, and that makes the following
complication necessary:
For @code{transient-suffix} objects the @code{transient} slot is unbound. We can
ignore that for the most part because, as stated above, @code{nil} and the
-slot being unbound are equivalent, and mean ``do exit''. That isn't
+slot being unbound are equivalent, and mean “do exit”. That isn't
actually true for suffixes that are sub-prefixes though. For such
-suffixes unbound means ``do exit but allow going back'', which is the
-default, while @code{nil} means ``do exit permanently'', which requires that
+suffixes unbound means “do exit but allow going back”, which is the
+default, while @code{nil} means “do exit permanently”, which requires that
slot to be explicitly set to that value.
@item
the value that they return determines whether the transient is exited.
To do so the value of one of the constants @code{transient--exit} or
@code{transient--stay} is used (that way we don't have to remember if @code{t} means
-``exit'' or ``stay'').
+“exit” or “stay”).
Additionally, these functions may change the value of @code{this-command}
(which explains why they have to be called using @code{pre-command-hook}),
function that makes sense for infixes.
@defun transient--do-stay
-
Call the command without exporting variables and stay transient.
@end defun
The default for suffixes is @code{transient--do-exit}.
@defun transient--do-exit
-
Call the command after exporting variables and exit the transient.
@end defun
-@defun transient--do-call
+@defun transient--do-return
+Call the command after exporting variables and return to parent
+prefix. If there is no parent prefix, then call @code{transient--do-exit}.
+@end defun
+@defun transient--do-call
Call the command after exporting variables and stay transient.
@end defun
-@defun transient--do-replace
+The following pre-commands are suitable for sub-prefixes. Only the
+first should ever explicitly be set as the value of the @code{transient}
+slot.
+
+@defun transient--do-recurse
+Call the transient prefix command, preparing for return to active
+transient.
+
+Whether we actually return to the parent transient is ultimately
+under the control of each invoked suffix. The difference between
+this pre-command and @code{transient--do-replace} is that it changes the
+value of the @code{transient-suffix} slot to @code{transient--do-return}.
+
+If there is no parent transient, then only call this command and
+skip the second step.
+@end defun
+@defun transient--do-replace
Call the transient prefix command, replacing the active transient.
-This is used for suffixes that are prefixes themselves, i.e.@: for
-sub-prefixes.
+Unless @code{transient--do-recurse} is explicitly used, this pre-command
+is automatically used for suffixes that are prefixes themselves,
+i.e., for sub-prefixes.
+@end defun
+
+@defun transient--do-suspend
+Suspend the active transient, saving the transient stack.
+
+This is used by the command @code{transient-suspend} and optionally also by
+“external events” such as @code{handle-switch-frame}. Such bindings should
+be added to @code{transient-predicate-map}.
@end defun
@anchor{Pre-commands for Non-Suffixes}
@subheading Pre-commands for Non-Suffixes
-The default for non-suffixes, i.e@: commands that are bound in other
+The default for non-suffixes, i.e., commands that are bound in other
keymaps beside the transient keymap, is @code{transient--do-warn}. Silently
ignoring the user-error is also an option, though probably not a good
one.
slot.
@defun transient--do-warn
-
Call @code{transient-undefined} and stay transient.
@end defun
@defun transient--do-noop
-
Call @code{transient-noop} and stay transient.
@end defun
@subheading Special Pre-Commands
@defun transient--do-quit-one
-
If active, quit help or edit mode, else exit the active transient.
This is used when the user pressed @kbd{C-g}.
@end defun
@defun transient--do-quit-all
-
Exit all transients without saving the transient stack.
This is used when the user pressed @kbd{C-q}.
@end defun
@defun transient--do-suspend
-
Suspend the active transient, saving the transient stack.
This is used when the user pressed @kbd{C-z}.
@node Classes and Methods
@chapter Classes and Methods
+
@cindex classes and methods
Transient uses classes and generic functions to make it possible to
command. The values of such slots are regular functions.
Generic functions are used when a function should do something
-different based on the type of the command, i.e. when all commands
+different based on the type of the command, i.e., when all commands
of a certain type should behave the same way but different from the
behavior for other types. Object slots that hold a regular function
as value are used when the task that they perform is likely to
@section Group Classes
The type of a group can be specified using the @code{:class} property at the
-beginning of the class specification, e.g. @code{[:class transient-columns
+beginning of the class specification, e.g., @code{[:class transient-columns
...]} in a call to @code{transient-define-prefix}.
@itemize
@code{transient-group} (and therefore all groups) as well as of
@code{transient-suffix} (and therefore all suffix and infix commands).
-This class exists because the elements (a.k.a.@: ``children'') of certain
+This class exists because the elements (or “children”) of certain
groups can be other groups instead of suffix and infix commands.
@item
@item
The @code{transient-column} class is the simplest group.
-This is the default ``flat'' group. If the class is not specified
-explicitly and the first element is not a vector (i.e. not a group),
+This is the default “flat” group. If the class is not specified
+explicitly and the first element is not a vector (i.e., not a group),
then this class is used.
This class displays each element on a separate line.
or strings. Each subgroup represents a column. This class takes
care of inserting the subgroups' elements.
-This is the default ``nested'' group. If the class is not specified
-explicitly and the first element is a vector (i.e.@: a group), then
+This is the default “nested” group. If the class is not specified
+explicitly and the first element is a vector (i.e., a group), then
this class is used.
@item
@section Group Methods
@defun transient-setup-children group children
-
This generic function can be used to setup the children or a group.
The default implementation usually just returns the children
-unchanged, but if the @code{setup-children} slot of @var{group} is non-nil, then
-it calls that function with @var{children} as the only argument and
+unchanged, but if the @code{setup-children} slot of @var{GROUP} is non-@code{nil}, then
+it calls that function with @var{CHILDREN} as the only argument and
returns the value.
The children are given as a (potentially empty) list consisting of
@end defun
@defun transient--insert-group group
-
This generic function formats the group and its elements and inserts
the result into the current buffer, which is a temporary buffer.
The contents of that buffer are later inserted into the popup buffer.
specialized based on the class of a prefix command.
@defun transient--history-init obj
-
This generic function is called while setting up the transient and
is responsible for initializing the @code{history} slot. This is the
transient-wide history; many individual infixes also have a history
@subsection Suffix Value Methods
@defun transient-init-value obj
-
-This generic function sets the initial value of the object @var{obj}.
+This generic function sets the initial value of the object @var{OBJ}.
This function is called for all suffix commands, but unless a
concrete method is implemented this falls through to the default
@end defun
@defun transient-infix-read obj
-
This generic function determines the new value of the infix object
-@var{obj}.
+@var{OBJ}.
This function merely determines the value; @code{transient-infix-set} is
used to actually store the new value in the object.
@code{transient-infix-value} method described below).
For some infix classes the value is changed without reading
-anything in the minibuffer, i.e.@: the mere act of invoking the
+anything in the minibuffer, i.e., the mere act of invoking the
infix command determines what the new value should be, based
on the previous value.
@end defun
@defun transient-prompt obj
-
This generic function returns the prompt to be used to read infix
-object @var{obj}'s value.
+object @var{OBJ}'s value.
@end defun
@defun transient-infix-set obj value
-
-This generic function sets the value of infix object @var{obj} to @var{value}.
+This generic function sets the value of infix object @var{OBJ} to @var{VALUE}.
@end defun
@defun transient-infix-value obj
-
-This generic function returns the value of the suffix object @var{obj}.
+This generic function returns the value of the suffix object @var{OBJ}.
This function is called by @code{transient-args} (which see), meaning this
function is how the value of a transient is determined so that the
invoked suffix command can use it.
Currently most values are strings, but that is not set in stone.
-@code{nil} is not a value, it means ``no value''.
+@code{nil} is not a value, it means “no value”.
Usually only infixes have a value, but see the method for
@code{transient-suffix}.
@end defun
@defun transient-init-scope obj
-
-This generic function sets the scope of the suffix object @var{obj}.
+This generic function sets the scope of the suffix object @var{OBJ}.
The scope is actually a property of the transient prefix, not of
individual suffixes. However it is possible to invoke a suffix
@subsection Suffix Format Methods
@defun transient-format obj
-
-This generic function formats and returns @var{obj} for display.
+This generic function formats and returns @var{OBJ} for display.
When this function is called, then the current buffer is some
temporary buffer. If you need the buffer from which the prefix
@end defun
@defun transient-format-key obj
-
-This generic function formats @var{obj}'s @code{key} for display and returns the
+This generic function formats @var{OBJ}'s @code{key} for display and returns the
result.
@end defun
@defun transient-format-description obj
-
-This generic function formats @var{obj}'s @code{description} for display and
+This generic function formats @var{OBJ}'s @code{description} for display and
returns the result.
@end defun
@defun transient-format-value obj
-
-This generic function formats @var{obj}'s value for display and returns
+This generic function formats @var{OBJ}'s value for display and returns
the result.
@end defun
@defun transient-show-help obj
-
Show help for the prefix, infix or suffix command represented by
-@var{obj}.
+@var{OBJ}.
For prefixes, show the info manual, if that is specified using the
@code{info-manual} slot. Otherwise, show the manpage if that is specified
@itemize
@item
-@code{man-page} or @code{info-manual} can be used to specify the documentation for
-the prefix and its suffixes. The command @code{transient-help} uses the
-method @code{transient-show-help} (which see) to lookup and use these
-values.
+@code{show-help}, @code{man-page} or @code{info-manual} can be used to specify the
+documentation for the prefix and its suffixes. The command
+@code{transient-help} uses the method @code{transient-show-help} (which see) to
+lookup and use these values.
@item
@code{history-key} If multiple prefix commands should share a single value,
@item
@code{scope} For some transients it might be necessary to have a sort of
-secondary value, called a ``scope''. See @code{transient-define-prefix}.
+secondary value, called a “scope”. See @code{transient-define-prefix}.
@end itemize
@anchor{Internal Prefix Slots}
@itemize
@item
@code{%k} For the key.
-
@item
@code{%d} For the description.
-
@item
@code{%v} For the infix value. Non-infix suffixes don't have a value.
@end itemize
@item
@code{description} The description, either a string or a function that is
called with no argument and returns a string.
+
+@item
+@code{show-help} A function used to display help for the suffix. If
+unspecified, the prefix controls how hlep is displayed for its
+suffixes.
@end itemize
@anchor{Slots of @code{transient-infix}}
@itemize
@item
-@code{argument} The long argument, e.g. @code{--verbose}.
+@code{argument} The long argument, e.g., @code{--verbose}.
@item
-@code{shortarg} The short argument, e.g. @code{-v}.
+@code{shortarg} The short argument, e.g., @code{-v}.
@item
@code{value} The value. Should not be accessed directly.
@item
@code{multi-value} For options, whether the option can have multiple
-values. If non-nil, then default to use @code{completing-read-multiple}.
+values. If this is non-@code{nil}, then the values are read using
+@code{completing-read-multiple} by default and if you specify your own
+reader, then it should read the values using that function or
+similar.
+
+Supported non-@code{nil} values are:
+
+@itemize
+@item
+Use @code{rest} for an option that can have multiple values. This is
+useful e.g., for an @code{--} argument that indicates that all remaining
+arguments are files (such as @code{git log -- file1 file2}).
+
+In the list returned by @code{transient-args} such an option and its
+values are represented by a single list of the form @code{(ARGUMENT
+ . VALUES)}.
+
+@item
+Use @code{repeat} for an option that can be specified multiple times.
+
+In the list returned by @code{transient-args} each instance of the option
+and its value appears separately in the usual from, for example:
+@code{("--another-argument" "--option=first" "--option=second")}.
+@end itemize
+
+In both cases the option's values have to be specified in the
+default value of a prefix using the same format as returned by
+@code{transient-args}, e.g., @code{("--other" "--o=1" "--o=2" ("--" "f1" "f2"))}.
@item
@code{always-read} For options, whether to read a value on every invocation.
@item
@code{reader} The function used to read the value of an infix. Not used
-for switches. The function takes three arguments, @var{prompt},
-@var{initial-input} and @var{history}, and must return a string.
+for switches. The function takes three arguments, @var{PROMPT},
+@var{INITIAL-INPUT} and @var{HISTORY}, and must return a string.
@item
@code{prompt} The prompt used when reading the value, either a string or a
@itemize
@item
@code{if} Enable if predicate returns non-@code{nil}.
-
@item
@code{if-not} Enable if predicate returns @code{nil}.
-
@item
@code{if-non-nil} Enable if variable's value is non-@code{nil}.
-
@item
@code{if-nil} Enable if variable's value is @code{nil}.
-
@item
@code{if-mode} Enable if major-mode matches value.
-
@item
@code{if-not-mode} Enable if major-mode does not match value.
-
@item
@code{if-derived} Enable if major-mode derives from value.
-
@item
@code{if-not-derived} Enable if major-mode does not derive from value.
@end itemize
@itemize
@item
-@code{(c)} represents a return to the command loop.
-
+@samp{(c)} represents a return to the command loop.
@item
-@code{(+)} represents the user's choice to press one key or another.
-
+@samp{(+)} represents the user's choice to press one key or another.
@item
-@code{@{@var{word}@}} are possible behaviors.
-
+@samp{@{WORD@}} are possible behaviors.
@item
-@code{@{@var{number}@}} is a footnote.
+@samp{@{NUMBER@}} is a footnote.
@end itemize
@anchor{Regular Prefix Commands}
@itemize
@item
-@code{@{1@}} Transients can be configured to be exited when a suffix command
+@samp{@{1@}} Transients can be configured to be exited when a suffix command
is invoked. The default is to do so for all suffixes except for
those that are common to all transients and which are used to
perform tasks such as providing help and saving the value of the
state.
@item
-@code{@{2@}} Transients can be configured to allow the user to invoke
+@samp{@{2@}} Transients can be configured to allow the user to invoke
non-suffix commands. The default is to not allow that and instead
warn the user.
@end itemize
temporarily available and show the available commands in a popup
buffer.
-A Hydra ``body'' is equivalent to a Transient ``prefix'' and a Hydra
-``head'' is equivalent to a Transient ``suffix''. Hydra has no equivalent
-of a Transient ``infix''.
+A Hydra “body” is equivalent to a Transient “prefix” and a Hydra
+“head” is equivalent to a Transient “suffix”. Hydra has no equivalent
+of a Transient “infix”.
Both hydras and transients can be used as simple command dispatchers.
Used like this they are similar to regular prefix commands and prefix
@item
Invoking a command from a hydra does not necessarily exit the hydra.
That makes it possible to invoke the same command again, but using a
-shorter key sequence (i.e. the key that was used to enter the hydra
+shorter key sequence (i.e., the key that was used to enter the hydra
does not have to be pressed again).
Transient supports that too, but for now this feature is not a focus
("n" "next visible heading" outline-next-visible-heading)])
@end lisp
-
@item
Transient supports infix arguments; values that are set by infix
commands and then consumed by the invoked suffix command(s).
@anchor{Can I control how the popup buffer is displayed?}
@appendixsec Can I control how the popup buffer is displayed?
-Yes, see @code{transient-display-buffer-action} in @ref{Other Options}.
+Yes, see @code{transient-display-buffer-action} in @ref{Configuration}.
@anchor{Why did some of the key bindings change?}
@appendixsec Why did some of the key bindings change?
You may have noticed that the bindings for some of the common commands
-do @strong{not} have the prefix @code{C-x} and that furthermore some of these commands
+do @strong{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.
too many non-prefix bindings, keeping them available for use in
individual transients. The bindings that do not use a prefix and that
are @strong{not} grayed out are very important bindings that are @strong{always}
-available, even when invoking the ``common command key prefix'' or @strong{any
+available, even when invoking the “common command key prefix” or @strong{any
other} transient-specific prefix. The non-prefix keys that @strong{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 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}.
+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},
+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 @kbd{C-x ...} bindings would be grayed out.
+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
-@strong{without} the section of common commands also popping up. @code{C-c} in
+@strong{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.
(Also see the next question.)
-@anchor{Why does @code{q} not quit popups anymore?}
-@appendixsec Why does @code{q} not quit popups anymore?
+@anchor{Why does @kbd{q} not quit popups anymore?}
+@appendixsec Why does @kbd{q} not quit popups anymore?
I agree that @kbd{q} is a good binding for commands that quit something.
This includes quitting whatever transient is currently active, but it
also includes quitting whatever it is that some specific transient is
-controlling. The transient @code{magit-blame} for example binds @code{q} to the
+controlling. The transient @code{magit-blame} for example binds @kbd{q} to the
command that turns @code{magit-blame-mode} off.
So I had to decide if @kbd{q} should quit the active transient (like
-Magit-Popup used to) or whether @kbd{C-g} should do that instead, so
-that @kbd{q}
+Magit-Popup used to) or whether @kbd{C-g} should do that instead, so that @kbd{q}
could be bound in individual transient to whatever commands make sense
for them. Because all other letters are already reserved for use by
individual transients, I have decided to no longer make an exception
@printindex vr
@node Concept Index
-@appendix Concept and Feature Index
+@appendix Concept Index
@printindex cp
projects / emacs.git / commitdiff