diff options
author | Glenn Morris <rgm@gnu.org> | 2012-02-07 00:26:54 -0800 |
---|---|---|
committer | Glenn Morris <rgm@gnu.org> | 2012-02-07 00:26:54 -0800 |
commit | 60d47423d1f05071b96857860a8281b318931bee (patch) | |
tree | 1174c0c7270f250aea285d4acc6599d74f943d61 /doc | |
parent | bba26374d0465e50338493a43eaa35312f8612d2 (diff) | |
download | emacs-60d47423d1f05071b96857860a8281b318931bee.tar.gz |
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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/lispref/ChangeLog | 5 | ||||
-rw-r--r-- | doc/lispref/modes.texi | 35 |
2 files changed, 25 insertions, 15 deletions
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 04d1234be06..a172f82d2e5 100644 --- 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 b4aa39dfbb9..052fd037167 100644 --- 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. |