[elpa] externals/transient 7065e1ce86 229/366: manual: Various small improvements

[Jonas Bernoulli]

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

    manual: Various small improvements
---
 docs/transient.org  | 51 ++++++++++++++++++++++++--------------------------
 docs/transient.texi | 54 ++++++++++++++++++++++++++---------------------------
 2 files changed, 50 insertions(+), 55 deletions(-)

diff --git a/docs/transient.org b/docs/transient.org
index 5730bafb96..f75b4413d9 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.2.0 (v0.2.0-73-gf086cb62+1)
+#+SUBTITLE: for version 0.2.0 (v0.2.0-77-g94582a3f+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.2.0 (v0.2.0-73-gf086cb62+1).
+This manual is for Transient version 0.2.0 (v0.2.0-77-g94582a3f+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2018-2021 Jonas Bernoulli <jonas@bernoul.li>
@@ -96,12 +96,12 @@ actually called.  Suffix commands can also be configured to 
not exit
 the transient.
 
 A suffix command can, but does not have to, use the infix arguments in
-much the same way it can choose to use or ignore the prefix arguments.
-For a suffix command that was invoked from a transient the variable
-~transient-current-suffixes~ and the function ~transient-args~ serve about
-the same purpose as the variables ~prefix-arg~ and ~current-prefix-arg~ do
-for any command that was called after the prefix arguments have been
-set using a command such as ~universal-argument~.
+much the same way any command can choose to use or ignore the prefix
+arguments.  For a suffix command that was invoked from a transient the
+variable ~transient-current-suffixes~ and the function ~transient-args~
+serve about the same purpose as the variables ~prefix-arg~ and
+~current-prefix-arg~ do for any command that was called after the prefix
+arguments have been set using a command such as ~universal-argument~.
 
 The information shown in the popup buffer while a transient is active
 looks a bit like this:
@@ -130,8 +130,9 @@ 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.  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~ command is an example
-of using Transient to merely implement a command dispatcher.
+prefix key or command.  Magit's ~magit-dispatch~ (on ~C-x M-g~) command is
+an example of using Transient to merely implement a command
+dispatcher.
 
 In addition to that, Transient also allows users to interactively pass
 arguments to commands.  These arguments can be much more complex than
@@ -188,7 +189,8 @@ the transient and they may use the values set by the infix 
commands,
 i.e. the infix *arguments*.
 
 Instead of setting arguments to be used by a suffix command, infix
-commands may also set some value by side-effect.
+commands may also set some value by side-effect, e.g. by setting the
+value of some variable.
 
 ** Aborting and Resuming Transients
 
@@ -252,12 +254,13 @@ doc string.
 A few shared suffix commands are available in all transients.  These
 suffix commands are not shown in the popup buffer by default.
 
-Most of these commands are bound to ~C-x <key>~ and after pressing ~C-x~ a
-section featuring all common commands is temporarily shown in the popup
-buffer.  After invoking one of these commands, that section disappears
-again.  Note however that one of these commands is described as "Show
-common permanently"; invoke that if you want the common commands to
-always be shown for all transients.
+This includes the abording commands mentioned in the previous node as
+well as some other commands that are all bound to ~C-x <key>~.  After
+~C-x~ is pressed, a section featuring all these common commands is
+temporarily shown in the popup buffer.  After invoking one of them,
+the section disappears again.  Note however that one of these commands
+is described as "Show common permanently"; invoke that if you want the
+common commands to always be shown for all transients.
 
 - Key: C-x t, transient-toggle-common
 
@@ -316,8 +319,7 @@ but it is easily accessible (see [[*Using History]]).
 
 [fn:1] ~magit-diff~ and ~magit-log~ are two prominent examples, and their
 handling of buffer-local values is actually a bit more complicated
-than outlined above and even customizable.  This is something I am
-rethinking, but I don't want to rush any changes.)
+than outlined above and even customizable.
 
 ** Using History
 
@@ -413,11 +415,6 @@ expect that it won't be of use to most users, and they 
should place
 very important suffixes on a lower level, so that they remain
 available even if the user lowers the transient level.
 
-(Magit currently places nearly all suffixes on level 4 and lower
-levels are not used at all yet.  So for the time being you should not
-set a lower default level and using a higher level might not give you
-as many additional suffixes as you hoped.)
-
 - User Option: transient-default-level
 
   This option controls which suffix levels are made available by
@@ -475,7 +472,7 @@ window, and the key bindings are the same as for 
~scroll-up-command~ and
   lines.  If ARG is ~nil~, then it scrolls near full screen.  This
   is a wrapper around ~scroll-down-command~ (which see).
 
-* Other Options
+** Other Options
 
 - User Option: transient-show-popup
 
@@ -501,7 +498,7 @@ window, and the key bindings are the same as for 
~scroll-up-command~ and
 - User Option: transient-enable-popup-navigation
 
   This option controls whether navigation commands are enabled in the
-  transient popup.
+  transient popup buffer.
 
   While a transient is active the transient popup buffer is not the
   current buffer, making it necessary to use dedicated commands to act
@@ -518,7 +515,7 @@ window, and the key bindings are the same as for 
~scroll-up-command~ and
 
   This option specifies the action used to display the transient popup
   buffer.  The transient popup buffer is displayed in a window using
-  ~(display-buffer buf transient-display-buffer-action)~.
+  ~(display-buffer BUFFER transient-display-buffer-action)~.
 
   The value of this option has the form ~(FUNCTION . ALIST)~, where
   FUNCTION is a function or a list of functions.  Each such function
diff --git a/docs/transient.texi b/docs/transient.texi
index 5ce629deb0..ced63d050b 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.2.0 (v0.2.0-73-gf086cb62+1)
+@subtitle for version 0.2.0 (v0.2.0-77-g94582a3f+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.2.0 (v0.2.0-73-gf086cb62+1).
+This manual is for Transient version 0.2.0 (v0.2.0-77-g94582a3f+1).
 
 @quotation
 Copyright (C) 2018-2021 Jonas Bernoulli <jonas@@bernoul.li>
@@ -86,7 +86,6 @@ General Public License for more details.
 @menu
 * Introduction::
 * Usage::
-* Other Options::
 * Modifying Existing Transients::
 * Defining New Commands::
 * Classes and Methods::
@@ -110,6 +109,7 @@ Usage
 * Getting Help for Suffix Commands::
 * Enabling and Disabling Suffixes::
 * Other Commands::
+* Other Options::
 
 Defining New Commands
 
@@ -195,12 +195,12 @@ actually called.  Suffix commands can also be configured 
to not exit
 the transient.
 
 A suffix command can, but does not have to, use the infix arguments in
-much the same way it can choose to use or ignore the prefix arguments.
-For a suffix command that was invoked from a transient the variable
-@code{transient-current-suffixes} and the function @code{transient-args} serve 
about
-the same purpose as the variables @code{prefix-arg} and 
@code{current-prefix-arg} do
-for any command that was called after the prefix arguments have been
-set using a command such as @code{universal-argument}.
+much the same way any command can choose to use or ignore the prefix
+arguments.  For a suffix command that was invoked from a transient the
+variable @code{transient-current-suffixes} and the function 
@code{transient-args}
+serve about the same purpose as the variables @code{prefix-arg} and
+@code{current-prefix-arg} do for any command that was called after the prefix
+arguments have been set using a command such as @code{universal-argument}.
 
 The information shown in the popup buffer while a transient is active
 looks a bit like this:
@@ -230,8 +230,9 @@ 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.  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} command is an example
-of using Transient to merely implement a command dispatcher.
+prefix key or command.  Magit's @code{magit-dispatch} (on @code{C-x M-g}) 
command is
+an example of using Transient to merely implement a command
+dispatcher.
 
 In addition to that, Transient also allows users to interactively pass
 arguments to commands.  These arguments can be much more complex than
@@ -282,6 +283,7 @@ to implementing yet).
 * Getting Help for Suffix Commands::
 * Enabling and Disabling Suffixes::
 * Other Commands::
