[Emacs-diffs] Changes to emacs/lispref/modes.texi

[Richard M. Stallman]

Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.56 emacs/lispref/modes.texi:1.57
*** emacs/lispref/modes.texi:1.56       Mon Jul  7 16:49:02 2003
--- emacs/lispref/modes.texi    Mon Jul 14 11:59:12 2003
***************
*** 263,277 ****
  @cindex major mode hook
  Each major mode should have a @dfn{mode hook} named
  @address@hidden  The major mode command should run that
! hook, with @code{run-hooks}, as the very last thing it
  does.  @xref{Hooks}.
  
  @item
! The major mode command may also run the hooks of some more basic modes.
! For example, @code{indented-text-mode} runs @code{text-mode-hook} as
! well as @code{indented-text-mode-hook}.  It may run these other hooks
! immediately before the mode's own hook (that is, after everything else),
! or it may run them earlier.
  
  @item
  If something special should be done if the user switches a buffer from
--- 263,280 ----
  @cindex major mode hook
  Each major mode should have a @dfn{mode hook} named
  @address@hidden  The major mode command should run that
! hook, with @code{run-mode-hooks}, as the very last thing it
  does.  @xref{Hooks}.
  
  @item
! The major mode command may start by calling some other major mode
! command (called the @dfn{parent mode}) and then alter some of its
! settings.  A mode that does this is called a @dfn{derived mode}.  The
! recommended way to define one is to use @code{define-derived-mode},
! but this is not required.  Such a mode should use
! @code{delay-mode-hooks} around its entire body, including the call to
! the parent mode command and the final call to @code{run-mode-hooks}.
! (Using @code{define-derived-mode} does this automatically.) 
  
  @item
  If something special should be done if the user switches a buffer from
***************
*** 359,365 ****
  @end group
  @end smallexample
  
!   Here is the complete major mode function definition for Text mode:
  
  @smallexample
  @group
--- 362,368 ----
  @end group
  @end smallexample
  
!   This was formerly the complete major mode function definition for Text mode:
  
  @smallexample
  @group
***************
*** 388,394 ****
  @group
    (setq mode-name "Text")
    (setq major-mode 'text-mode)
!   (run-hooks 'text-mode-hook))      ; @r{Finally, this permits the user to}
                                      ;   @r{customize the mode with a hook.}
  @end group
  @end smallexample
--- 391,397 ----
  @group
    (setq mode-name "Text")
    (setq major-mode 'text-mode)
!   (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
                                      ;   @r{customize the mode with a hook.}
  @end group
  @end smallexample
***************
*** 543,549 ****
  @group
    (setq imenu-case-fold-search t)
    (set-syntax-table lisp-mode-syntax-table)
!   (run-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
                                           ;   @r{hook to customize the mode.}
  @end group
  @end smallexample
--- 546,552 ----
  @group
    (setq imenu-case-fold-search t)
    (set-syntax-table lisp-mode-syntax-table)
!   (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to 
use a}
                                           ;   @r{hook to customize the mode.}
  @end group
  @end smallexample
***************
*** 819,824 ****
--- 822,831 ----
  way to insert the necessary hook into the rest of Emacs.  Minor mode
  keymaps make this easier than it used to be.
  
+ @defvar minor-mode-list
+ The value of this variable is a list of all minor mode commands.
+ @end defvar
+ 
  @menu
  * Minor Mode Conventions::      Tips for writing a minor mode.
  * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
***************
*** 981,1000 ****
  implementing a mode in one self-contained definition.  It supports only
  buffer-local minor modes, not global ones.
  
! @defmac define-minor-mode mode doc &optional init-value mode-indicator keymap 
body...
  @tindex define-minor-mode
! 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.  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}.
  
! The command named @var{mode} finishes by executing the @var{body} forms,
! if any, after it has performed the standard actions such as setting
! the variable named @var{mode}.
! 
! The string @var{mode-indicator} says what to display in the mode line
  when the mode is enabled; if it is @code{nil}, the mode is not displayed
  in the mode line.
  
--- 988,1003 ----
  implementing a mode in one self-contained definition.  It supports only
  buffer-local minor modes, not global ones.
  
! @defmac define-minor-mode mode doc [init-value [lighter [keymap 
keyword-args... body...]]]
  @tindex define-minor-mode
! 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.  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}.
  
! 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
  in the mode line.
  
***************
*** 1005,1012 ****
--- 1008,1044 ----
  @example
  (@var{key-sequence} . @var{definition})
  @end example
+ 
+ The @var{keyword-args} consist of keywords followed by corresponding
+ values.  A few keywords have special meanings:
+ 
+ @table @code
+ @item :global @var{global}
+ If address@hidden specifies that the minor mode should be global.
+ By default, minor modes are buffer-local.
+ 
+ @item :init-value @var{init-value}
+ This is equivalent to specifying @var{init-value} positionally.
+ 
+ @item :lighter @var{lighter}
+ This is equivalent to specifying @var{lighter} positionally.
+ 
+ @item :keymap @var{keymap}
+ This is equivalent to specifying @var{keymap} positionally.
+ @end table
+ 
+ Any other keyword arguments are passed passed directly to the
+ @code{defcustom} generated for the variable @var{mode}.
+ 
+ The command named @var{mode} finishes by executing the @var{body} forms,
+ if any, after it has performed the standard actions such as setting
+ the variable named @var{mode}.
  @end defmac
  
+ @findex easy-mmode-define-minor-mode
+   The name @code{easy-mmode-define-minor-mode} is an alias
+ for this macro.
+ 
    Here is an example of using @code{define-minor-mode}:
  
  @smallexample
***************
*** 1028,1034 ****
     ("\C-\M-\^?"
      . (lambda ()
          (interactive)
!         (hungry-electric-delete t)))))
  @end smallexample
  
  @noindent
--- 1060,1067 ----
     ("\C-\M-\^?"
      . (lambda ()
          (interactive)
!         (hungry-electric-delete t))))
!  :group 'hunger)
  @end smallexample
  
  @noindent
