branch: externals/transient
commit 323d6b6c84e6ae55e578efa1efb6bb4d42a69cac
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
manual: Document when to invoke prefix arguments
---
docs/transient.org | 31 ++++++++++++++++++++++-------
docs/transient.texi | 56 +++++++++++++++++++++++------------------------------
2 files changed, 48 insertions(+), 39 deletions(-)
diff --git a/docs/transient.org b/docs/transient.org
index b1c71e94b3..02389c83c2 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -142,13 +142,13 @@ 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”),
-but also remembers the values of individual arguments independently.
-See [[*Using History]].
+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 {{{var(KEY)}}} is
@@ -164,6 +164,23 @@ 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.)
+
* Usage
** Invoking Transients
#+cindex: invoking transients
diff --git a/docs/transient.texi b/docs/transient.texi
index 3aef6d7352..7d8bce0875 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -248,13 +248,13 @@ 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”),
-but also remembers the values of individual arguments independently.
-See @ref{Using History}.
+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 @var{KEY} is
@@ -270,21 +270,26 @@ 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 Usage
@chapter Usage
-@menu
-* Invoking Transients::
-* Aborting and Resuming Transients::
-* Common Suffix Commands::
-* Saving Values::
-* Using History::
-* Getting Help for Suffix Commands::
-* Enabling and Disabling Suffixes::
-* Other Commands::
-* Configuration::
-@end menu
-
@node Invoking Transients
@section Invoking Transients
@@ -995,14 +1000,6 @@ signal an error.
@node Defining New Commands
@chapter Defining New Commands
-@menu
-* Defining Transients::
-* Binding Suffix and Infix Commands::
-* Defining Suffix and Infix Commands::
-* Using Infix Arguments::
-* Transient State::
-@end menu
-
@node Defining Transients
@section Defining Transients
@@ -2225,11 +2222,6 @@ See @ref{Enabling and Disabling Suffixes}.
@node Related Abstractions and Packages
@chapter Related Abstractions and Packages
-@menu
-* Comparison With Prefix Keys and Prefix Arguments::
-* Comparison With Other Packages::
-@end menu
-
@node Comparison With Prefix Keys and Prefix Arguments
@section Comparison With Prefix Keys and Prefix Arguments
