Doc updates for define-minor-mode argument behavior

* doc/lispref/modes.texi (Defining Minor Modes):
Expand on args of defined minor modes.
* lisp/emacs-lisp/easy-mmode.el (define-minor-mode):
Doc fixes for the macro and the mode it defines.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 04d1234be06545555b1cc91fb2d384eb4f9bd2a7..a172f82d2e55602ca9f2bf85d5225376724b67bd 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2012-02-07  Glenn Morris  <rgm@gnu.org>
+
+       * modes.texi (Defining Minor Modes):
+       Expand on args of defined minor modes.
+
 2012-02-07  Chong Yidong  <cyd@gnu.org>
 
        * variables.texi (Creating Buffer-Local): Minor clarification

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index b4aa39dfbb9a98f1090b57677be5b8c26cf5459c..052fd0371677c26fc104d602bc2eaf69d75af562 100644 (file)
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1380,11 +1380,21 @@ implementing a mode in one self-contained definition.
 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
 This macro defines a new minor mode whose name is @var{mode} (a
 symbol).  It defines a command named @var{mode} to toggle the minor
-mode, with @var{doc} as its documentation string.  By default, it also
-defines a variable named @var{mode}, which is set to @code{t} or
-@code{nil} by enabling or disabling the mode.  The variable is
-initialized to @var{init-value}.  Except in unusual circumstances (see
-below), this value must be @code{nil}.
+mode, with @var{doc} as its documentation string.
+
+The toggle command takes one optional (prefix) argument.
+If called interactively with no argument it toggles the mode on or off.
+A positive prefix argument enables the mode, any other prefix argument
+disables it.  From Lisp, an argument of @code{toggle} toggles the mode,
+whereas an omitted or @code{nil} argument enables the mode.
+This makes it easy to enable the minor mode in a major mode hook, for example.
+If @var{doc} is nil, the macro supplies a default documentation string
+explaining the above.
+
+By default, it also defines a variable named @var{mode}, which is set to
+@code{t} or @code{nil} by enabling or disabling the mode.  The variable
+is initialized to @var{init-value}.  Except in unusual circumstances
+(see below), this value must be @code{nil}.
 
 The string @var{lighter} says what to display in the mode line
 when the mode is enabled; if it is @code{nil}, the mode is not displayed
@@ -1478,9 +1488,10 @@ for this macro.
 @smallexample
 (define-minor-mode hungry-mode
   "Toggle Hungry mode.
-With no argument, this command toggles the mode.
-Non-null prefix argument turns on the mode.
-Null prefix argument turns off the mode.
+Interactively with no argument, this command toggles the mode.
+A positive prefix argument enables the mode, any other prefix
+argument disables it.  From Lisp, argument omitted or nil enables
+the mode, `toggle' toggles the state.
 
 When Hungry mode is enabled, the control delete key
 gobbles all preceding whitespace except the last.
@@ -1509,13 +1520,7 @@ minor modes don't need any.
 @smallexample
 (define-minor-mode hungry-mode
   "Toggle Hungry mode.
-With no argument, this command toggles the mode.
-Non-null prefix argument turns on the mode.
-Null prefix argument turns off the mode.
-
-When Hungry mode is enabled, the control delete key
-gobbles all preceding whitespace except the last.
-See the command \\[hungry-electric-delete]."
+...rest of documentation as before..."
  ;; The initial value.
  :init-value nil
  ;; The indicator for the mode line.

diff --git a/etc/NEWS b/etc/NEWS
index da56151374543ac51e2dff0dad32ed592d96d1ea..5866a06525217d38f34bd84272b76f46551f4901 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1012,8 +1012,11 @@ trouble seems to be an old-style backquote followed by a newline.
 view-file has since Emacs 22 (ie, it won't enable View mode if the
 major-mode is special).
 
-** Passing a nil argument to a minor mode function now turns the mode
-ON unconditionally.
+** Passing a nil argument to a minor mode defined by define-minor-mode
+now turns the mode ON unconditionally.  This is so that you can write, e.g.
+  (add-hook 'text-mode-hook 'foo-minor-mode)
+to enable foo-minor-mode in Text mode buffers, thus removing the need
+for `turn-on-foo-minor-mode' style functions.
 
 +++
 ** During startup, Emacs no longer adds entries for `menu-bar-lines'

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 66025e2ec91960eb905b773ce7102ad14e59d1ea..f69b94fdb7b35aca72374a1d184e1a0be4a64ef3 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,8 @@
 2012-02-07  Glenn Morris  <rgm@gnu.org>
 
+       * emacs-lisp/easy-mmode.el (define-minor-mode):
+       Doc fixes for the macro and the mode it defines.
+
        * image.el (imagemagick-types-inhibit): Doc fix.
 
        * cus-start.el (imagemagick-render-type): Add it.

diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index d871f6f12127d45c1ba5d0589c76d8b7e91261f5..dbacba6cd29febe0d272c9c6056b3cb33ee025ac 100644 (file)
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -90,6 +90,14 @@ This defines the toggle command MODE and (by default) a control variable
 MODE (you can override this with the :variable keyword, see below).
 DOC is the documentation for the mode toggle command.
 
+The defined mode command takes one optional (prefix) argument.
+Interactively with no prefix argument it toggles the mode.
+With a prefix argument, it enables the mode if the argument is
+positive and otherwise disables it.  When called from Lisp, it
+enables the mode if the argument is omitted or nil, and toggles
+the mode if the argument is `toggle'.  If DOC is nil this
+function adds a basic doc-string stating these facts.
+
 Optional INIT-VALUE is the initial value of the mode's variable.
 Optional LIGHTER is displayed in the modeline when the mode is on.
 Optional KEYMAP is the default keymap bound to the mode keymap.
@@ -242,7 +250,7 @@ or call the function `%s'."))))
              (format (concat "Toggle %s on or off.
 With a prefix argument ARG, enable %s if ARG is
 positive, and disable it otherwise.  If called from Lisp, enable
-the mode if ARG is omitted or nil.
+the mode if ARG is omitted or nil, and toggle it if ARG is `toggle'.
 \\{%s}") pretty-name pretty-name keymap-sym))
         ;; Use `toggle' rather than (if ,mode 0 1) so that using
         ;; repeat-command still does the toggling correctly.