Skip to content

Commit

Permalink
The version in Emacs' "master" branches
Browse files Browse the repository at this point in the history 
To update:

1. Backport from Emacs' "emacs-30" to Transient.

   Make sure to look at history of not only "lisp/transient.el",
   but also "doc/misc/transient.texi".

2. Backport from Emacs' "master" to Transient, while making them
   backward compatible with Emacs 30.

3. In Transient, rebase "builtin" onto "main".

   Now we have to DISCARD the changes that revert modifications
   that have happened in Transient since the last round.  Only
   the following differences should remain:

   Differences in "transient.texi":

   - Additional whitespace in @direntry at the top.
   - Replace @ref{}.
     Ox-Texinfo uses @ref, but other link types are preferred in Emacs.
   - Use @dots{}.
     Ox-Texinfo cannot put @dots{} inside the term part of a
     description list (see example below).  It also cannot do it
     inside code blocks.

   Differences in "transient.el":

   - Use my main email address.
   - Use "URL" instead of "Homepage".
     I consistently use "Homepage" for all my packages and they
     consistently use "URL".
   - Use "Version" instead of "Package-Version" because that's
     all finder understands.
   - Drop "Package-Requires".
   - Drop require for `compat'.
   - Drop `seq' kludge.
   - Drop `pp-default-function' declaration.
   - Drop backward compatibility `transient--wrap-command'.

4. In Transient, sign and update date ("c N") and run
   "git describe" to get DESC.

5. Copy from Transient's "builtin" to Emacs' "emacs-30".

   cp ~/.config/emacs/lib/transient/lisp/transient.el \
      ~/src/emacs/emacs/emacs-30/lisp/
   cp ~/.config/emacs/lib/transient/docs/transient.texi \
      ~/src/emacs/emacs/emacs-30/doc/misc/

6. In Emacs, stage and commit using "Update to Transient DESC" as
   message.

7. Possibly repeat (5) and (6) for Emacs' "master" branch.
   If nothing changed on "master" compared to "emacs-30", then this
   shouldn't be necessary, and we can just wait for someone else to
   merge "emacs-30" into "master".  But if (2) brought in some
   additional changes, then we probably have to do this.

------

- Function: foo arg@@texinfo:@dots{}@@ rest ::

  This works @@texinfo:@dots{}@@.

- Function: bar arg{{{dots()}}} rest ::

  This works {{{dots()}}}.

- This works {{{dots()}}} also.
  • Loading branch information
@tarsius
tarsius committed Aug 5, 2024
1 parent b2cb4e5 commit 3d9e935
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 134 deletions.
63 changes: 36 additions & 27 deletions docs/transient.texi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ General Public License for more details.

@dircategory Emacs misc features
@direntry
* Transient: (transient). Transient Commands.
* Transient: (transient). Transient Commands.
@end direntry

@finalout
Expand Down Expand Up @@ -371,7 +371,7 @@ 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
history. That value won't be used when the transient is next invoked,
but it is easily accessible (see @ref{Using History}).
but it is easily accessible (@pxref{Using History}).

@table @asis
@item @kbd{C-x s} (@code{transient-set})
Expand Down Expand Up @@ -432,8 +432,8 @@ to cycle through previously used values. Usually the same keys as
those mentioned above are bound to those commands.

Authors of transients should arrange for different infix commands that
read the same kind of value to also use the same history key (see
@ref{Suffix Slots}).
read the same kind of value to also use the same history key
(@pxref{Suffix Slots}).

Both kinds of history are saved to a file when Emacs is exited.

