diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CHANGELOG | 38 | ||||
| -rw-r--r-- | docs/Makefile | 4 | ||||
| -rw-r--r-- | docs/transient.org | 69 | ||||
| -rw-r--r-- | docs/transient.texi | 55 |
4 files changed, 128 insertions, 38 deletions
diff --git a/docs/CHANGELOG b/docs/CHANGELOG index f92a727..61e01b2 100644 --- a/docs/CHANGELOG +++ b/docs/CHANGELOG @@ -1,4 +1,42 @@ # -*- mode: org -*- +* v0.3.7 2021-10-25 + +- Added an additional safety hatch to prevent Emacs from entering an + inconsistent state when an unexpected error occurs. 99e48369 + +- Added support for implementing section movement commands in + third-party packages. This was requested by the maintainer of + Emacspeak. Because they would be of very limited use to sighted + users no such commands are added to Transient itself. 769219b5 + +- ~transient-read-number-{N0,N+,N}~ now support infix arguments that + have three different states: disabled, enabled without an empty + value, and enabled with a non-empty value. 626d105e + +- If a command is called as a suffix of itself, then the help command + shows the function definition instead of the man-page as it usually + does for prefixes. e17e2b2f + +- Give users more control over how the transient buffer is displayed. + Various aspects that were previously hardcoded can now be changed + using the ~transient-display-buffer-action~ option. 7c677737 + +- Added support for adding suffixes that might be neither defined nor + autoloaded when the prefix is invoked. This usually results in an + error and while it is now possible to override that using an extra + step, it is still discouraged. 6842305e + +Bug fixes: + +- 1e740608 transient-map: Bind C-u to universal-argument +- e9048100 Explicitly call transient--pre-command in button action +- be119ee4 Export variables for transient non-infix suffixes +- b526b9c7 transient-infix-set: Consider all incompatibility rules +- 7126d6aa Fix hydra-inspired colors +- 0c2255a2 transient-get-value: Add an emergency exit + +Also contains various documentation updates and code clean-ups. + * v0.3.6 2021-07-01 - Added new option ~transient-force-single-column~, which may be useful diff --git a/docs/Makefile b/docs/Makefile index 1a75646..37cd779 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,8 +7,8 @@ info: $(PKG).info dir html: $(PKG).html pdf: $(PKG).pdf -ORG_ARGS = --batch -Q $(ORG_LOAD_PATH) -l ox-extra -l ox-texinfo+.el -ORG_EVAL = --eval "(ox-extras-activate '(ignore-headlines))" +ORG_ARGS = --batch -Q $(ORG_LOAD_PATH) -l ox-texinfo+.el +ORG_EVAL = --eval "(setq org-texinfo+-dissolve-noexport-headlines t)" ORG_EVAL += --eval "(setq indent-tabs-mode nil)" ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)" ORG_EVAL += --funcall org-texinfo-export-to-texinfo 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: diff --git a/docs/transient.texi b/docs/transient.texi index 9134e20..232e762 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.3.6 +@subtitle for version 0.3.7 @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.3.6. +This manual is for Transient version 0.3.7. @quotation Copyright (C) 2018-2021 Jonas Bernoulli <jonas@@bernoul.li> @@ -708,24 +708,38 @@ 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 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 -should accept two arguments: a buffer to display and an alist of the -same form as ALIST@. See @ref{Choosing Window,,,elisp,}. +The value of this option has the form @code{(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 @ref{Choosing Window,,,elisp,} +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 @code{(display-buffer-in-side-window (side . bottom))}. This displays the window at the bottom of the selected frame. -Another useful value is @code{(display-buffer-below-selected)}. This is -what @code{magit-popup} used by default. For more alternatives see -@ref{Display Action Functions,,,elisp,}. +Another useful FUNCTION is @code{display-buffer-below-selected}, which +is what @code{magit-popup} used by default. For more alternatives see +@ref{Display Action Functions,,,elisp,} and @ref{Buffer Display Action Alists,,,elisp,}. + +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 @code{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 @code{transient-mode-line-format}. +If you change the value of this option, then you might also +want to change the value of @code{transient-mode-line-format}. @end defopt @defopt transient-mode-line-format @@ -1170,6 +1184,18 @@ be used to set the default for certain values that otherwise have to 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: + +@lisp +(transient-insert-suffix 'some-prefix "k" + '("!" "Ceci n'est pas une commande" no-command + :if (lambda () (featurep 'no-library)))) +@end lisp + +Instead of @code{featurep} you could also use @code{require} with a non-nil value +for NOERROR@. + @item The mandatory argument can also be a command-line argument, a @@ -1898,7 +1924,8 @@ 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. +causes the others to be disabled. An argument may appear in +multiple sub-lists. @item |