branch: externals/transient
commit a2dada29c8dfce46e518c972b658a6a91f4659a6
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@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 <jo...@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
