[wip] Update manual

Author: tarsius

docs/transient.org

@@ -860,12 +860,15 @@ with an example:
 #+end_src
 
 This inserts a new infix argument to toggle the ~--reverse~ argument
-after the infix argument that toggles ~-3~ in ~magit-patch-apply~.
+after the infix argument that is bound to ~-3~ in ~magit-patch-apply~.
 
 The following functions share a few arguments:
 
 - {{{var(PREFIX)}}} is a transient prefix command, a symbol.
 
+  PREFIX may also by a symbol identify a separately defined group,
+  which can be included in multiple prefixes.  See TODO.
+
 - {{{var(SUFFIX)}}} is a transient infix or suffix specification in the same form
   as expected by ~transient-define-prefix~.  Note that an infix is a
   special kind of suffix.  Depending on context “suffixes” means
@@ -876,23 +879,23 @@ The following functions share a few arguments:
   ~transient-define-prefix~.  See [[*Group Specifications]].
 
 - {{{var(LOC)}}} is a command, a key description (a string as returned by
-  ~key-description~ and understood by ~kbd~), or a list specifying
+  ~key-description~ and understood by ~kbd~), or a vector specifying
   coordinates (the last element may also be a command or key).  For
-  example ~(1 0 -1)~ identifies the last suffix (~-1~) of the first
+  example ~[1 0 -1]~ identifies the last suffix (~-1~) of the first
   subgroup (~0~) of the second group (~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 function ~transient-get-suffix~ can be useful to determine whether
   a certain coordination list 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 ~transient--get-layout~.
 
 These functions operate on the information stored in the
 ~transient--layout~ property of the {{{var(PREFIX)}}} symbol.  Suffix entries in
-that tree are not objects but have the form {{{codevar((LEVEL CLASS PLIST))}}}, where
-{{{var(PLIST)}}} should set at least ~:key~, ~:description~ and ~:command~.
+that tree are not objects but have the form {{{codevar((CLASS PLIST))}}}.
 
 - Function: transient-insert-suffix prefix loc suffix &optional keep-other ::
 - Function: transient-append-suffix prefix loc suffix &optional keep-other ::
@@ -930,6 +933,19 @@ that tree are not objects but have the form {{{codevar((LEVEL CLASS PLIST))}}},
   This function edits the suffix or group at {{{var(LOC)}}} in {{{var(PREFIX)}}}, by setting
   the {{{var(PROP)}}} of its plist to {{{var(VALUE)}}}.
 
+Some prefix commands share suffixes, which are seperately 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
+~magit-diff~ (~d~) the same change also applies to ~magit-diff-refresh~ (~D~).
+In the rare case that this is not desirable use ~transient-inline-group~
+before making changes to included suffixes.
+
+- Function: 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.
+
 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
@@ -1095,6 +1111,22 @@ that is used to invoke that transient.
   For example, the scope of the ~magit-branch-configure~ transient is
   the branch whose variables are being configured.
 
+Sometimes multiple prefix commands share a common set of suffixes.
+For example, while ~magit-diff~ (~d~) and ~magit-diff-refresh~ (~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 ~transient-define-group~
+and then included in mulitple 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.
+
+- Macro: transient-define-group name group... ::
+
+  This macro define one or more groups and stores them in symbol NAME.
+  GROUPs have the same form as for ~transient-define-prefix~.
+
 ** Binding Suffix and Infix Commands
 
 The macro ~transient-define-prefix~ is used to define a transient.