***************
*** 1037,1048 ****
  which indicates whether the mode is enabled, and a variable named
  @code{hungry-mode-map} which holds the keymap that is active when the
  mode is enabled.  It initializes the keymap with key bindings for
! @address@hidden and @address@hidden
  
  
! @findex easy-mmode-define-minor-mode
!   The name @code{easy-mmode-define-minor-mode} is an alias
! for this macro.
  
  @node Mode Line Format
  @section Mode Line Format
--- 1070,1104 ----
  which indicates whether the mode is enabled, and a variable named
  @code{hungry-mode-map} which holds the keymap that is active when the
  mode is enabled.  It initializes the keymap with key bindings for
! @address@hidden and @address@hidden  It puts the variable
! @code{hungry-mode} into custom group @code{hunger}.  There are no
! @var{body} forms---many minor modes don't need any.
  
+   Here's an equivalent way to write it:
  
! @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]."
!  ;; The initial value.
!  :initial-value nil
!  ;; The indicator for the mode line.
!  :lighter " Hungry"
!  ;; The minor mode bindings.
!  :keymap
!  '(("\C-\^?" . hungry-electric-delete)
!    ("\C-\M-\^?"
!     . (lambda ()
!         (interactive)
!         (hungry-electric-delete t))))
!  :group 'hunger)
! @end smallexample
  
  @node Mode Line Format
  @section Mode Line Format
***************
*** 1885,1890 ****
--- 1941,1959 ----
  ("fubar" . fubar-face)
  @end example
  
+ The value of @var{facename} is usually a face name (a symbol), but it
+ can also be a list of the form
+ 
+ @example
+ (face @var{face} @var{prop1} @var{val1} @var{prop2} @address@hidden)
+ @end example
+ 
+ to specify various text properties to put on the text that matches.
+ If you do this, be sure to add the other text property names that you
+ set in this way to the value of @code{font-lock-extra-managed-props}
+ so that the properties will also be cleared out when they are no longer
+ appropriate.
+ 
  @item (@var{matcher} . @var{highlighter})
  In this kind of element, @var{highlighter} is a list
  which specifies how to highlight matches found by @var{matcher}.
***************
*** 2060,2065 ****
--- 2129,2142 ----
  textual modes.
  @end defvar
  
+ @defvar font-lock-extra-managed-props
+ Additional properties (other than @code{face}) that are being managed
+ by Font Lock mode.  Font Lock mode normally manages only the @code{face}
+ property; if you want it to manage others as well, you must specify
+ them in a @var{facename} in @code{font-lock-keywords} as well as adding
+ them to this list.
+ @end defvar
+ 
  @node Levels of Font Lock
  @subsection Levels of Font Lock
  
***************
*** 2163,2168 ****
--- 2240,2249 ----
  @vindex font-lock-constant-face
  Used (typically) for constant names.
  
+ @item font-locl-preprocessor-face
+ @vindex font-locl-preprocessor-face
+ Used (typically) for preprocessor commands.
+ 
  @item font-lock-warning-face
  @vindex font-lock-warning-face
  Used (typically) for constructs that are peculiar, or that greatly
***************
*** 2311,2316 ****
--- 2392,2409 ----
  (run-hooks 'emacs-lisp-mode-hook)
  @end example
  @end defun
+ 
+ @defun run-mode-hooks &rest hookvars
+ Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks}
+ macro.
+ @end defun
+ 
+ @defmac delay-mode-hooks body...
+ This macro executes the @var{body} forms but defers all calls to
+ @code{run-mode-hooks} within them until the end of @var{body}.
+ This macro enables a derived mode to arrange not to run
+ its parent modes' mode hooks until the end.
+ @end defmac
  
  @defun run-hook-with-args hook &rest args
  This function is the way to run an abnormal hook which passes arguments