Skip to content

Commit

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

0. At times backport from Emacs' "emacs-NN" to Transient.

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

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

2. 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.
   - Use @var{} in two code snippets.

   Differences in "transient.el":

   - Use `if-let*'/`when-let*' when it would be correct to use
     `if-let'/`when-let'.  This pisses me off and it's done in
     a separate commit.

   - 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".

   - Set the value of `transient-version' to "VERSION-builtin".

   - Drop require for `compat'.
   - Drop `seq' kludge.
   - Drop `eieio--unbound' alias.
   - Drop `pp-default-function' declaration.
   - Drop `cl-type' backport.
   - Drop backward compatibility `transient--wrap-command'.

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

4. Copy from Transient's "builtin" to Emacs' "master".

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

5. Set the value of `transient-version' to "DESC-builtin".

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

------

- 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 Jan 3, 2025
1 parent 989102c commit f0478b2
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 140 deletions.
49 changes: 28 additions & 21 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 @@ -360,7 +360,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 @@ -421,8 +421,8 @@ 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 @@ -718,7 +718,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 @@ -732,7 +732,7 @@ The default is:

This displays the window at the bottom of the selected frame.
For alternatives see @ref{Buffer Display Action Functions,,,elisp,},
and @ref{Buffer Display Action Alists,,,elisp,}.
and @xref{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 @@ -938,10 +938,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 @@ -1147,7 +1147,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 @@ -1182,11 +1182,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 All @@ -1212,10 +1214,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 @@ -1359,7 +1364,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 @@ -1370,8 +1377,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 @@ -2067,7 +2074,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 @@ -2081,7 +2088,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 @@ -2498,7 +2505,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 @@ -2547,7 +2554,7 @@ and the @code{level} slot (see @ref{Enabling and Disabling Suffixes}) are define
@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 @@ -2760,7 +2767,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
151 changes: 32 additions & 119 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-2025 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.8.3
;; Package-Requires: ((emacs "26.1") (compat "30.0.0.0") (seq "2.24"))
;; Version: 0.8.3

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

Expand All @@ -34,73 +32,24 @@

;;; Code:

(defconst transient-version "0.8.3")
(defconst transient-version "0.8.3-builtin")

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

(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))

(eval-and-compile
(unless (boundp 'eieio--unbound) ; New name since Emacs 28.1.
(defvaralias 'eieio--unbound 'eieio-unbound nil)))

(declare-function info "info" (&optional file-or-node buffer))
(declare-function Man-find-section "man" (section))
(declare-function Man-next-section "man" (n))
(declare-function Man-getpage-in-background "man" (topic))

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

(eval-and-compile
(when (< emacs-major-version 28)
(pcase-defmacro cl-type (type)
"Pcase pattern that matches objects of TYPE.
TYPE is a type descriptor as accepted by `cl-typep', which see."
(static-if (< emacs-major-version 30)
`(pred (pcase--flip cl-typep ',type))
`(pred (cl-typep _ ',type))))))

(make-obsolete-variable 'transient-hide-during-minibuffer-read
"use `transient-show-during-minibuffer-read' instead."
Expand Down Expand Up @@ -2604,70 +2553,34 @@ value. Otherwise return CHILDREN as is.")
,@body)))

(defun transient--wrap-command ()
(static-if (>= emacs-major-version 30)
(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))))
(cl-assert
(>= emacs-major-version 30) nil
"Emacs was downgraded, making it necessary to recompile Transient"))
;; (< emacs-major-version 30)
(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)))))))
(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 f0478b2

Please sign in to comment.