[elpa] externals/transient fe5fd3904f 7/8: Update manual

[Jonas Bernoulli]

branch: externals/transient
commit fe5fd3904f6a032a954667f7d53c0cfda9ba420f
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    Update manual
---
 CHANGELOG           |   2 +
 docs/transient.org  | 432 ++++++++++++++++++++++++++++++++++++++-------------
 docs/transient.texi | 435 ++++++++++++++++++++++++++++++++++++++++------------
 3 files changed, 662 insertions(+), 207 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index d9289c576e..284c59f69b 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -30,6 +30,8 @@
   used to override ~transient-display-buffer-action~ and
   ~transient-mode-line-format~ for individual prefix menus.  #332
 
+- Updated the manual considerably.
+
 Bug fixes:
 
 - Fixes some menu navigation edge-cases.
diff --git a/docs/transient.org b/docs/transient.org
index de475aab5f..6e34331c69 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -108,12 +108,13 @@ A transient prefix command is invoked like any other 
command by
 pressing the key that is bound to that command.  The main difference
 to other commands is that a transient prefix command activates a
 transient keymap, which temporarily binds the transient's infix and
-suffix commands.  Bindings from other keymaps may, or may not, be
-disabled while the transient state is in effect.
+suffix commands, and that those bindings are displayed in a transient
+menu, displayed in a popup buffer.  Bindings from other keymaps may,
+or may not, be disabled while the transient state is in effect.
 
 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