+* Other Options::
 @end menu
 
 @node Invoking Transients
@@ -302,7 +304,8 @@ the transient and they may use the values set by the infix 
commands,
 i.e. the infix @strong{arguments}.
 
 Instead of setting arguments to be used by a suffix command, infix
-commands may also set some value by side-effect.
+commands may also set some value by side-effect, e.g. by setting the
+value of some variable.
 
 @node Aborting and Resuming Transients
 @section Aborting and Resuming Transients
@@ -382,12 +385,13 @@ if any.
 A few shared suffix commands are available in all transients.  These
 suffix commands are not shown in the popup buffer by default.
 
-Most of these commands are bound to @code{C-x <key>} and after pressing 
@code{C-x} a
-section featuring all common commands is temporarily shown in the popup
-buffer.  After invoking one of these commands, that section disappears
-again.  Note however that one of these commands is described as "Show
-common permanently"; invoke that if you want the common commands to
-always be shown for all transients.
+This includes the abording commands mentioned in the previous node as
+well as some other commands that are all bound to @code{C-x <key>}.  After
+@code{C-x} is pressed, a section featuring all these common commands is
+temporarily shown in the popup buffer.  After invoking one of them,
+the section disappears again.  Note however that one of these commands
+is described as "Show common permanently"; invoke that if you want the
+common commands to always be shown for all transients.
 
 @table @asis
 @kindex C-x t
@@ -431,8 +435,7 @@ designed so that the value that they use is stored 
externally as the
 buffer-local value of some variable.  Invoking such a transient again
 uses the buffer-local value. @footnote{@code{magit-diff} and @code{magit-log} 
are two prominent examples, and their
 handling of buffer-local values is actually a bit more complicated
-than outlined above and even customizable.  This is something I am
-rethinking, but I don't want to rush any changes.)}
+than outlined above and even customizable.}
 
 If the user does not save the value and just exits using a regular
 suffix command, then the value is merely saved to the transient's
@@ -575,11 +578,6 @@ expect that it won't be of use to most users, and they 
should place
 very important suffixes on a lower level, so that they remain
 available even if the user lowers the transient level.
 
-(Magit currently places nearly all suffixes on level 4 and lower
-levels are not used at all yet.  So for the time being you should not
-set a lower default level and using a higher level might not give you
-as many additional suffixes as you hoped.)
-
 @defopt transient-default-level
 
 This option controls which suffix levels are made available by
@@ -649,7 +647,7 @@ is a wrapper around @code{scroll-down-command} (which see).
 @end deffn
 
 @node Other Options
-@chapter Other Options
+@section Other Options
 
 @defopt transient-show-popup
 
@@ -683,7 +681,7 @@ then the popup is shown after that many seconds of 
inactivity
 @defopt transient-enable-popup-navigation
 
 This option controls whether navigation commands are enabled in the
-transient popup.
+transient popup buffer.
 
 While a transient is active the transient popup buffer is not the
 current buffer, making it necessary to use dedicated commands to act
@@ -708,7 +706,7 @@ is non-nil, then the following features are available:
 
 This option specifies the action used to display the transient popup
 buffer.  The transient popup buffer is displayed in a window using
-@code{(display-buffer buf transient-display-buffer-action)}.
+@code{(display-buffer BUFFER transient-display-buffer-action)}.
 
 The value of this option has the form @code{(FUNCTION . ALIST)}, where
 FUNCTION is a function or a list of functions.  Each such function