branch: externals/transient
commit 41b6e06cf56c029465fae72dc4c6e16cfd304e47
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
Regenerate manual
---
docs/transient.texi | 86 +++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 71 insertions(+), 15 deletions(-)
diff --git a/docs/transient.texi b/docs/transient.texi
index 9073b2f206..4576cc6b16 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -1010,7 +1010,7 @@ with an example:
@end lisp
This inserts a new infix argument to toggle the @code{--reverse} argument
-after the infix argument that toggles @code{-3} in @code{magit-patch-apply}.
+after the infix argument that is bound to @code{-3} in
@code{magit-patch-apply}.
The following functions share a few arguments:
@@ -1018,6 +1018,9 @@ The following functions share a few arguments:
@item
@var{PREFIX} is a transient prefix command, a symbol.
+PREFIX may also by a symbol identifying a separately defined group,
+which can be included in multiple prefixes. See TODO@.
+
@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
@@ -1029,25 +1032,33 @@ means the former. See @ref{Suffix Specifications}.
@code{transient-define-prefix}. See @ref{Group Specifications}.
@item
-@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)}
+@var{LOC} is a key description (a string as returned by @code{key-description}
+and understood by @code{kbd}), a command, a symbol identifying an included
+group, or a vector specifying coordinates. 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
-group, not just an individual suffix command.
+If @var{LOC} is a vector, then it can be used to identify a group, not
+just an individual suffix command. The last element in a vector may
+also be a symbol or key, in which case the preceding elements must
+match a group and the last element is looked up within that group.
The function @code{transient-get-suffix} can be useful to determine whether
-a certain coordination list identifies the suffix or group that you
+a certain coordinate vector identifies the suffix or group that you
expect it to identify. In hairy cases it may be necessary to look
-at the definition of the transient prefix command.
+at the internal layout representation, which you can access using
+the function @code{transient--get-layout}.
@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}.
+@code{transient--layout} property of the @var{PREFIX} symbol. Elements in that
+tree are not objects but have the form @code{(@var{CLASS} @var{PLIST}) for
suffixes} and
+[CLASS PLIST CHILDREN] for groups. At the root of the tree is an
+element [N nil CHILDREN], where N is the version of the layout format,
+currently and hopefully for a long time 2. While that element looks
+like a group vector, that element does not count when identifying a
+group using a coordinate vector, i.e., [0] is its first child, not the
+root element itself.
@defun transient-insert-suffix prefix loc suffix &optional keep-other
@end defun
@@ -1061,8 +1072,8 @@ 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-@code{nil} @var{KEEP-OTHER@.} The symbol
@code{always}
-prevents the removal of a false-positive in some cases where other
+To deal with the former, use non-@code{nil} @var{KEEP-OTHER@.} The symbol
@code{always}
+prevents the removal of a false-positive, in some cases where other
non-@code{nil} values would fail. To deal with false-negatives remove the
conflicting binding separately, using @code{transient-remove-suffix}.
@end defun
@@ -1086,6 +1097,19 @@ 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
+Some prefix commands share suffixes, which are separately and then
+included in each prefix when it is defined. The inclusion is done by
+reference, the included suffix groups are not inlined by default. So
+if you change, for example, the key binding for an argument in
+@code{magit-diff} (@code{d}) the same change also applies to
@code{magit-diff-refresh} (@code{D}).
+In the rare case that this is not desirable use @code{transient-inline-group}
+before making changes to included suffixes.
+
+@defun transient-inline-group PREFIX GROUP
+This function inlines the included GROUP into PREFIX, by replacing
+the symbol GROUP with its expanded layout in the layout of PREFIX@.
+@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
@@ -1267,6 +1291,22 @@ For example, the scope of the
@code{magit-branch-configure} transient is
the branch whose variables are being configured.
@end defmac
+Sometimes multiple prefix commands share a common set of suffixes.
+For example, while @code{magit-diff} (@code{d}) and @code{magit-diff-refresh}
(@code{D}) offer
+different suffixes to actually create or update a diff, they both
+offer the same infix arguments to control how that diff is formatted.
+Such shared groups should be defined using @code{transient-define-group}
+and then included in multiple prefixes, by using the symbol that
+identifies the group in the prefix definition, in a location where
+you would otherwise use a group vector. If an included group is
+placed at the top-level of a prefix (as opposed of inside inside
+a vector as a child group), then the symbol should be quoted.
+
+@defmac transient-define-group name group@dots{}
+This macro define one or more groups and stores them in symbol NAME@.
+GROUPs have the same form as for @code{transient-define-prefix}.
+@end defmac
+
@node Binding Suffix and Infix Commands
@section Binding Suffix and Infix Commands
@@ -1470,7 +1510,15 @@ the object's values just for the binding inside this
transient.
@ref{Enabling and Disabling Suffixes}.
@item
-@var{KEY} is the key binding, either a vector or key description string.
+KEY is the key binding, a string in the format returned by
+@code{describe-key} and understood by @code{kbd}.
+
+That format is more permissive than the one accepted by @code{key-valid-p}.
+Being more permissive makes it possible, for example, to write the
+key binding, which toggles the @code{-a} command line argument, as "-a",
+instead of having to write "- a". Likewise additional spaces can be
+added, which is not removed when displaying the binding in the menu,
+which is useful for alignment purposes.
@item
@var{DESCRIPTION} is the description, either a string or a function that
@@ -2687,7 +2735,15 @@ and @code{advice*} slots (see @ref{Slots of
@code{transient-suffix}}) are define
@itemize
@item
-@code{key} The key, a key vector or a key description string.
+@code{key} is the key binding, a string in the format returned by
+@code{describe-key} and understood by @code{kbd}.
+
+That format is more permissive than the one accepted by @code{key-valid-p}.
+Being more permissive makes it possible, for example, to write the
+key binding, which toggles the @code{-a} command line argument, as "-a",
+instead of having to write "- a". Likewise additional spaces can be
+added, which is not removed when displaying the binding in the menu,
+which is useful for alignment purposes.
@item
@code{command} The command, a symbol.
