From bcd02cf5127ecfe6d6ce4ac316f881246c49db4f Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Thu, 23 Mar 2023 11:30:19 +0200 Subject: ; 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 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) (limited to 'doc') 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 -- cgit v1.2.3 From 1bc9dfc5bee5c69d82f9a3ed448ba2fefea82a96 Mon Sep 17 00:00:00 2001 From: João Távora Date: Tue, 21 Mar 2023 14:55:57 +0000 Subject: ; Minor copyedits to Eglot manual * doc/misc/eglot.texi (Troubleshooting Eglot): Minor fixes. --- doc/misc/eglot.texi | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'doc') diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi index defdf59e865..fc5449b0e8d 100644 --- a/doc/misc/eglot.texi +++ b/doc/misc/eglot.texi @@ -1298,9 +1298,9 @@ user. To report an Eglot bug, send e-mail to @email{bug-gnu-emacs@@gnu.org}. -Get acquainted with Emacs's bug reporting guidelines (@pxref{Bugs,,, -emacs, GNU Emacs Manual}). Then, follow this checklist specific to -Eglot bug rerpots. +To understand how to write this email, get acquainted with Emacs's bug +reporting guidelines (@pxref{Bugs,,, emacs, GNU Emacs Manual}). Then, +follow this Eglot-specific checklist: @enumerate @item @@ -1341,18 +1341,18 @@ since they are usually implicitly loaded when visiting a file in that language. ELPA packages usually live in @code{~/.emacs.d/elpa} (or what is in -@code{package-user-dir}). Please show the listing of files in that -directory as well. +@code{package-user-dir}). Including a listing of files in that +directory is a way to tell the maintainers about ELPA package +versions. @item Include a recipe to replicate the problem with @emph{a clean Emacs -run}. This means @kbd{emacs -Q -f package-initialize} invocation -which starts Emacs with no configuration and initializes the ELPA -packages. A very minimal (no more that 10 lines) @file{.emacs} -initialization file is also acceptable and good means to describe -changes to variables. +run}. The invocation @code{emacs -Q -f package-initialize} starts +Emacs with no configuration and initializes the ELPA packages. A very +minimal @file{.emacs} initialization file (10 lines or less) is also +acceptable and good means to describe changes to variables. -There is usually no need to include @kbd{require} statements in the +There is usually no need to include @code{require} statements in the recipe, as Eglot's functionality uses autoloads. Likewise, there is rarely the need to use things like @@ -1364,9 +1364,9 @@ adding to hooks with @code{add-hook}. Prefer starting Eglot with @item Make sure to double check all the above elements and re-run the recipe to see that the problem is reproducible. Following the recipe should -produce event transcript and error backtraces that are exactly the -same or very similar to the ones you included. If the problem only -happens sometimes, include this information in your bug report. +produce event transcript and error backtraces that are very similar to +the ones you included. If the problem only happens sometimes, mention +this in your report. @end enumerate Please keep in mind that some problems reported against Eglot may -- cgit v1.2.3