From: Eli Zaretskii Date: Thu, 23 Mar 2023 09:30:19 +0000 (+0200) Subject: ; Improve documentation of :predicate in globalized minor modes X-Git-Tag: emacs-29.0.90~105 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=bcd02cf5127ecfe6d6ce4ac316f881246c49db4f;p=emacs.git ; 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. --- 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