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
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
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
+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.
+``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
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
+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
+arguments''), but also remembers the values of individual arguments
independently. See @xref{Using History}.
After a transient prefix command is invoked, @kbd{C-h @var{KEY}} can be used to
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).
@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
+commands is described as ``Show common permanently''; invoke that if you
want the common commands to always be shown for all transients.
@table @asis
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
@item
@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
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
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.
+``suffixes'' means ``suffixes (including infixes)'' or ``non-infix
+suffixes''. Here it means the former.
Suffix specifications have this form:
@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”.
+``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.
@cindex transient state
-Invoking a transient prefix command “activates” the respective
+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.
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.
@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
+``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}),
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
+``external events'' such as @code{handle-switch-frame}. Such bindings should
be added to @code{transient-predicate-map}.
@end defun
@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 (or “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
+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.
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
+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.
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}.
@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}
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
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}.
-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
projects / emacs.git / commitdiff