[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-29 bcd02cf5127: ; Improve documentation of :predicate in globalize
From: |
Eli Zaretskii |
Subject: |
emacs-29 bcd02cf5127: ; Improve documentation of :predicate in globalized minor modes |
Date: |
Thu, 23 Mar 2023 05:30:45 -0400 (EDT) |
branch: emacs-29
commit bcd02cf5127ecfe6d6ce4ac316f881246c49db4f
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>
; Improve documentation of :predicate in globalized minor modes
* doc/lispref/modes.texi (Defining Minor Modes):
* lisp/emacs-lisp/easy-mmode.el (define-globalized-minor-mode):
Improve documentation of the :predicate keyword in defining
globalized minor modes.
---
doc/lispref/modes.texi | 36 ++++++++++++++++++++++--------------
lisp/emacs-lisp/easy-mmode.el | 26 +++++++++++++++++---------
2 files changed, 39 insertions(+), 23 deletions(-)
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index fff1ea65b07..d011962ade7 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1775,6 +1775,8 @@ it's used to say which major modes this minor mode is
useful in.
Any other keyword arguments are passed directly to the
@code{defcustom} generated for the variable @var{mode}.
+@xref{Variable Definitions}, for the description of those keywords and
+their values.
The command named @var{mode} first performs the standard actions such as
setting the variable named @var{mode} and then executes the @var{body}
@@ -1860,9 +1862,10 @@ by visiting files, and buffers that use a major mode
other than
Fundamental mode; but it does not detect the creation of a new buffer
in Fundamental mode.
-This defines the customization option @var{global-mode}
(@pxref{Customization}),
-which can be toggled in the Customize interface to turn the minor mode on
-and off. As with @code{define-minor-mode}, you should ensure that the
+This macro defines the customization option @var{global-mode}
+(@pxref{Customization}), which can be toggled via the Customize
+interface to turn the minor mode on and off. As with
+@code{define-minor-mode}, you should ensure that the
@code{define-globalized-minor-mode} form is evaluated each time Emacs
starts, for example by providing a @code{:require} keyword.
@@ -1875,24 +1878,27 @@ Use @code{:variable @var{variable}} if that's not the
case--some minor
modes use a different variable to store this state information.
Generally speaking, when you define a globalized minor mode, you should
-also define a non-globalized version, so that people can use (or
-disable) it in individual buffers. This also allows them to disable a
+also define a non-globalized version, so that people could use it (or
+disable it) in individual buffers. This also allows them to disable a
globally enabled minor mode in a specific major mode, by using that
mode's hook.
-If given a @code{:predicate} keyword, a user option called the same as
-the global mode variable, but with @code{-modes} instead of
-@code{-mode} at the end will be created. The variable is used as a
-predicate that specifies which major modes the minor mode should be
-activated in. Valid values include @code{t} (use in all major modes,
-@code{nil} (use in no major modes), or a list of mode names (or
-@code{(not mode-name ...)}) elements (as well as @code{t} and
-@code{nil}).
+If the macro is given a @code{:predicate} keyword, it will create a
+user option called the same as the global mode variable, but with
+@code{-modes} instead of @code{-mode} at the end, i.e.@:
+@code{@var{global-mode}s}. This variable will be used in a predicate
+function that determines whether the minor mode should be activated in
+a particular major mode. Valid values of @code{:predicate} include
+@code{t} (use in all major modes), @code{nil} (don't use in any major
+modes), or a list of mode names, optionally preceded with @code{not}
+(as in @w{@code{(not @var{mode-name} @dots{})}}). These elements can
+be mixed, as shown in the following examples.
@example
(c-mode (not mail-mode message-mode) text-mode)
@end example
+@noindent
This means ``use in modes derived from @code{c-mode}, and not in
modes derived from @code{message-mode} or @code{mail-mode}, but do use
in modes derived from @code{text-mode}, and otherwise no other
@@ -1902,13 +1908,15 @@ modes''.
((not c-mode) t)
@end example
-This means ``don't use modes derived from @code{c-mode}, but use
+@noindent
+This means ``don't use in modes derived from @code{c-mode}, but do use
everywhere else''.
@example
(text-mode)
@end example
+@noindent
This means ``use in modes derived from @code{text-mode}, but nowhere
else''. (There's an implicit @code{nil} element at the end.)
@end defmac
diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index e84207da2df..0f6711209a5 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -449,15 +449,23 @@ No problems result if this variable is not bound.
TURN-ON is a function that will be called with no args in every buffer
and that should try to turn MODE on if applicable for that buffer.
-Each of KEY VALUE is a pair of CL-style keyword arguments. :predicate
-specifies which major modes the globalized minor mode should be switched on
-in. As the minor mode defined by this function is always global, any
-:global keyword is ignored. Other keywords have the same meaning as in
-`define-minor-mode', which see. In particular, :group specifies the custom
-group. The most useful keywords are those that are passed on to the
-`defcustom'. It normally makes no sense to pass the :lighter or :keymap
-keywords to `define-globalized-minor-mode', since these are usually passed
-to the buffer-local version of the minor mode.
+Each of KEY VALUE is a pair of CL-style keyword arguments.
+The :predicate argument specifies in which major modes should the
+globalized minor mode be switched on. The value should be t (meaning
+switch on the minor mode in all major modes), nil (meaning don't
+switch on in any major mode), a list of modes (meaning switch on only
+in those modes and their descendants), or a list (not MODES...),
+meaning switch on in any major mode except MODES. The value can also
+mix all of these forms, see the info node `Defining Minor Modes' for
+details.
+As the minor mode defined by this function is always global, any
+:global keyword is ignored.
+Other keywords have the same meaning as in `define-minor-mode',
+which see. In particular, :group specifies the custom group.
+The most useful keywords are those that are passed on to the `defcustom'.
+It normally makes no sense to pass the :lighter or :keymap keywords
+to `define-globalized-minor-mode', since these are usually passed to
+the buffer-local version of the minor mode.
BODY contains code to execute each time the mode is enabled or disabled.
It is executed after toggling the mode, and before running
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-29 bcd02cf5127: ; Improve documentation of :predicate in globalized minor modes,
Eli Zaretskii <=