diff options
Diffstat (limited to 'docs/transient.org')
| -rw-r--r-- | docs/transient.org | 69 |
1 files changed, 47 insertions, 22 deletions
diff --git a/docs/transient.org b/docs/transient.org index 305684e..2211dd0 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.3.6 +#+SUBTITLE: for version 0.3.7 #+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.3.6. +This manual is for Transient version 0.3.7. #+BEGIN_QUOTE Copyright (C) 2018-2021 Jonas Bernoulli <jonas@bernoul.li> @@ -517,24 +517,39 @@ window, and the key bindings are the same as for ~scroll-up-command~ and buffer. The transient popup buffer is displayed in a window using ~(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 - should accept two arguments: a buffer to display and an alist of the - same form as ALIST. See [[info:elisp#Choosing Window]]. + The value of this option has the form ~(FUNCTION . ALIST)~, + where FUNCTION is a function or a list of functions. Each such + function should accept two arguments: a buffer to display and an + alist of the same form as ALIST. See [[info:elisp#Choosing Window]] + for details. + + The default is: + + (display-buffer-in-side-window + (side . bottom) + (inhibit-same-window . t) + (window-parameters (no-other-window . t))) - The default is ~(display-buffer-in-side-window (side . bottom))~. This displays the window at the bottom of the selected frame. - Another useful value is ~(display-buffer-below-selected)~. This is - what ~magit-popup~ used by default. For more alternatives see - [[info:elisp#Display Action Functions]]. + Another useful FUNCTION is ~display-buffer-below-selected~, which + is what ~magit-popup~ used by default. For more alternatives see + [[info:elisp#Display Action Functions]] and [[info:elisp#Buffer Display + Action Alists]]. + + Note that the buffer that was current before the transient buffer + is shown should remain the current buffer. Many suffix commands + act on the thing at point, if appropriate, and if the transient + buffer became the current buffer, then that would change what is + at point. To that effect ~inhibit-same-window~ ensures that the + selected window is not used to show the transient buffer. It may be possible to display the window in another frame, but whether that works in practice depends on the window-manager. If the window manager selects the new window (Emacs frame), - then it doesn't work. + then that unfortunately changes which buffer is current. - If you change the value of this option, then you might also want - to change the value of ~transient-mode-line-format~. + If you change the value of this option, then you might also + want to change the value of ~transient-mode-line-format~. - User Option: transient-mode-line-format @@ -755,7 +770,7 @@ that is used to invoke that transient. the branch whose variables are being configured. ** Binding Suffix and Infix Commands -*** _ :ignore: +*** _ The macro ~transient-define-prefix~ is used to define a transient. This defines the actual transient prefix command (see [[*Defining @@ -923,6 +938,18 @@ argument that is mandatory in all cases. be set in the suffix specification. Therefore if there is no object, then you have to make sure to specify the KEY and the DESCRIPTION. + As a special case, if you want to add a command that might be neither + defined nor autoloaded, you can use a workaround like: + + #+BEGIN_SRC emacs-lisp + (transient-insert-suffix 'some-prefix "k" + '("!" "Ceci n'est pas une commande" no-command + :if (lambda () (featurep 'no-library)))) + #+END_SRC + + Instead of ~featurep~ you could also use ~require~ with a non-nil value + for NOERROR. + - The mandatory argument can also be a command-line argument, a string. In that case an anonymous command is defined and bound. @@ -1077,7 +1104,7 @@ function, which for infix arguments serves about the same purpose as returned value is a symbol, the transient prefix command. ** Transient State -*** _ :ignore: +*** _ Invoking a transient prefix command "activates" the respective transient, i.e. it puts a transient keymap into effect, which binds @@ -1230,7 +1257,7 @@ slot. This is used when the user pressed ~C-z~. * Classes and Methods -** _ :ignore: +** _ Transient uses classes and generic functions to make it possible to define new types of suffix commands that are similar to existing @@ -1406,7 +1433,7 @@ classes will likely get generalized and added to Transient. For now they are very much subject to change and not documented. ** Suffix Methods -*** _ :ignore: +*** _ To get information about the methods implementing these generic functions use ~describe-function~. @@ -1537,7 +1564,8 @@ functions use ~describe-function~. - ~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. + causes the others to be disabled. An argument may appear in + multiple sub-lists. - ~scope~ For some transients it might be necessary to have a sort of secondary value, called a "scope". See ~transient-define-prefix~. @@ -2114,8 +2142,6 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. #+END_QUOTE -* _ :ignore: - # LocalWords: ARGLIST ARGS DOCSTRING ELEMENTs EVAL GROUPs Infixes # LocalWords: Infixes KEYWORDs LOC LocalWords MERCHANTABILITY Magit # LocalWords: Magit's Makefile OBJ OBJ's Pre arglist @@ -2127,9 +2153,8 @@ General Public License for more details. # IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile. # Local Variables: -# eval: (require 'ox-extra nil t) # eval: (require 'ox-texinfo+ nil t) -# eval: (and (featurep 'ox-extra) (ox-extras-activate '(ignore-headlines))) +# org-texinfo+-dissolve-noexport-headlines: t # indent-tabs-mode: nil # org-src-preserve-indentation: nil # End: |