[elpa] externals/transient a2dada29c8 034/366: manual: Add a FAQ

[Jonas Bernoulli]

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

    manual: Add a FAQ
---
 docs/transient.org  | 127 ++++++++++++++++++++++++++++++++++------------------
 docs/transient.texi | 115 ++++++++++++++++++++++++++++++-----------------
 2 files changed, 158 insertions(+), 84 deletions(-)

diff --git a/docs/transient.org b/docs/transient.org
index 1d468ca645..b92c7c88a0 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-31-gf0213e0+1)
+#+SUBTITLE: for version 0.1.0 (v0.1.0-32-g08b4778+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-31-gf0213e0+1).
+This manual is for Transient version 0.1.0 (v0.1.0-32-g08b4778+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2018-2019 Jonas Bernoulli <jonas@bernoul.li>
@@ -248,7 +248,6 @@ doc-string.
   if any.
 
 ** Common Suffix Commands
-*** _ :ignore:
 
 A few shared suffix commands are available in all transients.  These
 suffix commands are not shown in the popup buffer by default.
@@ -281,47 +280,8 @@ always be shown for all transients.
 The other common commands are describe in either the previous node or
 in one of the following nodes.
 
-*** Notes on Common Key Bindings
-:PROPERTIES:
-:NONODE: t
-:END:
-
-You may have noticed that the bindings for some of the common commands
-do *not* have the prefix ~C-x~ and that furthermore some of these commands
-are grayed out while others are not.  That unfortunately is a bit
-confusing if the section of common commands is not shown permanently,
-making the following explanation necessary.
-
-The purpose of usually hiding that section but showing it after the
-user pressed the respective prefix key is to conserve space and not
-overwhelm users with too much noise, while allowing the user to
-quickly list common bindings on demand.
-
-That however should not keep us from using the best possible key
-bindings.  The bindings that do use a prefix do so to avoid wasting
-too many non-prefix bindings, keeping them available for use in
-individual transients.  The bindings that do not use a prefix and that
-are *not* grayed out are very important bindings that are *always*
-available, even when invoking the "common command key prefix" or *any
-other* transient-specific prefix.  The non-prefix keys that *are* grayed
-out however, are not available when any incomplete prefix key sequence
-is active.  They do not use the "common command key prefix" because it
-is likely that users want to invoke them several times in a row and
-e.g. ~M-p M-p M-p~ is much more convenient than ~C-x M-p C-x M-p C-x M-p~.
-
-You may also have noticed that the "Set" command is bound to ~C-x s~,
-while Magit-Popup used to bind ~C-c C-c~ instead.  I have seen several
-users praise the latter binding (sic), so I did not change it
-willy-nilly.  The reason that I changed it is that using different
-prefix keys for different common commands, would have made the
-temporary display of the common commands even more confusing,
-i.e. after pressing ~C-c~ all the ~C-x ...~ bindings would be grayed out.
-
-Using a single prefix for common commands key means that all other
-potential prefix keys can be used for transient-specific commands
-*without* the section of common commands also popping up.  ~C-c~ in
-particular is a prefix that I want (and already do) use for Magit, and
-also using that for a common command would prevent me from doing so.
+Some of Transient's key bindings differ from the respective bindings
+of Magit-Popup; see [[*FAQ]] for more information.
 
 ** Saving Values
 
@@ -1876,6 +1836,85 @@ commands are outlined:
   implement that without modifying any existing code, but it does not
   currently exist.
 
+* FAQ
+:PROPERTIES:
+:APPENDIX:   t
+:END:
+
+** Can I control how the popup buffer is displayed?
+:PROPERTIES:
+:NONODE: t
+:END:
+
+Yes, see ~transient-display-buffer-action~ in [[*Other Options]].
+
+** Why did some of the key bindings change?
+:PROPERTIES:
+:NONODE: t
+:END:
+
+You may have noticed that the bindings for some of the common commands
+do *not* have the prefix ~C-x~ and that furthermore some of these commands
+are grayed out while others are not.  That unfortunately is a bit
+confusing if the section of common commands is not shown permanently,
+making the following explanation necessary.
+
+The purpose of usually hiding that section but showing it after the
+user pressed the respective prefix key is to conserve space and not
+overwhelm users with too much noise, while allowing the user to
+quickly list common bindings on demand.
+
+That however should not keep us from using the best possible key
+bindings.  The bindings that do use a prefix do so to avoid wasting
+too many non-prefix bindings, keeping them available for use in
+individual transients.  The bindings that do not use a prefix and that
+are *not* grayed out are very important bindings that are *always*
+available, even when invoking the "common command key prefix" or *any
+other* transient-specific prefix.  The non-prefix keys that *are* grayed
+out however, are not available when any incomplete prefix key sequence
+is active.  They do not use the "common command key prefix" because it
+is likely that users want to invoke them several times in a row and
+e.g. ~M-p M-p M-p~ is much more convenient than ~C-x M-p C-x M-p C-x M-p~.
+
+You may also have noticed that the "Set" command is bound to ~C-x s~,
+while Magit-Popup used to bind ~C-c C-c~ instead.  I have seen several
+users praise the latter binding (sic), so I did not change it
+willy-nilly.  The reason that I changed it is that using different
+prefix keys for different common commands, would have made the
+temporary display of the common commands even more confusing,
+i.e. after pressing ~C-c~ all the ~C-x ...~ bindings would be grayed out.
+
+Using a single prefix for common commands key means that all other
+potential prefix keys can be used for transient-specific commands
+*without* the section of common commands also popping up.  ~C-c~ in
+particular is a prefix that I want (and already do) use for Magit, and
+also using that for a common command would prevent me from doing so.
+
+(Also see the next question.)
+
+** Why does ~q~ not quit popups anymore?
+:PROPERTIES:
+:NONODE: t
+:END:
+
+I agree that ~q~ is a good binding for commands that quit something.
+This includes quitting whatever transient is currently active, but it
+also includes quitting whatever it is that some specific transient is
+controlling.  The transient ~magit-blame~ for example binds ~q~ to the
+command that turns ~magit-blame-mode~ off.
+
+So I had to decide if ~q~ should quit the active transient (like
+Magit-Popup used to) or whether ~C-g~ should do that instead, so that ~q~
+could be bound in individual transient to whatever commands make sense
+for them.  Because all other letters are already reserved for use by
+individual transients, I have decided to no longer make an exception
+for ~q~.
+
+If you want to get ~q~'s old binding back then you can do so.  Doing
+that is a bit more complicated than changing a single key binding, so
+I have implemented a function, ~transient-bind-q-to-quit~ that makes the
+necessary changes.  See its doc-string for more information.
+
 * Keystroke Index
 :PROPERTIES:
 :APPENDIX:   t
diff --git a/docs/transient.texi b/docs/transient.texi
index 7e68fcf043..35d93f0781 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-31-gf0213e0+1)
+@subtitle for version 0.1.0 (v0.1.0-32-g08b4778+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-31-gf0213e0+1).
+This manual is for Transient version 0.1.0 (v0.1.0-32-g08b4778+1).
 
 @quotation
 Copyright (C) 2018-2019 Jonas Bernoulli <jonas@@bernoul.li>
