[elpa] externals/transient 0d9a1b5536 107/366: manual: Document prefix slots

[Jonas Bernoulli]

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

    manual: Document prefix slots
---
 docs/transient.org  | 56 +++++++++++++++++++++++++++++++++++++---
 docs/transient.texi | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 124 insertions(+), 6 deletions(-)

diff --git a/docs/transient.org b/docs/transient.org
index 488525d451..2868f65080 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -8,7 +8,7 @@
 #+TEXINFO_DIR_CATEGORY: Emacs
 #+TEXINFO_DIR_TITLE: Transient: (transient).
 #+TEXINFO_DIR_DESC: Transient Commands
-#+SUBTITLE: for version 0.1.0 (v0.1.0-103-g68f31ed+1)
+#+SUBTITLE: for version 0.1.0 (v0.1.0-105-g0cad5eb+1)
 
 #+TEXINFO_DEFFN: t
 #+OPTIONS: H:4 num:4 toc:2
@@ -37,7 +37,7 @@ Calling a suffix command usually causes the transient to be 
exited
 but suffix commands can also be configured to not exit the transient.
 
 #+TEXINFO: @noindent
-This manual is for Transient version 0.1.0 (v0.1.0-103-g68f31ed+1).
+This manual is for Transient version 0.1.0 (v0.1.0-105-g0cad5eb+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2018-2019 Jonas Bernoulli <jonas@bernoul.li>
@@ -1457,7 +1457,57 @@ functions use ~describe-function~.
   For infixes, show the manpage if that is specified.  Otherwise show
   the command's doc string.
 
-** TODO Prefix Slots
+** Prefix Slots
+
+- ~man-page~ or ~info-manual~ can be used to specify the documentation for
+  the prefix and its suffixes.  The command ~transient-help~ uses the
+  method ~transient-show-help~ (which see) to lookup and use these
+  values.
+
+- ~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 abitrary non-suffix
+  command is invoked.  See [[*Transient State]].
+
+- ~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.
+
+- ~scope~ For some transients it might be necessary to have a sort of
+  secondary value, called a "scope".  See ~define-transient-command~.
+
+*** Internal Prefix Slots
+:PROPERTIES:
+:NONODE: t
+:END:
+
+These slots are mostly intended for internal use.  They should not be
+set in calls to ~define-transient-command~.
+
+- ~prototype~ When a transient prefix command is invoked, then a clone
+  of that object is stored in the global variable ~transient--prefix~
+  and the prototype is stored in the clone's ~prototype~ slot.
+
+- ~command~ The command, a symbol.  Each transient prefix command
+  consists of a command, which is stored in a symbol's function slot
+  and an object, which is stored in the ~transient--prefix~ property
+  of the same symbol.
+
+- ~level~ The level of the prefix commands.  The suffix commands whose
+  layer is equal or lower are displayed.  See [[*Enabling and Disabling
+  Suffixes]].
+
+- ~value~ The likely outdated value of the prefix.  Instead of accessing
+  this slot directly you should use the function ~transient-get-value~,
+  which is guaranteed to return the up-to-date value.
+
+- ~history~ and ~history-pos~ are used to keep track of historic values.
+  Unless you implement your own ~transient-infix-read~ method you should
+  not have to deal with these slots.
 
 ** Suffix Slots
 
diff --git a/docs/transient.texi b/docs/transient.texi
index 4090f0cf52..8ad98bd85d 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -31,7 +31,7 @@ General Public License for more details.
 @finalout
 @titlepage
 @title Transient User and Developer Manual
-@subtitle for version 0.1.0 (v0.1.0-103-g68f31ed+1)
+@subtitle for version 0.1.0 (v0.1.0-105-g0cad5eb+1)
 @author Jonas Bernoulli
 @page
 @vskip 0pt plus 1filll
@@ -65,7 +65,7 @@ Calling a suffix command usually causes the transient to be 
exited
 but suffix commands can also be configured to not exit the transient.
 
 @noindent
-This manual is for Transient version 0.1.0 (v0.1.0-103-g68f31ed+1).
+This manual is for Transient version 0.1.0 (v0.1.0-105-g0cad5eb+1).
 
 @quotation
 Copyright (C) 2018-2019 Jonas Bernoulli <jonas@@bernoul.li>
@@ -1794,7 +1794,75 @@ the command's doc string.
 @end defun
 
 @node Prefix Slots
-@section @strong{TODO} Prefix Slots
+@section Prefix Slots
+
+@itemize
+@item
+@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
+method @code{transient-show-help} (which see) to lookup and use these
+values.
+
+
+@item
+@code{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.
+
+
+@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 abitrary non-suffix
+command is invoked.  See @ref{Transient State}.
+
+
+@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.
+
+
+@item
+@code{scope} For some transients it might be necessary to have a sort of
+secondary value, called a "scope".  See @code{define-transient-command}.
+@end itemize
+
+@subsection Internal Prefix Slots
+
+These slots are mostly intended for internal use.  They should not be
+set in calls to @code{define-transient-command}.
+
+@itemize
+@item
+@code{prototype} When a transient prefix command is invoked, then a clone
+of that object is stored in the global variable @code{transient--prefix}
+and the prototype is stored in the clone's @code{prototype} slot.
+
+
+@item
+@code{command} The command, a symbol.  Each transient prefix command
+consists of a command, which is stored in a symbol's function slot
+and an object, which is stored in the @code{transient--prefix} property
+of the same symbol.
+
+
+@item
+@code{level} The level of the prefix commands.  The suffix commands whose
+layer is equal or lower are displayed.  See @ref{Enabling and Disabling 
Suffixes}.
+
+
+@item
+@code{value} The likely outdated value of the prefix.  Instead of accessing
+this slot directly you should use the function @code{transient-get-value},
+which is guaranteed to return the up-to-date value.
+
+
+@item
+@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.
+@end itemize
 
 @node Suffix Slots
 @section Suffix Slots