changeset 75635:425b89152cb4

(Defining Minor Modes): Document that a :require keyword or similar may be required to make saved customization variables work.
author Chong Yidong <cyd@stupidchicken.com>
date Sat, 03 Feb 2007 17:11:39 +0000
parents 9d9ee16e5ee0
children dccc7ead1ede
files lispref/modes.texi
diffstat 1 files changed, 19 insertions(+), 4 deletions(-) [+]
line wrap: on
line diff
--- a/lispref/modes.texi	Sat Feb 03 17:11:31 2007 +0000
+++ b/lispref/modes.texi	Sat Feb 03 17:11:39 2007 +0000
@@ -1387,9 +1387,18 @@
 Definitions}.
 
 @item :global @var{global}
-If non-@code{nil} specifies that the minor mode should be global.  By
-default, minor modes defined with @code{define-minor-mode} are
-buffer-local.
+If non-@code{nil}, this specifies that the minor mode should be global
+rather than buffer-local.  It defaults to @code{nil}.
+
+One of the effects of making a minor mode global is that the
+@var{mode} variable becomes a customization variable; toggling it
+through the Custom interface to turn the mode on and off, and its
+value can be saved for future Emacs sessions (@pxref{Saving
+Customizations,,, emacs, The GNU Emacs Manual}.  For the saved
+variable to work, you should ensure that the @code{define-minor-mode}
+form is evaluated each time Emacs starts; for packages that are not
+part of Emacs, the easiest way to do this is to specify a
+@code{:require} keyword.
 
 @item :init-value @var{init-value}
 This is equivalent to specifying @var{init-value} positionally.
@@ -1479,7 +1488,7 @@
  :group 'hunger)
 @end smallexample
 
-@defmac define-global-minor-mode global-mode mode turn-on keyword-args@dots{}
+@defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{}
 This defines a global toggle named @var{global-mode} whose meaning is
 to enable or disable the buffer-local minor mode @var{mode} in all
 buffers.  To turn on the minor mode in a buffer, it uses the function
@@ -1491,6 +1500,12 @@
 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 Custom 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.
+
 Use @code{:group @var{group}} in @var{keyword-args} to specify the
 custom group for the mode variable of the global minor mode.
 @end defmac