@@ -91,6 +91,7 @@ General Public License for more details.
 * Defining New Commands::
 * Classes and Methods::
 * Related Abstractions and Packages::
+* FAQ::
 * Keystroke Index::
 * Command Index::
 * Function Index::
@@ -415,44 +416,8 @@ Emacs session by typing @code{C-x t} while a transient is 
active.
 The other common commands are describe in either the previous node or
 in one of the following nodes.
 
-@subsection Notes on Common Key Bindings
-
-You may have noticed that the bindings for some of the common commands
-do @strong{not} have the prefix @code{C-x} and that furthermore some of these 
commands
-are grayed out while others are not.  That unfortunately is a bit
-confusing if the section of common commands is not shown permanently,
-making the following explanation necessary.
-
-The purpose of usually hiding that section but showing it after the
-user pressed the respective prefix key is to conserve space and not
-overwhelm users with too much noise, while allowing the user to
-quickly list common bindings on demand.
-
-That however should not keep us from using the best possible key
-bindings.  The bindings that do use a prefix do so to avoid wasting
-too many non-prefix bindings, keeping them available for use in
-individual transients.  The bindings that do not use a prefix and that
-are @strong{not} grayed out are very important bindings that are 
@strong{always}
-available, even when invoking the "common command key prefix" or @strong{any
-other} transient-specific prefix.  The non-prefix keys that @strong{are} grayed
-out however, are not available when any incomplete prefix key sequence
-is active.  They do not use the "common command key prefix" because it
-is likely that users want to invoke them several times in a row and
-e.g. @code{M-p M-p M-p} is much more convenient than @code{C-x M-p C-x M-p C-x 
M-p}.
-
-You may also have noticed that the "Set" command is bound to @code{C-x s},
-while Magit-Popup used to bind @code{C-c C-c} instead.  I have seen several
-users praise the latter binding (sic), so I did not change it
-willy-nilly.  The reason that I changed it is that using different
-prefix keys for different common commands, would have made the
-temporary display of the common commands even more confusing,
-i.e. after pressing @code{C-c} all the @code{C-x ...} bindings would be grayed 
out.
-
-Using a single prefix for common commands key means that all other
-potential prefix keys can be used for transient-specific commands
-@strong{without} the section of common commands also popping up.  @code{C-c} in
-particular is a prefix that I want (and already do) use for Magit, and
-also using that for a common command would prevent me from doing so.
+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
@@ -2260,6 +2225,76 @@ implement that without modifying any existing code, but 
it does not
 currently exist.
 @end itemize
 