+set some value (which is then shown in the 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 *arguments*.
@@ -218,9 +219,6 @@ want the common commands to always be shown for all 
transients.
 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 [[*FAQ]] for more information.
-
 ** Saving Values
 #+cindex: saving values of arguments
 
@@ -245,12 +243,12 @@ but it is easily accessible (see [[*Using History]]).
 
 - Key: C-x C-s (transient-save) ::
 
-  Save the value of the active transient persistently across Emacs
-  sessions.
+  This command saves the value of the active transient persistently
+  across Emacs sessions.
 
 - Key: C-x C-k (transient-reset) ::
 
-  Clear the set and saved values of the active transient.
+  This command clears the set and saved values of the active transient.
 
 - User Option: transient-values-file ::
 
@@ -265,8 +263,8 @@ than outlined above and even customizable.
 #+cindex: value history
 
 Every time the user invokes a suffix command the transient's current
-value is saved to its history.  These values can be cycled through the
-same way one can cycle through the history of commands that read
+value is saved to its history.  These values can be cycled through,
+the same way one can cycle through the history of commands that read
 user-input in the minibuffer.
 
 #+attr_texinfo: :compact t
@@ -282,11 +280,11 @@ user-input in the minibuffer.
   This command switches to the next value used for the active
   transient.
 
-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.
+In addition to the transient-wide history, infixes can have their own
+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.
 
 Authors of transients should arrange for different infix commands that
 read the same kind of value to also use the same history key (see
@@ -486,7 +484,7 @@ Also see [[* Common Suffix Commands]].
 
   When ~nil~ (the default), hide the menu while the minibuffer is in use.
   When ~t~, keep showing the menu, but allow for the menu window to be
-  resized to ensure that completion candidates can be displayed.
+  resized, to ensure that completion candidates can be displayed.
 
   When ~fixed~, keep showing the menu and prevent it from being resized,
   which may make it impossible to display the completion candidates.  If
@@ -519,13 +517,14 @@ Also see [[* Common Suffix Commands]].
 - User Option: transient-enable-popup-navigation ::
 
   This option controls whether navigation commands are enabled in the
-  transient popup buffer.  If the value is ~verbose~, additionally show
-  brief documentation about the command under point in the echo area.
+  transient popup buffer.  If the value is ~verbose~ (the default),
+  brief documentation about the command under point is additionally
+  show in the echo area.
 
   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:
+  on that buffer itself.  If this option is non-~nil~, then the
+  following features are available:
 
   - {{{kbd(UP)}}} moves the cursor to the previous suffix.
   - {{{kbd(DOWN)}}} moves the cursor to the next suffix.
@@ -554,16 +553,14 @@ Also see [[* Common Suffix Commands]].
 
   #+BEGIN_SRC emacs-lisp
     (display-buffer-in-side-window
-      (side . bottom)
-      (inhibit-same-window . t)
-      (window-parameters (no-other-window . t)))
+     (side . bottom)
+     (dedicated . t)
+     (inhibit-same-window . t))
   #+END_SRC
 
   This displays the window at the bottom of the selected frame.
-  Another useful {{{var(FUNCTION)}}} is ~display-buffer-below-selected~, which
-  is what ~magit-popup~ used by default.  For more alternatives see
-  [[info:elisp#Buffer Display Action Functions]], and [[info:elisp#Buffer
-  Display Action Alists]].
+  For alternatives see [[info:elisp#Buffer Display Action Functions]],
+  and [[info:elisp#Buffer Display Action Alists]].
 
   Note that the buffer that was current before the transient buffer
   is shown should remain the current buffer.  Many suffix commands
@@ -734,6 +731,20 @@ These options are mainly intended for developers.
   suffixes that won't be available to users without them making the
   same customization.
 
+*** Hook Variables
+:PROPERTIES:
+:UNNUMBERED: notoc
+:END:
+
+- Variable: transient-exit-hook ::
+
+  This hook is run after a transient is exited.
+
+- Variable: transient-setup-buffer-hook ::
+
+  This hook is run when the transient buffer is being setup.
+  That buffer is current and empty when this hook is runs.
+
 * Modifying Existing Transients
 #+cindex: modifying existing transients
 
@@ -865,7 +876,7 @@ arguments have been set using a command such as 
~universal-argument~.
 #+cindex: command dispatchers
 Transient can be used to implement simple “command dispatchers”.  The
 main benefit then is that the user can see all the available commands
-in a popup buffer, which can be thought of as a “menus”.  That is
+in a popup buffer, which can be thought of as a “menu”.  That is
 useful by itself because it frees the user from having to remember all
 the keys that are valid after a certain prefix key or command.
 Magit's ~magit-dispatch~ (on {{{kbd(C-x M-g)}}}) command is an example of using
@@ -1319,9 +1330,18 @@ function, which for infix arguments serves about the 
same purpose as
   command was not invoked from {{{var(PREFIX)}}}, then it returns the set, 
saved
   or default value for {{{var(PREFIX)}}}.
 
+- Function: transient-get-value ::
+
+  This function returns the value of the current prefix.
+
+  This is mostly intended for internal use, but may also be of use
+  in ~transient-set-value~ and ~transient-save-value~ methods.  Unlike
+  ~transient-args~, this does not include the values of suffixes whose
+  ~unsavable~ slot is non-~nil~.
+
 - Function: transient-arg-value arg args ::
 
-  This function return the value of {{{var(ARG)}}} as it appears in 
{{{var(ARGS)}}}.
+  This function returns 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,
@@ -1334,6 +1354,52 @@ function, which for infix arguments serves about the 
same purpose as
   used if you need the objects (as opposed to just their values) and
   if the current command is not being invoked from {{{var(PREFIX)}}}.
 
+** Current Suffix Command
+
+- Function: transient-suffix-object command ::
+
+  This function returns the object associated with the current suffix
+  command.
+
+  Each suffix commands is associated with an object, which holds
+  additional information about the suffix, such as its value (in
+  the case of an infix command, which is a kind of suffix command).
+
+  This function is intended to be called by infix commands, which
+  are usually aliases of ~transient--default-infix-command~, which
+  is defined like this:
+
+  #+begin_src emacs-lisp
+    (defun transient--default-infix-command ()
+      (interactive)
+      (let ((obj (transient-suffix-object)))
+        (transient-infix-set obj (transient-infix-read obj)))
+      (transient--show))
+  #+end_src
+
+  (User input is read outside of ~interactive~ to prevent the
+  command from being added to ~command-history~.)
+
+  Such commands need to be able to access their associated object
+  to guide how ~transient-infix-read~ reads the new value and to
+  store the read value.  Other suffix commands (including non-infix
+  commands) may also need the object to guide their behavior.
+
+  This function attempts to return the object associated with the
+  current suffix command even if the suffix command was not invoked
+  from a transient.  (For some suffix command that is a valid thing
+  to do, for others it is not.)  In that case ~nil~ may be returned,
+  if the command was not defined using one of the macros intended
+  to define such commands.
+
+  The optional argument COMMAND is intended for internal use.  If
+  you are contemplating using it in your own code, then you should
+  probably use this instead:
+
+  #+begin_src emacs-lisp
+    (get COMMAND 'transient--suffix)
+  #+end_src
+
 - Variable: transient-current-suffixes ::
 
   The suffixes of the transient from which this suffix command was
@@ -1342,22 +1408,49 @@ function, which for infix arguments serves about the 
same purpose as
   values.  In complex cases it might be necessary to use this variable
   instead, i.e., if you need access to information beside the value.
 
-- Variable: transient-current-command ::
+** Current Prefix Command
+
+- Function: transient-prefix-object ::
 
-  The transient from which this suffix command was invoked.  The
-  returned value is a symbol, the transient prefix command.
+  This function returns the current prefix as an object.
+
+  While a transient is being setup or refreshed (which involves
+  preparing its suffixes) the variable ~transient--prefix~ can be
+  used to access the prefix object.  Thus this is what has to be
+  used in suffix methods such as ~transient-format-description~,
+  and in object-specific functions that are stored in suffix slots
+  such as ~description~.
+
+  When a suffix command is invoked (i.e., in its ~interactive~ form
+  and function body) then the variable ~transient-current-prefix~
+  has to be used instead.
+
+  Two distinct variables are needed, because any prefix may itself
+  be used as a suffix of another prefix, and such sub-prefixes have
+  to be able to tell themselves apart from the prefix they were
+  invoked from.
+
+  Regular suffix commands, which are not prefixes, do not have to
+  concern themselves with this distinction, so they can use this
+  function instead.  In the context of a plain suffix, it always
+  returns the value of the appropriate variable.
 
 - Variable: transient-current-prefix ::
 
-  The transient from which this suffix command was invoked.  The
-  returned value is a ~transient-prefix~ object, which holds information
-  associated with the transient prefix command.
+  The transient from which this suffix command was invoked.  The value
+  is a ~transient-prefix~ object, which holds information associated
+  with the transient prefix command.
 
-- Function: transient-active-prefix ::
+- Variable: transient-current-command ::
+
+  The transient from which this suffix command was invoked.  The value
+  is a symbol, the transient prefix command.
 
-  This function returns the active transient object.  Return ~nil~ if
-  there is no active transient, if the transient buffer isn't shown,
-  and while the active transient is suspended (e.g., while the
+- Function: transient-active-prefix &optional prefixes ::
+
+  This function returns the active transient object.  It returns ~nil~
+  if there is no active transient, if the transient buffer isn't
+  shown, and while the active transient is suspended (e.g., while the
   minibuffer is in use).
 
   Unlike ~transient-current-prefix~, which is only ever non-~nil~ in code
@@ -1606,14 +1699,12 @@ the transient.
 #+cindex: classes and methods
 
 Transient uses classes and generic functions to make it possible to
-define new types of suffix commands that are similar to existing
-types, but behave differently in some aspects.  It does the same for
-groups and prefix commands, though at least for prefix commands that
-*currently* appears to be less important.
+define new types of suffix and prefix commands, which are similar to
+existing types, but behave differently in some respects.
 
 Every prefix, infix and suffix command is associated with an object,
-which holds information that controls certain aspects of its behavior.
-This happens in two ways.
+which holds information, which controls certain aspects of its
+behavior.  This happens in two ways.
 
 - Associating a command with a certain class gives the command a type.
   This makes it possible to use generic functions to do certain things
@@ -1621,9 +1712,9 @@ This happens in two ways.
   it acts on.
 
   That in turn makes it possible for third-parties to add new types
-  without having to convince the maintainer of Transient that that new
-  type is important enough to justify adding a special case to a dozen
-  or so functions.
+  without having to convince the maintainer of Transient, that that
+  new type is important enough to justify adding a special case to a
+  dozen or so functions.
 
 - Associating a command with an object makes it possible to easily
   store information that is specific to that particular command.
@@ -1709,23 +1800,15 @@ beginning of the class specification, e.g., ~[:class 
transient-columns
 
   Functions that are called by this function may need to operate in
   the buffer from which the transient was called.  To do so they can
-  temporarily make the ~transient--source-buffer~ the current buffer.
+  temporarily make the ~transient--shadowed-buffer~ the current buffer.
 
 ** Prefix Classes
 
-Currently the ~transient-prefix~ class is being used for all prefix
-commands and there is only a single generic function that can be
-specialized based on the class of a prefix command.
-
-- Function: transient--history-init obj ::
-
-  This generic function is called while setting up the transient and
-  is responsible for initializing the ~history~ slot.  This is the
-  transient-wide history; many individual infixes also have a history
-  of their own.
-
-  The default (and currently only) method extracts the value from the
-  global variable ~transient-history~.
+Transient itself provides a single class for prefix commands,
+~transient-prefix~, but package authors may wish to define specialized
+classes.  Doing so makes it possible to change the behavior of the set
+of prefix commands that use that class, by implementing specialized
+methods for certain generic functions (see [[* Prefix Methods]]).
 
 A transient prefix command's object is stored in the ~transient--prefix~
 property of the command symbol.  While a transient is active, a clone
@@ -1773,28 +1856,97 @@ object should not affect later invocations.
 - Classes used for infix commands that represent variables should
   derived from the abstract ~transient-variable~ class.
 
-- The ~transient-information~ class is special in that suffixes that use
-  this class are not associated with a command and thus also not with
-  any key binding.  Such suffixes are only used to display arbitrary
-  information, and that anywhere a suffix can appear.  Display-only
-  suffix specifications take this form:
+- The ~transient-information~ and ~transient-information*~ classes are
+  special in that suffixes that use these class are not associated
+  with a command and thus also not with any key binding.  Such
+  suffixes are only used to display arbitrary information, and that
+  anywhere a suffix can appear.  Display-only suffix specifications
+  take these form:
 
   #+begin_src emacs-lisp
     ([LEVEL] :info DESCRIPTION [KEYWORD VALUE]...)
+    ([LEVEL] :info* DESCRIPTION [KEYWORD VALUE]...)
   #+end_src
 
-  The ~:info~ keyword argument replaces the ~:description~ keyword used for
-  other suffix classes.  Other keyword arguments that you might want to
-  set, include ~:face~, predicate keywords (such as ~:if~ and ~:inapt-if~),
-  and ~:format~.  By default the value of ~:format~ includes ~%k~, which for
-  this class is replaced with the empty string or spaces, if keys are
-  being padded in the containing group.
+  The ~:info~ and ~:info*~ keyword arguments replaces the ~:description~
+  keyword used for other suffix classes.  Other keyword arguments that
+  you might want to set, include ~:face~, predicate keywords (such as
+  ~:if~ and ~:inapt-if~), and ~:format~.  By default the value of ~:format~
+  includes ~%k~, which for this class is replaced with the empty string
+  or spaces, if keys are being padded in the containing group.
+
+  The only difference between these two classes is that ~:info*~ aligns
+  its description with the descriptions of suffix commands, while for
+  ~:info~ the description bleeds into the area where suffixes display
+  their key bindings.
+
+- The ~transient-lisp-variable~ class can be used to show and change the
+  value of lisp variables.  This class is not fully featured yet and
+  it is somewhat likely that future improvements won't be fully
+  backward compatible.
+
+- The ~transient-value-preset~ class is used to implement the command
+  ~transient-preset~, which activates a value preset.
 
 Magit defines additional classes, which can serve as examples for the
 fancy things you can do without modifying Transient.  Some of these
 classes will likely get generalized and added to Transient.  For now
 they are very much subject to change and not documented.
 
+** Prefix Methods
+
+To get information about the methods implementing these generic
+functions use ~describe-function~.
+
+- Function: transient-init-value obj ::
+
+  This generic function sets the initial value of the object {{{var(OBJ)}}}.
+  Methods exist for both prefix and suffix objects.
+
+  The default method for prefix objects sets the value of OBJ's ~value~
+  slot to the set, saved or default value.  The value that is set for
+  the current session is preferred over the saved value, which is
+  preferred over the default value.
+
+  The default value is determined using the generic function
+  ~transient-default-value~.  If you need to change how the value for a
+  prefix class is determined, its usually sufficient to implement a
+  method for that function.
+
+- Function: transient-default-value obj ::
+
+  This generic function returns the default value of the object {{{var(OBJ)}}}.
+  Methods exist for both prefix and suffix objects.
+
+  The default method for prefix objects returns the value of the
+  ~default-value~ slot if that is bound and not a function.  If it is a
+  function, that is called to get the value.  If the slot is unbound,
+  ~nil~ is returned.
+
+- Function: transient-prefix-value obj ::
+
+  This generic function returns the value of the prefix object {{{var(OBJ)}}}.
+  The respective generic function for infix and suffix objects is
+  named ~transient-infix-value~.
+
+- Function: transient-init-scope obj ::
+
+  This generic function sets the scope of the object {{{var(OBJ)}}}.  Methods
+  exist for both prefix and suffix objects.
+
+  This function is called for all prefix and suffix commands, but
+  unless a concrete method is implemented this falls through to
+  the default implementation, which is a noop.
+
+~transient-set-value~, ~transient-save-value~, ~transient-reset-value~,
+~transient--history-key~, ~transient--history-push~ and
+~transient--history-init~ are other generic functions dealing with the
+value of prefix objects.  See their doc-strings for more information.
+
+~transient-show-help~ is another generic function implemented for prefix
+commands.  The default method effectively describes the command using
+~describe-function~.
+
 ** Suffix Methods
 
 To get information about the methods implementing these generic
@@ -1856,7 +2008,8 @@ functions use ~describe-function~.
 
 - Function: transient-init-scope obj ::
 
-  This generic function sets the scope of the suffix object {{{var(OBJ)}}}.
+  This generic function sets the scope of the object {{{var(OBJ)}}}.  Methods
+  exist for both prefix and suffix objects.
 
   The scope is actually a property of the transient prefix, not of
   individual suffixes.  However it is possible to invoke a suffix
@@ -1864,12 +2017,14 @@ functions use ~describe-function~.
   the suffix expects a scope, then it has to determine that itself
   and store it in its ~scope~ slot.
 
-  This function is called for all suffix commands, but unless a
-  concrete method is implemented this falls through to the default
-  implementation, which is a noop.
+  This function is called for all prefix and suffix commands, but
+  unless a concrete method is implemented, this falls through to
+  the default implementation, which is a noop.
 
 *** Suffix Format Methods
 
+# Low-level transient--init-suffix-key intentionally left out.
+
 - Function: transient-format obj ::
 
   This generic function formats and returns {{{var(OBJ)}}} for display.
@@ -1899,7 +2054,7 @@ functions use ~describe-function~.
   Show help for the prefix, infix or suffix command represented by
   {{{var(OBJ)}}}.
 
-  Regardless of OBJ's type, if its ~show-help~ slot is non-nil, that
+  Regardless of OBJ's type, if its ~show-help~ slot is non-~nil~, that
   must be a function, which takes OBJ is its only argument.  It must
   prepare, display and return a buffer, and select the window used to
   display it.  The ~transient-show-help-window~ macro is intended for
@@ -1934,35 +2089,31 @@ functions use ~describe-function~.
   If OBJ's ~summary~ slot is a string, that is used.  If ~summary~ is a
   function, that is called with OBJ as the only argument and the
   returned string is used.  If ~summary~ is or returns something other
-  than a string or nil, no summary is shown.  If ~summary~ is or returns
+  than a string or ~nil~, no summary is shown.  If ~summary~ is or returns
   ~nil~, the first line of the documentation string is used, if any.
 
   If RETURN is non-~nil~, this function returns the summary instead of
   showing it.  This is used when a tooltip is needed.
 
 ** Prefix Slots
+*** Value and Scope
+:PROPERTIES:
+:UNNUMBERED: notoc
+:END:
 
-- ~show-help~, ~man-page~ or ~info-manual~ can be used to specify the
-  documentation for the prefix and its suffixes.  The command
-  ~transient-help~ uses the function ~transient-show-help~ (which see) to
-  lookup and use these values.
+- ~default-value~ The default value of the prefix.  Use the keyword
+  argument ~:value~ (sic) to set this slot in the definition of a
+  prefix.
+
+- ~init-value~ A function that is responsible for setting the object's
+  value.  If bound, then this is called with the object as the only
+  argument.  Usually this is not bound, in which case the object's
+  primary ~transient-init-value~ method is called instead.
 
 - ~history-key~ If multiple prefix commands should share a single value,
   then this slot has to be set to the same value for all of them.  You
   probably don't want that.
 
-- ~transient-suffix~ and ~transient-non-suffix~ play a part when
-  determining whether the currently active transient prefix command
-  remains active/transient when a suffix or arbitrary non-suffix
-  command is invoked.  See [[*Transient State]].
-
-- ~refresh-suffixes~ Normally suffix objects and keymaps are only setup
-  once, when the prefix is invoked.  Setting this to ~t~, causes them to
-  be recreated after every command.  This is useful when using ~:if...~
-  predicates, and those need to be rerun for some reason.  Doing this
-  is somewhat costly, and there is a risk of losing state, so this is
-  disabled by default and still considered experimental.
-
 - ~incompatible~ A list of lists.  Each sub-list specifies a set of
   mutually exclusive arguments.  Enabling one of these arguments
   causes the others to be disabled.  An argument may appear in
@@ -1973,16 +2124,70 @@ functions use ~describe-function~.
   against a specific value, as returned by ~transient-infix-value~,
   for example, ~--option=one~.
 
+- ~scope~ For some transients it might be necessary to have a sort of
+  secondary value, called a “scope”.  See ~transient-define-prefix~.
+
+*** Behavior
+:PROPERTIES:
+:UNNUMBERED: notoc
+:END:
+
+- ~transient-suffix~, ~transient-non-suffix~ and ~transient-switch-frame~
+  play a part when determining whether the currently active transient
+  prefix command remains active/transient when a suffix or arbitrary
+  non-suffix command is invoked.  See [[*Transient State]].
+
+- ~refresh-suffixes~ Normally suffix objects and keymaps are only setup
+  once, when the prefix is invoked.  Setting this to ~t~, causes them to
+  be recreated after every command.  This is useful when using ~:if...~
+  predicates, and those need to be rerun for some reason.  Doing this
+  is somewhat costly, and there is a risk of losing state, so this is
+  disabled by default and still considered experimental.
+
+- ~environment~ A function used to establish an environment while
+  initializing, refreshing or redisplaying a transient prefix menu.
+  This is useful to establish a cache, in case multiple suffixes
+  require the same expensive work.  The provided function is called
+  with at least one argument, the function for which it establishes
+  the environment.  It must ~funcall~ that function with no arguments.
+  During initialization the second argument is the prefix object
+  being initialized.  This slot is still experimental.
+
+*** Appearance
+:PROPERTIES:
+:UNNUMBERED: notoc
+:END:
+
 - ~display-action~ determines how this prefix is displayed, overriding
   ~transient-display-buffer-action~.  It should have the same type.
 
 - ~mode-line-format~ is this prefix's mode line format, overriding
   ~transient-mode-line-format~.  It should have the same type.
 
-- ~scope~ For some transients it might be necessary to have a sort of
-  secondary value, called a “scope”.  See ~transient-define-prefix~.
+- ~column-width~ is only respected inside ~transient-columns~ groups and
+  allows aligning columns across separate instances of that.
+
+- ~variable-pitch~ controls whether alignment is done pixel-wise to
+  account for use of variable-pitch characters, which is useful, e.g.,
+  when using emoji.
+
+*** Documentation
+:PROPERTIES:
+:UNNUMBERED: notoc
+:END:
+
+- ~show-help~, ~man-page~ or ~info-manual~ can be used to specify the
+  documentation for the prefix and its suffixes.  The command
+  ~transient-help~ uses the function ~transient-show-help~ (which see) to
+  lookup and use these values.
 
-*** Internal Prefix Slots
+- ~suffix-description~ can be used to specify a function which provides
+  fallback descriptions for suffixes that lack a description.  This
+  is intended to be temporarily used when implementing of a new prefix
+  command, at which time ~transient-command-summary-or-name~ is a useful
+  value.
+
+*** Internal
 :PROPERTIES:
 :UNNUMBERED: notoc
 :END:
@@ -2011,6 +2216,9 @@ set in calls to ~transient-define-prefix~.
   Unless you implement your own ~transient-infix-read~ method you should
   not have to deal with these slots.
 
+- ~unwind-suffix~ is used internally to ensure transient state is
+  properly exited, even in case of an error.
+
 ** Suffix Slots
 
 Here we document most of the slots that are only available for suffix
@@ -2019,6 +2227,15 @@ documented in [[*Predicate Slots]].
 
 Also see [[*Suffix Classes]].
 
+*** Slots of ~transient-child~
+:PROPERTIES:
+:UNNUMBERED: notoc
+:END:
+
+This is the abstract superclass of ~transient-suffix~ and ~transient-group~.
+This is where the shared ~if*~ and ~inapt-if*~ slots (see [[*Predicate Slots]])
+and the ~level~ slot (see [[*Enabling and Disabling Suffixes]]) are defined.
+
 *** Slots of ~transient-suffix~
 :PROPERTIES:
 :UNNUMBERED: notoc
@@ -2054,6 +2271,9 @@ Also see [[*Suffix Classes]].
   documentation string is used instead.  See ~transient-show-summary~
   for details.
 
+- ~definition~ A command, which is used if the body is omitted when
+  defining a command using ~transient-define-suffix~.
+
 *** Slots of ~transient-infix~
 :PROPERTIES:
 :UNNUMBERED: notoc
@@ -2363,14 +2583,14 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
See the GNU
 General Public License for more details.
 #+end_quote
 
-#  LocalWords:  ARGLIST ARGS DOCSTRING ELEMENTs EVAL GROUPs Infixes
+#  LocalWords:  ARGLIST ARGS CLI DOCSTRING ELEMENTs EVAL GROUPs Infixes
 #  LocalWords:  Infixes KEYWORDs LOC LocalWords MERCHANTABILITY Magit
-#  LocalWords:  Magit's Makefile OBJ OBJ's Pre arglist
-#  LocalWords:  args boolean booleans customizable docstring eval
-#  LocalWords:  featurep infixes init keymap keymaps loc magit manpage
-#  LocalWords:  minibuffer ness nilly noop plist pre prev
-#  LocalWords:  rebase src subclass subclasses subprocess superclass
-#  LocalWords:  utils
+#  LocalWords:  Magit's Makefile OBJ OBJ's Pre alist arglist
+#  LocalWords:  args autoloaded boolean booleans customizable docstring
+#  LocalWords:  eval featurep infixes init isearch keymap keymaps loc
+#  LocalWords:  magit manpage minibuffer monospaced ness nilly noop
+#  LocalWords:  plist pre prev rebase redisplay src subclass subclasses
+#  LocalWords:  subcommands subprocess superclass tooltip termcap utils
 
 # IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile.
 # Local Variables:
diff --git a/docs/transient.texi b/docs/transient.texi
index 33be8f44e4..34865e0036 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -93,6 +93,8 @@ Defining New Commands
 * Binding Suffix and Infix Commands::
 * Defining Suffix and Infix Commands::
 * Using Infix Arguments::
+* Current Suffix Command::
+* Current Prefix Command::
 * Transient State::
 
 Binding Suffix and Infix Commands
@@ -107,6 +109,7 @@ Classes and Methods
 * Group Methods::
 * Prefix Classes::
 * Suffix Classes::
+* Prefix Methods::
 * Suffix Methods::
 * Prefix Slots::
 * Suffix Slots::
@@ -224,12 +227,13 @@ A transient prefix command is invoked like any other 
command by
 pressing the key that is bound to that command.  The main difference
 to other commands is that a transient prefix command activates a
 transient keymap, which temporarily binds the transient's infix and
-suffix commands.  Bindings from other keymaps may, or may not, be
-disabled while the transient state is in effect.
+suffix commands, and that those bindings are displayed in a transient
+menu, displayed in a popup buffer.  Bindings from other keymaps may,
+or may not, be disabled while the transient state is in effect.
 
 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
+set some value (which is then shown in the 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}.
@@ -349,9 +353,6 @@ Emacs session by typing @kbd{C-x t} while a transient is 
active.
 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
 
@@ -383,13 +384,13 @@ session.
 @item @kbd{C-x C-s} (@code{transient-save})
 @kindex C-x C-s
 @findex transient-save
-Save the value of the active transient persistently across Emacs
-sessions.
+This command saves the value of the active transient persistently
+across Emacs sessions.
 
 @item @kbd{C-x C-k} (@code{transient-reset})
 @kindex C-x C-k
 @findex transient-reset
-Clear the set and saved values of the active transient.
+This command clears the set and saved values of the active transient.
 @end table
 
 @defopt transient-values-file
@@ -403,8 +404,8 @@ transients between Emacs sessions.
 @cindex value history
 
 Every time the user invokes a suffix command the transient's current
-value is saved to its history.  These values can be cycled through the
-same way one can cycle through the history of commands that read
+value is saved to its history.  These values can be cycled through,
+the same way one can cycle through the history of commands that read
 user-input in the minibuffer.
 
 @table @asis
@@ -425,11 +426,11 @@ 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.
+In addition to the transient-wide history, infixes can have their own
+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.
 
 Authors of transients should arrange for different infix commands that
 read the same kind of value to also use the same history key (see
@@ -643,7 +644,7 @@ minibuffer is entered, irrespective of the value of this 
option.
 
 When @code{nil} (the default), hide the menu while the minibuffer is in use.
 When @code{t}, keep showing the menu, but allow for the menu window to be
-resized to ensure that completion candidates can be displayed.
+resized, to ensure that completion candidates can be displayed.
 
 When @code{fixed}, keep showing the menu and prevent it from being resized,
 which may make it impossible to display the completion candidates.  If
@@ -676,13 +677,14 @@ element has to be accessed the same way as the older 
elements.
 
 @defopt transient-enable-popup-navigation
 This option controls whether navigation commands are enabled in the
-transient popup buffer.  If the value is @code{verbose}, additionally show
-brief documentation about the command under point in the echo area.
+transient popup buffer.  If the value is @code{verbose} (the default),
+brief documentation about the command under point is additionally
+show in the echo area.
 
 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-@code{nil}, then the following features are available:
+on that buffer itself.  If this option is non-@code{nil}, then the
+following features are available:
 
 @itemize
 @item
@@ -718,15 +720,14 @@ The default is:
 
 @lisp
 (display-buffer-in-side-window
-  (side . bottom)
-  (inhibit-same-window . t)
-  (window-parameters (no-other-window . t)))
+ (side . bottom)
+ (dedicated . t)
+ (inhibit-same-window . t))
 @end lisp
 
 This displays the window at the bottom of the selected frame.
-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 @ref{Buffer Display Action 
Alists,,,elisp,}.
+For alternatives see @ref{Buffer Display Action Functions,,,elisp,},
+and @ref{Buffer Display Action Alists,,,elisp,}.
 
 Note that the buffer that was current before the transient buffer
 is shown should remain the current buffer.  Many suffix commands
@@ -891,6 +892,18 @@ suffixes that won't be available to users without them 
making the
 same customization.
 @end defopt
 
+@anchor{Hook Variables}
+@subheading Hook Variables
+
+@defvar transient-exit-hook
+This hook is run after a transient is exited.
+@end defvar
+
+@defvar transient-setup-buffer-hook
+This hook is run when the transient buffer is being setup.
+That buffer is current and empty when this hook is runs.
+@end defvar
+
 @node Modifying Existing Transients
 @chapter Modifying Existing Transients
 
@@ -999,6 +1012,8 @@ signal an error.
 * Binding Suffix and Infix Commands::
 * Defining Suffix and Infix Commands::
 * Using Infix Arguments::
+* Current Suffix Command::
+* Current Prefix Command::
 * Transient State::
 @end menu
 
@@ -1042,7 +1057,7 @@ arguments have been set using a command such as 
@code{universal-argument}.
 @cindex command dispatchers
 Transient can be used to implement simple ``command dispatchers''.  The
 main benefit then is that the user can see all the available commands
-in a popup buffer, which can be thought of as a ``menus''.  That is
+in a popup buffer, which can be thought of as a ``menu''.  That is
 useful by itself because it frees the user from having to remember all
 the keys that are valid after a certain prefix key or command.
 Magit's @code{magit-dispatch} (on @kbd{C-x M-g}) command is an example of using
@@ -1522,8 +1537,17 @@ command was not invoked from @var{PREFIX}, then it 
returns the set, saved
 or default value for @var{PREFIX}.
 @end defun
 
+@defun transient-get-value
+This function returns the value of the current prefix.
+
+This is mostly intended for internal use, but may also be of use
+in @code{transient-set-value} and @code{transient-save-value} methods.  Unlike
+@code{transient-args}, this does not include the values of suffixes whose
+@code{unsavable} slot is non-@code{nil}.
+@end defun
+
 @defun transient-arg-value arg args
-This function return the value of @var{ARG} as it appears in @var{ARGS}.
+This function returns 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,
@@ -1537,6 +1561,53 @@ used if you need the objects (as opposed to just their 
values) and
 if the current command is not being invoked from @var{PREFIX}.
 @end defun
 
+@node Current Suffix Command
+@section Current Suffix Command
+
+@defun transient-suffix-object command
+This function returns the object associated with the current suffix
+command.
+
+Each suffix commands is associated with an object, which holds
+additional information about the suffix, such as its value (in
+the case of an infix command, which is a kind of suffix command).
+
+This function is intended to be called by infix commands, which
+are usually aliases of @code{transient--default-infix-command}, which
+is defined like this:
+
+@lisp
+(defun transient--default-infix-command ()
+  (interactive)
+  (let ((obj (transient-suffix-object)))
+    (transient-infix-set obj (transient-infix-read obj)))
+  (transient--show))
+@end lisp
+
+(User input is read outside of @code{interactive} to prevent the
+command from being added to @code{command-history}.)
+
+Such commands need to be able to access their associated object
+to guide how @code{transient-infix-read} reads the new value and to
+store the read value.  Other suffix commands (including non-infix
+commands) may also need the object to guide their behavior.
+
+This function attempts to return the object associated with the
+current suffix command even if the suffix command was not invoked
+from a transient.  (For some suffix command that is a valid thing
+to do, for others it is not.)  In that case @code{nil} may be returned,
+if the command was not defined using one of the macros intended
+to define such commands.
+
+The optional argument COMMAND is intended for internal use.  If
+you are contemplating using it in your own code, then you should
+probably use this instead:
+
+@lisp
+(get COMMAND 'transient--suffix)
+@end lisp
+@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
@@ -1545,21 +1616,49 @@ values.  In complex cases it might be necessary to use 
this variable
 instead, i.e., if you need access to information beside the value.
 @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 Current Prefix Command
+@section Current Prefix Command
+
+@defun transient-prefix-object
+This function returns the current prefix as an object.
+
+While a transient is being setup or refreshed (which involves
+preparing its suffixes) the variable @code{transient--prefix} can be
+used to access the prefix object.  Thus this is what has to be
+used in suffix methods such as @code{transient-format-description},
+and in object-specific functions that are stored in suffix slots
+such as @code{description}.
+
+When a suffix command is invoked (i.e., in its @code{interactive} form
+and function body) then the variable @code{transient-current-prefix}
+has to be used instead.
+
+Two distinct variables are needed, because any prefix may itself
+be used as a suffix of another prefix, and such sub-prefixes have
+to be able to tell themselves apart from the prefix they were
+invoked from.
+
+Regular suffix commands, which are not prefixes, do not have to
+concern themselves with this distinction, so they can use this
+function instead.  In the context of a plain suffix, it always
+returns the value of the appropriate variable.
+@end defun
 
 @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.
+The transient from which this suffix command was invoked.  The value
+is a @code{transient-prefix} object, which holds information associated
+with the transient prefix command.
 @end defvar
 
-@defun transient-active-prefix
-This function returns the active transient object.  Return @code{nil} if
-there is no active transient, if the transient buffer isn't shown,
-and while the active transient is suspended (e.g., while the
+@defvar transient-current-command
+The transient from which this suffix command was invoked.  The value
+is a symbol, the transient prefix command.
+@end defvar
+
+@defun transient-active-prefix &optional prefixes
+This function returns the active transient object.  It returns @code{nil}
+if there is no active transient, if the transient buffer isn't
+shown, and while the active transient is suspended (e.g., while the
 minibuffer is in use).
 
 Unlike @code{transient-current-prefix}, which is only ever non-@code{nil} in 
code
@@ -1817,14 +1916,12 @@ This is used when the user pressed @kbd{C-z}.
 @cindex classes and methods
 
 Transient uses classes and generic functions to make it possible to
-define new types of suffix commands that are similar to existing
-types, but behave differently in some aspects.  It does the same for
-groups and prefix commands, though at least for prefix commands that
-@strong{currently} appears to be less important.
+define new types of suffix and prefix commands, which are similar to
+existing types, but behave differently in some respects.
 
 Every prefix, infix and suffix command is associated with an object,
-which holds information that controls certain aspects of its behavior.
-This happens in two ways.
+which holds information, which controls certain aspects of its
+behavior.  This happens in two ways.
 
 @itemize
 @item
@@ -1834,9 +1931,9 @@ that have to be done differently depending on what type 
of command
 it acts on.
 
 That in turn makes it possible for third-parties to add new types
-without having to convince the maintainer of Transient that that new
-type is important enough to justify adding a special case to a dozen
-or so functions.
+without having to convince the maintainer of Transient, that that
+new type is important enough to justify adding a special case to a
+dozen or so functions.
 
 @item
 Associating a command with an object makes it possible to easily
@@ -1862,6 +1959,7 @@ differ even between different commands of the same type.
 * Group Methods::
 * Prefix Classes::
 * Suffix Classes::
+* Prefix Methods::
 * Suffix Methods::
 * Prefix Slots::
 * Suffix Slots::
@@ -1944,25 +2042,17 @@ The contents of that buffer are later inserted into the 
popup buffer.
 
 Functions that are called by this function may need to operate in
 the buffer from which the transient was called.  To do so they can
-temporarily make the @code{transient--source-buffer} the current buffer.
+temporarily make the @code{transient--shadowed-buffer} the current buffer.
 @end defun
 
 @node Prefix Classes
 @section Prefix Classes
 
-Currently the @code{transient-prefix} class is being used for all prefix
-commands and there is only a single generic function that can be
-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
-of their own.
-
-The default (and currently only) method extracts the value from the
-global variable @code{transient-history}.
-@end defun
+Transient itself provides a single class for prefix commands,
+@code{transient-prefix}, but package authors may wish to define specialized
+classes.  Doing so makes it possible to change the behavior of the set
+of prefix commands that use that class, by implementing specialized
+methods for certain generic functions (see @ref{Prefix Methods}).
 
 A transient prefix command's object is stored in the @code{transient--prefix}
 property of the command symbol.  While a transient is active, a clone
@@ -2020,22 +2110,39 @@ Classes used for infix commands that represent 
variables should
 derived from the abstract @code{transient-variable} class.
 
 @item
-The @code{transient-information} class is special in that suffixes that use
-this class are not associated with a command and thus also not with
-any key binding.  Such suffixes are only used to display arbitrary
-information, and that anywhere a suffix can appear.  Display-only
-suffix specifications take this form:
+The @code{transient-information} and @code{transient-information*} classes are
+special in that suffixes that use these class are not associated
+with a command and thus also not with any key binding.  Such
+suffixes are only used to display arbitrary information, and that
+anywhere a suffix can appear.  Display-only suffix specifications
+take these form:
 
 @lisp
 ([LEVEL] :info DESCRIPTION [KEYWORD VALUE]...)
+([LEVEL] :info* DESCRIPTION [KEYWORD VALUE]...)
 @end lisp
 
-The @code{:info} keyword argument replaces the @code{:description} keyword 
used for
-other suffix classes.  Other keyword arguments that you might want to
-set, include @code{:face}, predicate keywords (such as @code{:if} and 
@code{:inapt-if}),
-and @code{:format}.  By default the value of @code{:format} includes 
@code{%k}, which for
-this class is replaced with the empty string or spaces, if keys are
-being padded in the containing group.
+The @code{:info} and @code{:info*} keyword arguments replaces the 
@code{:description}
+keyword used for other suffix classes.  Other keyword arguments that
+you might want to set, include @code{:face}, predicate keywords (such as
+@code{:if} and @code{:inapt-if}), and @code{:format}.  By default the value of 
@code{:format}
+includes @code{%k}, which for this class is replaced with the empty string
+or spaces, if keys are being padded in the containing group.
+
+The only difference between these two classes is that @code{:info*} aligns
+its description with the descriptions of suffix commands, while for
+@code{:info} the description bleeds into the area where suffixes display
+their key bindings.
+
+@item
+The @code{transient-lisp-variable} class can be used to show and change the
+value of lisp variables.  This class is not fully featured yet and
+it is somewhat likely that future improvements won't be fully
+backward compatible.
+
+@item
+The @code{transient-value-preset} class is used to implement the command
+@code{transient-preset}, which activates a value preset.
 @end itemize
 
 Magit defines additional classes, which can serve as examples for the
@@ -2043,6 +2150,61 @@ fancy things you can do without modifying Transient.  
Some of these
 classes will likely get generalized and added to Transient.  For now
 they are very much subject to change and not documented.
 
+@node Prefix Methods
+@section Prefix Methods
+
+To get information about the methods implementing these generic
+functions use @code{describe-function}.
+
+@defun transient-init-value obj
+This generic function sets the initial value of the object @var{OBJ}.
+Methods exist for both prefix and suffix objects.
+
+The default method for prefix objects sets the value of OBJ's @code{value}
+slot to the set, saved or default value.  The value that is set for
+the current session is preferred over the saved value, which is
+preferred over the default value.
+
+The default value is determined using the generic function
+@code{transient-default-value}.  If you need to change how the value for a
+prefix class is determined, its usually sufficient to implement a
+method for that function.
+@end defun
+
+@defun transient-default-value obj
+This generic function returns the default value of the object @var{OBJ}.
+Methods exist for both prefix and suffix objects.
+
+The default method for prefix objects returns the value of the
+@code{default-value} slot if that is bound and not a function.  If it is a
+function, that is called to get the value.  If the slot is unbound,
+@code{nil} is returned.
+@end defun
+
+@defun transient-prefix-value obj
+This generic function returns the value of the prefix object @var{OBJ}.
+The respective generic function for infix and suffix objects is
+named @code{transient-infix-value}.
+@end defun
+
+@defun transient-init-scope obj
+This generic function sets the scope of the object @var{OBJ}.  Methods
+exist for both prefix and suffix objects.
+
+This function is called for all prefix and suffix commands, but
+unless a concrete method is implemented this falls through to
+the default implementation, which is a noop.
+@end defun
+
+@code{transient-set-value}, @code{transient-save-value}, 
@code{transient-reset-value},
+@code{transient--history-key}, @code{transient--history-push} and
+@code{transient--history-init} are other generic functions dealing with the
+value of prefix objects.  See their doc-strings for more information.
+
+@code{transient-show-help} is another generic function implemented for prefix
+commands.  The default method effectively describes the command using
+@code{describe-function}.
+
 @node Suffix Methods
 @section Suffix Methods
 
@@ -2110,7 +2272,8 @@ Usually only infixes have a value, but see the method for
 @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 object @var{OBJ}.  Methods
+exist for both prefix and suffix objects.
 
 The scope is actually a property of the transient prefix, not of
 individual suffixes.  However it is possible to invoke a suffix
@@ -2118,9 +2281,9 @@ command directly instead of from a transient.  In that 
case, if
 the suffix expects a scope, then it has to determine that itself
 and store it in its @code{scope} slot.
 
-This function is called for all suffix commands, but unless a
-concrete method is implemented this falls through to the default
-implementation, which is a noop.
+This function is called for all prefix and suffix commands, but
+unless a concrete method is implemented, this falls through to
+the default implementation, which is a noop.
 @end defun
 
 @node Suffix Format Methods
@@ -2154,7 +2317,7 @@ the result.
 Show help for the prefix, infix or suffix command represented by
 @var{OBJ}.
 
-Regardless of OBJ's type, if its @code{show-help} slot is non-nil, that
+Regardless of OBJ's type, if its @code{show-help} slot is non-@code{nil}, that
 must be a function, which takes OBJ is its only argument.  It must
 prepare, display and return a buffer, and select the window used to
 display it.  The @code{transient-show-help-window} macro is intended for
@@ -2189,7 +2352,7 @@ the user navigates to a command using the keyboard.
 If OBJ's @code{summary} slot is a string, that is used.  If @code{summary} is a
 function, that is called with OBJ as the only argument and the
 returned string is used.  If @code{summary} is or returns something other
-than a string or nil, no summary is shown.  If @code{summary} is or returns
+than a string or @code{nil}, no summary is shown.  If @code{summary} is or 
returns
 @code{nil}, the first line of the documentation string is used, if any.
 
 If RETURN is non-@code{nil}, this function returns the summary instead of
@@ -2199,12 +2362,20 @@ showing it.  This is used when a tooltip is needed.
 @node Prefix Slots
 @section Prefix Slots
 
+@anchor{Value and Scope}
+@subheading Value and Scope
+
 @itemize
 @item
-@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 function @code{transient-show-help} (which see) 
to
-lookup and use these values.
+@code{default-value} The default value of the prefix.  Use the keyword
+argument @code{:value} (sic) to set this slot in the definition of a
+prefix.
+
+@item
+@code{init-value} A function that is responsible for setting the object's
+value.  If bound, then this is called with the object as the only
+argument.  Usually this is not bound, in which case the object's
+primary @code{transient-init-value} method is called instead.
 
 @item
 @code{history-key} If multiple prefix commands should share a single value,
@@ -2212,10 +2383,30 @@ then this slot has to be set to the same value for all 
of them.  You
 probably don't want that.
 
 @item
-@code{transient-suffix} and @code{transient-non-suffix} play a part when
-determining whether the currently active transient prefix command
-remains active/transient when a suffix or arbitrary non-suffix
-command is invoked.  See @ref{Transient State}.
+@code{incompatible} A list of lists.  Each sub-list specifies a set of
+mutually exclusive arguments.  Enabling one of these arguments
+causes the others to be disabled.  An argument may appear in
+multiple sub-lists.  Arguments must me given in the same form as
+used in the @code{argument} or @code{argument-format} slot of the respective
+suffix objects, usually something like @code{--switch} or @code{--option=%s}.  
For
+options and @code{transient-switches} suffixes it is also possible to match
+against a specific value, as returned by @code{transient-infix-value},
+for example, @code{--option=one}.
+
+@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}.
+@end itemize
+
+@anchor{Behavior}
+@subheading Behavior
+
+@itemize
+@item
+@code{transient-suffix}, @code{transient-non-suffix} and 
@code{transient-switch-frame}
+play a part when determining whether the currently active transient
+prefix command remains active/transient when a suffix or arbitrary
+non-suffix command is invoked.  See @ref{Transient State}.
 
 @item
 @code{refresh-suffixes} Normally suffix objects and keymaps are only setup
@@ -2226,16 +2417,20 @@ is somewhat costly, and there is a risk of losing 
state, so this is
 disabled by default and still considered experimental.
 
 @item
-@code{incompatible} A list of lists.  Each sub-list specifies a set of
-mutually exclusive arguments.  Enabling one of these arguments
-causes the others to be disabled.  An argument may appear in
-multiple sub-lists.  Arguments must me given in the same form as
-used in the @code{argument} or @code{argument-format} slot of the respective
-suffix objects, usually something like @code{--switch} or @code{--option=%s}.  
For
-options and @code{transient-switches} suffixes it is also possible to match
-against a specific value, as returned by @code{transient-infix-value},
-for example, @code{--option=one}.
+@code{environment} A function used to establish an environment while
+initializing, refreshing or redisplaying a transient prefix menu.
+This is useful to establish a cache, in case multiple suffixes
+require the same expensive work.  The provided function is called
+with at least one argument, the function for which it establishes
+the environment.  It must @code{funcall} that function with no arguments.
+During initialization the second argument is the prefix object
+being initialized.  This slot is still experimental.
+@end itemize
+
+@anchor{Appearance}
+@subheading Appearance
 
+@itemize
 @item
 @code{display-action} determines how this prefix is displayed, overriding
 @code{transient-display-buffer-action}.  It should have the same type.
@@ -2245,12 +2440,35 @@ for example, @code{--option=one}.
 @code{transient-mode-line-format}.  It should have the same type.
 
 @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}.
+@code{column-width} is only respected inside @code{transient-columns} groups 
and
+allows aligning columns across separate instances of that.
+
+@item
+@code{variable-pitch} controls whether alignment is done pixel-wise to
+account for use of variable-pitch characters, which is useful, e.g.,
+when using emoji.
+@end itemize
+
+@anchor{Documentation}
+@subheading Documentation
+
+@itemize
+@item
+@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 function @code{transient-show-help} (which see) 
to
+lookup and use these values.
+
+@item
+@code{suffix-description} can be used to specify a function which provides
+fallback descriptions for suffixes that lack a description.  This
+is intended to be temporarily used when implementing of a new prefix
+command, at which time @code{transient-command-summary-or-name} is a useful
+value.
 @end itemize
 
-@anchor{Internal Prefix Slots}
-@subheading Internal Prefix Slots
+@anchor{Internal}
+@subheading Internal
 
 These slots are mostly intended for internal use.  They should not be
 set in calls to @code{transient-define-prefix}.
@@ -2280,6 +2498,10 @@ which is guaranteed to return the up-to-date value.
 @code{history} and @code{history-pos} are used to keep track of historic 
values.
 Unless you implement your own @code{transient-infix-read} method you should
 not have to deal with these slots.
+
+@item
+@code{unwind-suffix} is used internally to ensure transient state is
+properly exited, even in case of an error.
 @end itemize
 
 @node Suffix Slots
@@ -2291,6 +2513,13 @@ documented in @ref{Predicate Slots}.
 
 Also see @ref{Suffix Classes}.
 
+@anchor{Slots of @code{transient-child}}
+@subheading Slots of @code{transient-child}
+
+This is the abstract superclass of @code{transient-suffix} and 
@code{transient-group}.
+This is where the shared @code{if*} and @code{inapt-if*} slots (see 
@ref{Predicate Slots})
+and the @code{level} slot (see @ref{Enabling and Disabling Suffixes}) are 
defined.
+
 @anchor{Slots of @code{transient-suffix}}
 @subheading Slots of @code{transient-suffix}
 
@@ -2337,6 +2566,10 @@ suffixes.  See also function @code{transient-show-help}.
 If this is @code{nil}, which it usually should be, the first line of the
 documentation string is used instead.  See @code{transient-show-summary}
 for details.
+
+@item
+@code{definition} A command, which is used if the body is omitted when
+defining a command using @code{transient-define-suffix}.
 @end itemize
 
 @anchor{Slots of @code{transient-infix}}