Expand Down Expand Up @@ -647,7 +647,7 @@ buffer. The transient popup buffer is displayed in a window using
The value of this option has the form @code{(@var{FUNCTION} . @var{ALIST})},
where @var{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 @var{ALIST}. See @ref{Choosing Window,,,elisp,},
alist of the same form as @var{ALIST}. @xref{Choosing Window,,,elisp,},
for details.

The default is:
Expand All @@ -662,7 +662,8 @@ The default is:
This displays the window at the bottom of the selected frame.
Another useful @var{FUNCTION} is @code{display-buffer-below-selected}, which
is what @code{magit-popup} used by default. For more alternatives see
@ref{Buffer Display Action Functions,,,elisp,}, and @ref{Buffer Display Action Alists,,,elisp,}.
@ref{Buffer Display Action Functions,,,elisp,}, and see @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
Expand Down Expand Up @@ -714,7 +715,8 @@ color of @code{transient-key-noop} (if non-suffix are disallowed),
@code{transient-key-exit} (if allowed and they exit the transient) is
used to draw the line.

Otherwise this can be any mode-line format. See @ref{Mode Line Format,,,elisp,}, for details.
Otherwise this can be any mode-line format. @xref{Mode Line
Format,,,elisp,}, for details.
@end defopt

@defopt transient-semantic-coloring
Expand Down Expand Up @@ -863,10 +865,10 @@ The following functions share a few arguments:
as expected by @code{transient-define-prefix}. Note that an infix is a
special kind of suffix. Depending on context ``suffixes'' means
``suffixes (including infixes)'' or ``non-infix suffixes''. Here it
means the former. See @ref{Suffix Specifications}.
means the former. @xref{Suffix Specifications}.

@var{SUFFIX} may also be a group in the same form as expected by
@code{transient-define-prefix}. See @ref{Group Specifications}.
@code{transient-define-prefix}. @xref{Group Specifications}.

@item
@var{LOC} is a command, a key vector, a key description (a string as
Expand Down Expand Up @@ -1055,7 +1057,7 @@ binds the transient's infix and suffix commands. In other words, it
defines the complete transient, not just the transient prefix command
that is used to invoke that transient.

@defmac transient-define-prefix name arglist [docstring] [keyword value]... group... [body...]
@defmac transient-define-prefix name arglist [docstring] [keyword value]@dots{} group@dots{} [body@dots{}]
This macro defines @var{NAME} as a transient prefix command and binds the
transient's infix and suffix commands.

Expand All @@ -1070,7 +1072,7 @@ explicitly.

@var{GROUP}s add key bindings for infix and suffix commands and specify
how these bindings are presented in the popup buffer. At least one
@var{GROUP} has to be specified. See @ref{Binding Suffix and Infix Commands}.
@var{GROUP} has to be specified. @xref{Binding Suffix and Infix Commands}.

The @var{BODY} is optional. If it is omitted, then @var{ARGLIST} is ignored and
the function definition becomes:
Expand Down Expand Up @@ -1105,11 +1107,13 @@ the branch whose variables are being configured.
@section Binding Suffix and Infix Commands

The macro @code{transient-define-prefix} is used to define a transient.
This defines the actual transient prefix command (see @ref{Defining Transients}) and adds the transient's infix and suffix bindings, as
This defines the actual transient prefix command (@pxref{Defining
Transients}) and adds the transient's infix and suffix bindings, as
described below.

Users and third-party packages can add additional bindings using
functions such as @code{transient-insert-suffix} (see @ref{Modifying Existing Transients}). These functions take a ``suffix specification'' as one of
functions such as @code{transient-insert-suffix} (@pxref{Modifying Existing Transients}).
These functions take a ``suffix specification'' as one of
their arguments, which has the same form as the specifications used in
@code{transient-define-prefix}.

Expand Down Expand Up @@ -1140,10 +1144,13 @@ brackets to do the latter.
Group specifications then have this form:

@lisp
[@{LEVEL@} @{DESCRIPTION@} @{KEYWORD VALUE@}... ELEMENT...]
[@{@var{LEVEL}@} @{@var{DESCRIPTION}@}
@{@var{KEYWORD} @var{VALUE}@}...
@var{ELEMENT}...]
@end lisp

The @var{LEVEL} is optional and defaults to 4. See @ref{Enabling and Disabling Suffixes}.
The @var{LEVEL} is optional and defaults to 4. @xref{Enabling and
Disabling Suffixes}.

The @var{DESCRIPTION} is optional. If present, it is used as the heading of
the group.
Expand Down Expand Up @@ -1287,7 +1294,9 @@ suffixes''. Here it means the former.
Suffix specifications have this form:

@lisp
([LEVEL] [KEY [DESCRIPTION]] COMMAND|ARGUMENT [KEYWORD VALUE]...)
([@var{LEVEL}]
[@var{KEY} [@var{DESCRIPTION}]]
@var{COMMAND}|@var{ARGUMENT} [@var{KEYWORD} @var{VALUE}]...)
@end lisp

@var{LEVEL}, @var{KEY} and @var{DESCRIPTION} can also be specified using the @var{KEYWORD}s
Expand All @@ -1298,8 +1307,8 @@ the object's values just for the binding inside this transient.

@itemize
@item
@var{LEVEL} is the suffix level, an integer between 1 and 7. See
@ref{Enabling and Disabling Suffixes}.
@var{LEVEL} is the suffix level, an integer between 1 and 7.
@xref{Enabling and Disabling Suffixes}.

@item
@var{KEY} is the key binding, either a vector or key description string.
Expand Down Expand Up @@ -1377,7 +1386,7 @@ Note that an infix is a special kind of suffix. Depending on context
``suffixes'' means ``suffixes (including infixes)'' or ``non-infix
suffixes''.

@defmac transient-define-suffix name arglist [docstring] [keyword value]... body...
@defmac transient-define-suffix name arglist [docstring] [keyword value]@dots{} body@dots{}
This macro defines @var{NAME} as a transient suffix command.

@var{ARGLIST} are the arguments that the command takes.
Expand All @@ -1394,7 +1403,7 @@ The infix arguments are usually accessed by using @code{transient-args}
inside @code{interactive}.
@end defmac

@defmac transient-define-infix name arglist [docstring] [keyword value]...
@defmac transient-define-infix name arglist [docstring] [keyword value]@dots{}
This macro defines @var{NAME} as a transient infix command.

@var{ARGLIST} is always ignored (but mandatory never-the-less) and
Expand Down Expand Up @@ -1427,7 +1436,7 @@ define your own infix command class. In that case you have to use
value of the @code{:transient} keyword.
@end defmac

@defmac transient-define-argument name arglist [docstring] [keyword value]...
@defmac transient-define-argument name arglist [docstring] [keyword value]@dots{}
This macro defines @var{NAME} as a transient infix command.

This is an alias for @code{transient-define-infix}. Only use this alias
Expand Down Expand Up @@ -1920,7 +1929,7 @@ object should not affect later invocations.
@item
All suffix and infix classes derive from @code{transient-suffix}, which in
turn derives from @code{transient-child}, from which @code{transient-group} also
derives (see @ref{Group Classes}).
derives (@pxref{Group Classes}).

@item
All infix classes derive from the abstract @code{transient-infix} class,
Expand All @@ -1934,7 +1943,7 @@ that does not do so. If you do that then you get to implement many
methods.

Also, infixes and non-infix suffixes are usually defined using
different macros (see @ref{Defining Suffix and Infix Commands}).
different macros (@pxref{Defining Suffix and Infix Commands}).

@item
Classes used for infix commands that represent arguments should
Expand Down Expand Up @@ -2127,7 +2136,7 @@ probably don't want that.
@code{transient-suffix} and @code{transient-non-suffix} play a part when
determining whether the currently active transient prefix command
remains active/transient when a suffix or arbitrary non-suffix
command is invoked. See @ref{Transient State}.
command is invoked. @xref{Transient State}.

@item
@code{refresh-suffixes} Normally suffix objects and keymaps are only setup
Expand Down Expand Up @@ -2173,7 +2182,7 @@ of the same symbol.

@item
@code{level} The level of the prefix commands. The suffix commands whose
layer is equal or lower are displayed. See @ref{Enabling and Disabling Suffixes}.
layer is equal or lower are displayed. @pxref{Enabling and Disabling Suffixes}.

@item
@code{value} The likely outdated value of the prefix. Instead of accessing
Expand Down Expand Up @@ -2206,7 +2215,7 @@ Also see @ref{Suffix Classes}.
@code{command} The command, a symbol.

@item
@code{transient} Whether to stay transient. See @ref{Transient State}.
@code{transient} Whether to stay transient. @xref{Transient State}.

@item
@code{format} The format used to display the suffix in the popup buffer.
Expand Down Expand Up @@ -2381,7 +2390,7 @@ the slots documented above, it is a predicate, but it is used for a
different purpose. The value has to be an integer between 1
and 7. @code{level} controls whether a suffix or a group should be
available depending on user preference.
See @ref{Enabling and Disabling Suffixes}.
@xref{Enabling and Disabling Suffixes}.

@node FAQ
@appendix FAQ
Expand Down
139 changes: 32 additions & 107 deletions lisp/transient.el
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,10 @@

;; Copyright (C) 2018-2024 Free Software Foundation, Inc.

;; Author: Jonas Bernoulli <emacs.transient@jonas.bernoulli.dev>
;; Homepage: https://github.com/magit/transient
;; Author: Jonas Bernoulli <jonas@bernoul.li>
;; URL: https://github.com/magit/transient
;; Keywords: extensions

;; Package-Version: 0.7.4
;; Package-Requires: ((emacs "26.1") (compat "30.0.0.0") (seq "2.24"))
;; Version: 0.7.4

;; SPDX-License-Identifier: GPL-3.0-or-later

Expand Down Expand Up @@ -35,45 +33,10 @@
;;; Code:

(require 'cl-lib)
(require 'compat)
(require 'eieio)
(require 'edmacro)
(require 'format-spec)

(eval-and-compile
(when (and (featurep 'seq)
(not (fboundp 'seq-keep)))
(unload-feature 'seq 'force)))
(require 'seq)
(unless (fboundp 'seq-keep)
(display-warning 'transient (substitute-command-keys "\
Transient requires `seq' >= 2.24,
but due to bad defaults, Emacs's package manager, refuses to
upgrade this and other built-in packages to higher releases
from GNU Elpa, when a package specifies that this is needed.
To fix this, you have to add this to your init file:
(setq package-install-upgrade-built-in t)
Then evaluate that expression by placing the cursor after it
and typing \\[eval-last-sexp].
Once you have done that, you have to explicitly upgrade `seq':
\\[package-upgrade] seq \\`RET'
Then you also must make sure the updated version is loaded,
by evaluating this form:
(progn (unload-feature 'seq t) (require 'seq))
Until you do this, you will get random errors about `seq-keep'
being undefined while using Transient.
If you don't use the `package' package manager but still get
this warning, then your chosen package manager likely has a
similar defect.") :emergency))

(eval-when-compile (require 'subr-x))

Expand All @@ -83,7 +46,6 @@ similar defect.") :emergency))
(declare-function Man-getpage-in-background "man" (topic))

(defvar Man-notify-method)
(defvar pp-default-function) ; since Emacs 29.1

(defmacro transient--with-emergency-exit (id &rest body)
(declare (indent defun))
Expand Down Expand Up @@ -2460,72 +2422,35 @@ value. Otherwise return CHILDREN as is."
(remove-hook 'minibuffer-exit-hook ,exit)))
,@body)))

(static-if (>= emacs-major-version 30) ;transient--wrap-command
(defun transient--wrap-command ()
(cl-assert
(>= emacs-major-version 30) nil
"Emacs was downgraded, making it necessary to recompile Transient")
(letrec
((prefix transient--prefix)
(suffix this-command)
(advice
(lambda (fn &rest args)
(interactive
(lambda (spec)
(let ((abort t))
(unwind-protect
(prog1 (let ((debugger #'transient--exit-and-debug))
(advice-eval-interactive-spec spec))
(setq abort nil))
(when abort
(when-let ((unwind (oref prefix unwind-suffix)))
(transient--debug 'unwind-interactive)
(funcall unwind suffix))
(advice-remove suffix advice)
(oset prefix unwind-suffix nil))))))
(unwind-protect
(let ((debugger #'transient--exit-and-debug))
(apply fn args))
(when-let ((unwind (oref prefix unwind-suffix)))
(transient--debug 'unwind-command)
(funcall unwind suffix))
(advice-remove suffix advice)
(oset prefix unwind-suffix nil)))))
(when (symbolp this-command)
(advice-add suffix :around advice '((depth . -99))))))

(defun transient--wrap-command ()
(let* ((prefix transient--prefix)
(suffix this-command)
(advice nil)
(advice-interactive
(lambda (spec)
(let ((abort t))
(unwind-protect
(prog1 (let ((debugger #'transient--exit-and-debug))
(advice-eval-interactive-spec spec))
(setq abort nil))
(when abort
(when-let ((unwind (oref prefix unwind-suffix)))
(transient--debug 'unwind-interactive)
(funcall unwind suffix))
(advice-remove suffix advice)
(oset prefix unwind-suffix nil))))))
(advice-body
(lambda (fn &rest args)
(unwind-protect
(let ((debugger #'transient--exit-and-debug))
(apply fn args))
(when-let ((unwind (oref prefix unwind-suffix)))
(transient--debug 'unwind-command)
(funcall unwind suffix))
(advice-remove suffix advice)
(oset prefix unwind-suffix nil)))))
(setq advice `(lambda (fn &rest args)
(interactive ,advice-interactive)
(apply ',advice-body fn args)))
(when (symbolp this-command)
(advice-add suffix :around advice '((depth . -99)))))))
(defun transient--wrap-command ()
(letrec
((prefix transient--prefix)
(suffix this-command)
(advice
(lambda (fn &rest args)
(interactive
(lambda (spec)
(let ((abort t))
(unwind-protect
(prog1 (let ((debugger #'transient--exit-and-debug))
(advice-eval-interactive-spec spec))
(setq abort nil))
(when abort
(when-let ((unwind (oref prefix unwind-suffix)))
(transient--debug 'unwind-interactive)
(funcall unwind suffix))
(advice-remove suffix advice)
(oset prefix unwind-suffix nil))))))
(unwind-protect
(let ((debugger #'transient--exit-and-debug))
(apply fn args))
(when-let ((unwind (oref prefix unwind-suffix)))
(transient--debug 'unwind-command)
(funcall unwind suffix))
(advice-remove suffix advice)
(oset prefix unwind-suffix nil)))))
(when (symbolp this-command)
(advice-add suffix :around advice '((depth . -99))))))

(defun transient--premature-post-command ()
(and (equal (this-command-keys-vector) [])
Expand Down

0 comments on commit 3d9e935

Please sign in to comment.