+@node FAQ
+@appendix FAQ
+
+
+
+@appendixsec Can I control how the popup buffer is displayed?
+
+Yes, see @code{transient-display-buffer-action} in @ref{Other Options}.
+
+@appendixsec Why did some of the key bindings change?
+
+You may have noticed that the bindings for some of the common commands
+do @strong{not} have the prefix @code{C-x} and that furthermore some of these 
commands
+are grayed out while others are not.  That unfortunately is a bit
+confusing if the section of common commands is not shown permanently,
+making the following explanation necessary.
+
+The purpose of usually hiding that section but showing it after the
+user pressed the respective prefix key is to conserve space and not
+overwhelm users with too much noise, while allowing the user to
+quickly list common bindings on demand.
+
+That however should not keep us from using the best possible key
+bindings.  The bindings that do use a prefix do so to avoid wasting
+too many non-prefix bindings, keeping them available for use in
+individual transients.  The bindings that do not use a prefix and that
+are @strong{not} grayed out are very important bindings that are 
@strong{always}
+available, even when invoking the "common command key prefix" or @strong{any
+other} transient-specific prefix.  The non-prefix keys that @strong{are} grayed
+out however, are not available when any incomplete prefix key sequence
+is active.  They do not use the "common command key prefix" because it
+is likely that users want to invoke them several times in a row and
+e.g. @code{M-p M-p M-p} is much more convenient than @code{C-x M-p C-x M-p C-x 
M-p}.
+
+You may also have noticed that the "Set" command is bound to @code{C-x s},
+while Magit-Popup used to bind @code{C-c C-c} instead.  I have seen several
+users praise the latter binding (sic), so I did not change it
+willy-nilly.  The reason that I changed it is that using different
+prefix keys for different common commands, would have made the
+temporary display of the common commands even more confusing,
+i.e. after pressing @code{C-c} all the @code{C-x ...} bindings would be grayed 
out.
+
+Using a single prefix for common commands key means that all other
+potential prefix keys can be used for transient-specific commands
+@strong{without} the section of common commands also popping up.  @code{C-c} in
+particular is a prefix that I want (and already do) use for Magit, and
+also using that for a common command would prevent me from doing so.
+
+(Also see the next question.)
+
+@appendixsec Why does @code{q} not quit popups anymore?
+
+I agree that @code{q} is a good binding for commands that quit something.
+This includes quitting whatever transient is currently active, but it
+also includes quitting whatever it is that some specific transient is
+controlling.  The transient @code{magit-blame} for example binds @code{q} to 
the
+command that turns @code{magit-blame-mode} off.
+
+So I had to decide if @code{q} should quit the active transient (like
+Magit-Popup used to) or whether @code{C-g} should do that instead, so that 
@code{q}
+could be bound in individual transient to whatever commands make sense
+for them.  Because all other letters are already reserved for use by
+individual transients, I have decided to no longer make an exception
+for @code{q}.
+
+If you want to get @code{q}'s old binding back then you can do so.  Doing
+that is a bit more complicated than changing a single key binding, so
+I have implemented a function, @code{transient-bind-q-to-quit} that makes the
+necessary changes.  See its doc-string for more information.
+
 @node Keystroke Index
 @appendix Keystroke Index