info/lispref.info-21

   1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
   2 lispref/lispref.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
   7 END-INFO-DIR-ENTRY
   8
   9    Edition History:
  10
  11    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
  19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
  20
  21    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  22 Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  23 Copyright (C) 1995, 1996 Ben Wing.
  24
  25    Permission is granted to make and distribute verbatim copies of this
  26 manual provided the copyright notice and this permission notice are
  27 preserved on all copies.
  28
  29    Permission is granted to copy and distribute modified versions of
  30 this manual under the conditions for verbatim copying, provided that the
  31 entire resulting derived work is distributed under the terms of a
  32 permission notice identical to this one.
  33
  34    Permission is granted to copy and distribute translations of this
  35 manual into another language, under the above conditions for modified
  36 versions, except that this permission notice may be stated in a
  37 translation approved by the Foundation.
  38
  39    Permission is granted to copy and distribute modified versions of
  40 this manual under the conditions for verbatim copying, provided also
  41 that the section entitled "GNU General Public License" is included
  42 exactly as in the original, and provided that the entire resulting
  43 derived work is distributed under the terms of a permission notice
  44 identical to this one.
  45
  46    Permission is granted to copy and distribute translations of this
  47 manual into another language, under the above conditions for modified
  48 versions, except that the section entitled "GNU General Public License"
  49 may be included in a translation approved by the Free Software
  50 Foundation instead of in the original English.
  51
  52 \1f
  53 File: lispref.info,  Node: CDE dt,  Next: MSWindows OLE,  Prev: OffiX DND,  Up: Supported Protocols
  54
  55 CDE dt
  56 ------
  57
  58    CDE stands for Common Desktop Environment. It is based on the Motif
  59 widget library. It's drag'n'drop protocol is also an abstraction of the
  60 Motif protocol (so it might be possible, that XEmacs will also support
  61 the Motif protocol soon).
  62
  63    CDE has three different types: file, buffer, and text. XEmacs only
  64 uses file and buffer drags. The API will disallow full URL drags, only
  65 file method URLs are passed through.
  66
  67    Buffer drags are always converted to plain text.
  68
  69 \1f
  70 File: lispref.info,  Node: MSWindows OLE,  Next: Loose ends,  Prev: CDE dt,  Up: Supported Protocols
  71
  72 MSWindows OLE
  73 -------------
  74
  75    Only allows file drags and drops.
  76
  77 \1f
  78 File: lispref.info,  Node: Loose ends,  Prev: MSWindows OLE,  Up: Supported Protocols
  79
  80 Loose ends
  81 ----------
  82
  83    The following protocols will be supported soon: Xdnd, Motif, Xde (if
  84 I get some specs), KDE OffiX (if KDE can find XEmacs windows).
  85
  86    In particular Xdnd will be one of the protocols that can benefit from
  87 the XEmacs API, cause it also uses MIME types to encode dragged data.
  88
  89 \1f
  90 File: lispref.info,  Node: Drop Interface,  Next: Drag Interface,  Prev: Supported Protocols,  Up: Drag and Drop
  91
  92 Drop Interface
  93 ==============
  94
  95    For each activated low-level protocol, a internal routine will catch
  96 incoming drops and convert them to a dragdrop-drop type misc-user-event.
  97
  98    This misc-user-event has its function argument set to
  99 `dragdrop-drop-dispatch' and the object contains the data of the drop
 100 (converted to URL/MIME specific data). This function will search the
 101 variable `experimental-dragdrop-drop-functions' for a function that can
 102 handle the dropped data.
 103
 104    To modify the drop behavior, the user can modify the variable
 105 `experimental-dragdrop-drop-functions'. Each element of this list
 106 specifies a possible handler for dropped data. The first one that can
 107 handle the data will return `t' and exit. Another possibility is to set
 108 a extent-property with the same name. Extents are checked prior to the
 109 variable.
 110
 111    The customization group `drag-n-drop' shows all variables of user
 112 interest.
 113
 114 \1f
 115 File: lispref.info,  Node: Drag Interface,  Prev: Drop Interface,  Up: Drag and Drop
 116
 117 Drag Interface
 118 ==============
 119
 120    This describes the drag API (not implemented yet).
 121
 122 \1f
 123 File: lispref.info,  Node: Modes,  Next: Documentation,  Prev: Drag and Drop,  Up: Top
 124
 125 Major and Minor Modes
 126 *********************
 127
 128    A "mode" is a set of definitions that customize XEmacs and can be
 129 turned on and off while you edit.  There are two varieties of modes:
 130 "major modes", which are mutually exclusive and used for editing
 131 particular kinds of text, and "minor modes", which provide features
 132 that users can enable individually.
 133
 134    This chapter describes how to write both major and minor modes, how
 135 to indicate them in the modeline, and how they run hooks supplied by the
 136 user.  For related topics such as keymaps and syntax tables, see *Note
 137 Keymaps::, and *Note Syntax Tables::.
 138
 139 * Menu:
 140
 141 * Major Modes::        Defining major modes.
 142 * Minor Modes::        Defining minor modes.
 143 * Modeline Format::    Customizing the text that appears in the modeline.
 144 * Hooks::              How to use hooks; how to write code that provides hooks.
 145
 146 \1f
 147 File: lispref.info,  Node: Major Modes,  Next: Minor Modes,  Up: Modes
 148
 149 Major Modes
 150 ===========
 151
 152    Major modes specialize XEmacs for editing particular kinds of text.
 153 Each buffer has only one major mode at a time.
 154
 155    The least specialized major mode is called "Fundamental mode".  This
 156 mode has no mode-specific definitions or variable settings, so each
 157 XEmacs command behaves in its default manner, and each option is in its
 158 default state.  All other major modes redefine various keys and options.
 159 For example, Lisp Interaction mode provides special key bindings for
 160 <LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
 161 keys.
 162
 163    When you need to write several editing commands to help you perform a
 164 specialized editing task, creating a new major mode is usually a good
 165 idea.  In practice, writing a major mode is easy (in contrast to
 166 writing a minor mode, which is often difficult).
 167
 168    If the new mode is similar to an old one, it is often unwise to
 169 modify the old one to serve two purposes, since it may become harder to
 170 use and maintain.  Instead, copy and rename an existing major mode
 171 definition and alter the copy--or define a "derived mode" (*note
 172 Derived Modes::).  For example, Rmail Edit mode, which is in
 173 `emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
 174 mode except that it provides three additional commands.  Its definition
 175 is distinct from that of Text mode, but was derived from it.
 176
 177    Rmail Edit mode is an example of a case where one piece of text is
 178 put temporarily into a different major mode so it can be edited in a
 179 different way (with ordinary XEmacs commands rather than Rmail).  In
 180 such cases, the temporary major mode usually has a command to switch
 181 back to the buffer's usual mode (Rmail mode, in this case).  You might
 182 be tempted to present the temporary redefinitions inside a recursive
 183 edit and restore the usual ones when the user exits; but this is a bad
 184 idea because it constrains the user's options when it is done in more
 185 than one buffer: recursive edits must be exited most-recently-entered
 186 first.  Using alternative major modes avoids this limitation.  *Note
 187 Recursive Editing::.
 188
 189    The standard XEmacs Lisp library directory contains the code for
 190 several major modes, in files including `text-mode.el', `texinfo.el',
 191 `lisp-mode.el', `c-mode.el', and `rmail.el'.  You can look at these
 192 libraries to see how modes are written.  Text mode is perhaps the
 193 simplest major mode aside from Fundamental mode.  Rmail mode is a
 194 complicated and specialized mode.
 195
 196 * Menu:
 197
 198 * Major Mode Conventions::  Coding conventions for keymaps, etc.
 199 * Example Major Modes::     Text mode and Lisp modes.
 200 * Auto Major Mode::         How XEmacs chooses the major mode automatically.
 201 * Mode Help::               Finding out how to use a mode.
 202 * Derived Modes::           Defining a new major mode based on another major
 203                               mode.
 204
 205 \1f
 206 File: lispref.info,  Node: Major Mode Conventions,  Next: Example Major Modes,  Up: Major Modes
 207
 208 Major Mode Conventions
 209 ----------------------
 210
 211    The code for existing major modes follows various coding conventions,
 212 including conventions for local keymap and syntax table initialization,
 213 global names, and hooks.  Please follow these conventions when you
 214 define a new major mode:
 215
 216    * Define a command whose name ends in `-mode', with no arguments,
 217      that switches to the new mode in the current buffer.  This command
 218      should set up the keymap, syntax table, and local variables in an
 219      existing buffer without changing the buffer's text.
 220
 221    * Write a documentation string for this command that describes the
 222      special commands available in this mode.  `C-h m'
 223      (`describe-mode') in your mode will display this string.
 224
 225      The documentation string may include the special documentation
 226      substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
 227      enable the documentation to adapt automatically to the user's own
 228      key bindings.  *Note Keys in Documentation::.
 229
 230    * The major mode command should start by calling
 231      `kill-all-local-variables'.  This is what gets rid of the local
 232      variables of the major mode previously in effect.
 233
 234    * The major mode command should set the variable `major-mode' to the
 235      major mode command symbol.  This is how `describe-mode' discovers
 236      which documentation to print.
 237
 238    * The major mode command should set the variable `mode-name' to the
 239      "pretty" name of the mode, as a string.  This appears in the mode
 240      line.
 241
 242    * Since all global names are in the same name space, all the global
 243      variables, constants, and functions that are part of the mode
 244      should have names that start with the major mode name (or with an
 245      abbreviation of it if the name is long).  *Note Style Tips::.
 246
 247    * The major mode should usually have its own keymap, which is used
 248      as the local keymap in all buffers in that mode.  The major mode
 249      function should call `use-local-map' to install this local map.
 250      *Note Active Keymaps::, for more information.
 251
 252      This keymap should be kept in a global variable named
 253      `MODENAME-mode-map'.  Normally the library that defines the mode
 254      sets this variable.
 255
 256    * The mode may have its own syntax table or may share one with other
 257      related modes.  If it has its own syntax table, it should store
 258      this in a variable named `MODENAME-mode-syntax-table'.  *Note
 259      Syntax Tables::.
 260
 261    * The mode may have its own abbrev table or may share one with other
 262      related modes.  If it has its own abbrev table, it should store
 263      this in a variable named `MODENAME-mode-abbrev-table'.  *Note
 264      Abbrev Tables::.
 265
 266    * Use `defvar' to set mode-related variables, so that they are not
 267      reinitialized if they already have a value.  (Such reinitialization
 268      could discard customizations made by the user.)
 269
 270    * To make a buffer-local binding for an Emacs customization
 271      variable, use `make-local-variable' in the major mode command, not
 272      `make-variable-buffer-local'.  The latter function would make the
 273      variable local to every buffer in which it is subsequently set,
 274      which would affect buffers that do not use this mode.  It is
 275      undesirable for a mode to have such global effects.  *Note
 276      Buffer-Local Variables::.
 277
 278      It's ok to use `make-variable-buffer-local', if you wish, for a
 279      variable used only within a single Lisp package.
 280
 281    * Each major mode should have a "mode hook" named
 282      `MODENAME-mode-hook'.  The major mode command should run that
 283      hook, with `run-hooks', as the very last thing it does. *Note
 284      Hooks::.
 285
 286    * The major mode command may also run the hooks of some more basic
 287      modes.  For example, `indented-text-mode' runs `text-mode-hook' as
 288      well as `indented-text-mode-hook'.  It may run these other hooks
 289      immediately before the mode's own hook (that is, after everything
 290      else), or it may run them earlier.
 291
 292    * If something special should be done if the user switches a buffer
 293      from this mode to any other major mode, the mode can set a local
 294      value for `change-major-mode-hook'.
 295
 296    * If this mode is appropriate only for specially-prepared text, then
 297      the major mode command symbol should have a property named
 298      `mode-class' with value `special', put on as follows:
 299
 300           (put 'funny-mode 'mode-class 'special)
 301
 302      This tells XEmacs that new buffers created while the current
 303      buffer has Funny mode should not inherit Funny mode.  Modes such
 304      as Dired, Rmail, and Buffer List use this feature.
 305
 306    * If you want to make the new mode the default for files with certain
 307      recognizable names, add an element to `auto-mode-alist' to select
 308      the mode for those file names.  If you define the mode command to
 309      autoload, you should add this element in the same file that calls
 310      `autoload'.  Otherwise, it is sufficient to add the element in the
 311      file that contains the mode definition.  *Note Auto Major Mode::.
 312
 313    * In the documentation, you should provide a sample `autoload' form
 314      and an example of how to add to `auto-mode-alist', that users can
 315      include in their `.emacs' files.
 316
 317    * The top-level forms in the file defining the mode should be
 318      written so that they may be evaluated more than once without
 319      adverse consequences.  Even if you never load the file more than
 320      once, someone else will.
 321
 322  - Variable: change-major-mode-hook
 323      This normal hook is run by `kill-all-local-variables' before it
 324      does anything else.  This gives major modes a way to arrange for
 325      something special to be done if the user switches to a different
 326      major mode.  For best results, make this variable buffer-local, so
 327      that it will disappear after doing its job and will not interfere
 328      with the subsequent major mode.  *Note Hooks::.
 329
 330 \1f
 331 File: lispref.info,  Node: Example Major Modes,  Next: Auto Major Mode,  Prev: Major Mode Conventions,  Up: Major Modes
 332
 333 Major Mode Examples
 334 -------------------
 335
 336    Text mode is perhaps the simplest mode besides Fundamental mode.
 337 Here are excerpts from  `text-mode.el' that illustrate many of the
 338 conventions listed above:
 339
 340      ;; Create mode-specific tables.
 341      (defvar text-mode-syntax-table nil
 342        "Syntax table used while in text mode.")
 343
 344      (if text-mode-syntax-table
 345          ()              ; Do not change the table if it is already set up.
 346        (setq text-mode-syntax-table (make-syntax-table))
 347        (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
 348        (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
 349        (modify-syntax-entry ?' "w   " text-mode-syntax-table))
 350
 351      (defvar text-mode-abbrev-table nil
 352        "Abbrev table used while in text mode.")
 353      (define-abbrev-table 'text-mode-abbrev-table ())
 354
 355      (defvar text-mode-map nil)   ; Create a mode-specific keymap.
 356
 357      (if text-mode-map
 358          ()              ; Do not change the keymap if it is already set up.
 359        (setq text-mode-map (make-sparse-keymap))
 360        (define-key text-mode-map "\t" 'tab-to-tab-stop)
 361        (define-key text-mode-map "\es" 'center-line)
 362        (define-key text-mode-map "\eS" 'center-paragraph))
 363
 364    Here is the complete major mode function definition for Text mode:
 365
 366      (defun text-mode ()
 367        "Major mode for editing text intended for humans to read.
 368       Special commands: \\{text-mode-map}
 369      Turning on text-mode runs the hook `text-mode-hook'."
 370        (interactive)
 371        (kill-all-local-variables)
 372        (use-local-map text-mode-map)     ; This provides the local keymap.
 373        (setq mode-name "Text")           ; This name goes into the modeline.
 374        (setq major-mode 'text-mode)      ; This is how `describe-mode'
 375                                          ;   finds the doc string to print.
 376        (setq local-abbrev-table text-mode-abbrev-table)
 377        (set-syntax-table text-mode-syntax-table)
 378        (run-hooks 'text-mode-hook))      ; Finally, this permits the user to
 379                                          ;   customize the mode with a hook.
 380
 381    The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
 382 Interaction mode) have more features than Text mode and the code is
 383 correspondingly more complicated.  Here are excerpts from
 384 `lisp-mode.el' that illustrate how these modes are written.
 385
 386      ;; Create mode-specific table variables.
 387      (defvar lisp-mode-syntax-table nil "")
 388      (defvar emacs-lisp-mode-syntax-table nil "")
 389      (defvar lisp-mode-abbrev-table nil "")
 390
 391      (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
 392                                             ;   if it is already set.
 393          (let ((i 0))
 394            (setq emacs-lisp-mode-syntax-table (make-syntax-table))
 395
 396            ;; Set syntax of chars up to 0 to class of chars that are
 397            ;;   part of symbol names but not words.
 398            ;;   (The number 0 is `48' in the ASCII character set.)
 399            (while (< i ?0)
 400              (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
 401              (setq i (1+ i)))
 402            ...
 403            ;; Set the syntax for other characters.
 404            (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
 405            (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
 406            ...
 407            (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
 408            (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
 409            ...))
 410      ;; Create an abbrev table for lisp-mode.
 411      (define-abbrev-table 'lisp-mode-abbrev-table ())
 412
 413    Much code is shared among the three Lisp modes.  The following
 414 function sets various variables; it is called by each of the major Lisp
 415 mode functions:
 416
 417      (defun lisp-mode-variables (lisp-syntax)
 418        ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
 419        ;;   and `t' in the other two Lisp modes.
 420        (cond (lisp-syntax
 421               (if (not lisp-mode-syntax-table)
 422                   ;; The Emacs Lisp mode syntax table always exists, but
 423                   ;;   the Lisp Mode syntax table is created the first time a
 424                   ;;   mode that needs it is called.  This is to save space.
 425                   (progn (setq lisp-mode-syntax-table
 426                             (copy-syntax-table emacs-lisp-mode-syntax-table))
 427                          ;; Change some entries for Lisp mode.
 428                          (modify-syntax-entry ?\| "\"   "
 429                                               lisp-mode-syntax-table)
 430                          (modify-syntax-entry ?\[ "_   "
 431                                               lisp-mode-syntax-table)
 432                          (modify-syntax-entry ?\] "_   "
 433                                               lisp-mode-syntax-table)))
 434                (set-syntax-table lisp-mode-syntax-table)))
 435        (setq local-abbrev-table lisp-mode-abbrev-table)
 436        ...)
 437
 438    Functions such as `forward-paragraph' use the value of the
 439 `paragraph-start' variable.  Since Lisp code is different from ordinary
 440 text, the `paragraph-start' variable needs to be set specially to
 441 handle Lisp.  Also, comments are indented in a special fashion in Lisp
 442 and the Lisp modes need their own mode-specific
 443 `comment-indent-function'.  The code to set these variables is the rest
 444 of `lisp-mode-variables'.
 445
 446        (make-local-variable 'paragraph-start)
 447        ;; Having `^' is not clean, but `page-delimiter'
 448        ;; has them too, and removing those is a pain.
 449        (setq paragraph-start (concat "^$\\|" page-delimiter))
 450        ...
 451        (make-local-variable 'comment-indent-function)
 452        (setq comment-indent-function 'lisp-comment-indent))
 453
 454    Each of the different Lisp modes has a slightly different keymap.
 455 For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
 456 Lisp modes do not.  However, all Lisp modes have some commands in
 457 common.  The following function adds these common commands to a given
 458 keymap.
 459
 460      (defun lisp-mode-commands (map)
 461        (define-key map "\e\C-q" 'indent-sexp)
 462        (define-key map "\177" 'backward-delete-char-untabify)
 463        (define-key map "\t" 'lisp-indent-line))
 464
 465    Here is an example of using `lisp-mode-commands' to initialize a
 466 keymap, as part of the code for Emacs Lisp mode.  First we declare a
 467 variable with `defvar' to hold the mode-specific keymap.  When this
 468 `defvar' executes, it sets the variable to `nil' if it was void.  Then
 469 we set up the keymap if the variable is `nil'.
 470
 471    This code avoids changing the keymap or the variable if it is already
 472 set up.  This lets the user customize the keymap.
 473
 474      (defvar emacs-lisp-mode-map () "")
 475      (if emacs-lisp-mode-map
 476          ()
 477        (setq emacs-lisp-mode-map (make-sparse-keymap))
 478        (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
 479        (lisp-mode-commands emacs-lisp-mode-map))
 480
 481    Finally, here is the complete major mode function definition for
 482 Emacs Lisp mode.
 483
 484      (defun emacs-lisp-mode ()
 485        "Major mode for editing Lisp code to run in XEmacs.
 486      Commands:
 487      Delete converts tabs to spaces as it moves back.
 488      Blank lines separate paragraphs.  Semicolons start comments.
 489      \\{emacs-lisp-mode-map}
 490      Entry to this mode runs the hook `emacs-lisp-mode-hook'."
 491        (interactive)
 492        (kill-all-local-variables)
 493        (use-local-map emacs-lisp-mode-map)    ; This provides the local keymap.
 494        (set-syntax-table emacs-lisp-mode-syntax-table)
 495        (setq major-mode 'emacs-lisp-mode)     ; This is how `describe-mode'
 496                                               ;   finds out what to describe.
 497        (setq mode-name "Emacs-Lisp")          ; This goes into the modeline.
 498        (lisp-mode-variables nil)              ; This defines various variables.
 499        (run-hooks 'emacs-lisp-mode-hook))     ; This permits the user to use a
 500                                               ;   hook to customize the mode.
 501
 502 \1f
 503 File: lispref.info,  Node: Auto Major Mode,  Next: Mode Help,  Prev: Example Major Modes,  Up: Major Modes
 504
 505 How XEmacs Chooses a Major Mode
 506 -------------------------------
 507
 508    Based on information in the file name or in the file itself, XEmacs
 509 automatically selects a major mode for the new buffer when a file is
 510 visited.
 511
 512  - Command: fundamental-mode
 513      Fundamental mode is a major mode that is not specialized for
 514      anything in particular.  Other major modes are defined in effect
 515      by comparison with this one--their definitions say what to change,
 516      starting from Fundamental mode.  The `fundamental-mode' function
 517      does _not_ run any hooks; you're not supposed to customize it.
 518      (If you want Emacs to behave differently in Fundamental mode,
 519      change the _global_ state of Emacs.)
 520
 521  - Command: normal-mode &optional find-file
 522      This function establishes the proper major mode and local variable
 523      bindings for the current buffer.  First it calls `set-auto-mode',
 524      then it runs `hack-local-variables' to parse, and bind or evaluate
 525      as appropriate, any local variables.
 526
 527      If the FIND-FILE argument to `normal-mode' is non-`nil',
 528      `normal-mode' assumes that the `find-file' function is calling it.
 529      In this case, it may process a local variables list at the end of
 530      the file and in the `-*-' line.  The variable
 531      `enable-local-variables' controls whether to do so.
 532
 533      If you run `normal-mode' interactively, the argument FIND-FILE is
 534      normally `nil'.  In this case, `normal-mode' unconditionally
 535      processes any local variables list.  *Note Local Variables in
 536      Files: (emacs)File variables, for the syntax of the local
 537      variables section of a file.
 538
 539      `normal-mode' uses `condition-case' around the call to the major
 540      mode function, so errors are caught and reported as a `File mode
 541      specification error',  followed by the original error message.
 542
 543  - User Option: enable-local-variables
 544      This variable controls processing of local variables lists in files
 545      being visited.  A value of `t' means process the local variables
 546      lists unconditionally; `nil' means ignore them; anything else means
 547      ask the user what to do for each file.  The default value is `t'.
 548
 549  - Variable: ignored-local-variables
 550      This variable holds a list of variables that should not be set by
 551      a local variables list.  Any value specified for one of these
 552      variables is ignored.
 553
 554    In addition to this list, any variable whose name has a non-`nil'
 555 `risky-local-variable' property is also ignored.
 556
 557  - User Option: enable-local-eval
 558      This variable controls processing of `Eval:' in local variables
 559      lists in files being visited.  A value of `t' means process them
 560      unconditionally; `nil' means ignore them; anything else means ask
 561      the user what to do for each file.  The default value is `maybe'.
 562
 563  - Function: set-auto-mode
 564      This function selects the major mode that is appropriate for the
 565      current buffer.  It may base its decision on the value of the `-*-'
 566      line, on the visited file name (using `auto-mode-alist'), or on the
 567      value of a local variable.  However, this function does not look
 568      for the `mode:' local variable near the end of a file; the
 569      `hack-local-variables' function does that.  *Note How Major Modes
 570      are Chosen: (emacs)Choosing Modes.
 571
 572  - User Option: default-major-mode
 573      This variable holds the default major mode for new buffers.  The
 574      standard value is `fundamental-mode'.
 575
 576      If the value of `default-major-mode' is `nil', XEmacs uses the
 577      (previously) current buffer's major mode for the major mode of a
 578      new buffer.  However, if the major mode symbol has a `mode-class'
 579      property with value `special', then it is not used for new buffers;
 580      Fundamental mode is used instead.  The modes that have this
 581      property are those such as Dired and Rmail that are useful only
 582      with text that has been specially prepared.
 583
 584  - Function: set-buffer-major-mode buffer
 585      This function sets the major mode of BUFFER to the value of
 586      `default-major-mode'.  If that variable is `nil', it uses the
 587      current buffer's major mode (if that is suitable).
 588
 589      The low-level primitives for creating buffers do not use this
 590      function, but medium-level commands such as `switch-to-buffer' and
 591      `find-file-noselect' use it whenever they create buffers.
 592
 593  - Variable: initial-major-mode
 594      The value of this variable determines the major mode of the initial
 595      `*scratch*' buffer.  The value should be a symbol that is a major
 596      mode command name.  The default value is `lisp-interaction-mode'.
 597
 598  - Variable: auto-mode-alist
 599      This variable contains an association list of file name patterns
 600      (regular expressions; *note Regular Expressions::) and
 601      corresponding major mode functions.  Usually, the file name
 602      patterns test for suffixes, such as `.el' and `.c', but this need
 603      not be the case.  An ordinary element of the alist looks like
 604      `(REGEXP .  MODE-FUNCTION)'.
 605
 606      For example,
 607
 608           (("^/tmp/fol/" . text-mode)
 609            ("\\.texinfo\\'" . texinfo-mode)
 610            ("\\.texi\\'" . texinfo-mode)
 611            ("\\.el\\'" . emacs-lisp-mode)
 612            ("\\.c\\'" . c-mode)
 613            ("\\.h\\'" . c-mode)
 614            ...)
 615
 616      When you visit a file whose expanded file name (*note File Name
 617      Expansion::) matches a REGEXP, `set-auto-mode' calls the
 618      corresponding MODE-FUNCTION.  This feature enables XEmacs to select
 619      the proper major mode for most files.
 620
 621      If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
 622      t)', then after calling FUNCTION, XEmacs searches
 623      `auto-mode-alist' again for a match against the portion of the file
 624      name that did not match before.
 625
 626      This match-again feature is useful for uncompression packages: an
 627      entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
 628      and then put the uncompressed file in the proper mode according to
 629      the name sans `.gz'.
 630
 631      Here is an example of how to prepend several pattern pairs to
 632      `auto-mode-alist'.  (You might use this sort of expression in your
 633      `.emacs' file.)
 634
 635           (setq auto-mode-alist
 636             (append
 637              ;; File name starts with a dot.
 638              '(("/\\.[^/]*\\'" . fundamental-mode)
 639                ;; File name has no dot.
 640                ("[^\\./]*\\'" . fundamental-mode)
 641                ;; File name ends in `.C'.
 642                ("\\.C\\'" . c++-mode))
 643              auto-mode-alist))
 644
 645  - Variable: interpreter-mode-alist
 646      This variable specifies major modes to use for scripts that
 647      specify a command interpreter in an `#!' line.  Its value is a
 648      list of elements of the form `(INTERPRETER . MODE)'; for example,
 649      `("perl" . perl-mode)' is one element present by default.  The
 650      element says to use mode MODE if the file specifies INTERPRETER.
 651
 652      This variable is applicable only when the `auto-mode-alist' does
 653      not indicate which major mode to use.
 654
 655  - Function: hack-local-variables &optional force
 656      This function parses, and binds or evaluates as appropriate, any
 657      local variables for the current buffer.
 658
 659      The handling of `enable-local-variables' documented for
 660      `normal-mode' actually takes place here.  The argument FORCE
 661      usually comes from the argument FIND-FILE given to `normal-mode'.
 662
 663 \1f
 664 File: lispref.info,  Node: Mode Help,  Next: Derived Modes,  Prev: Auto Major Mode,  Up: Major Modes
 665
 666 Getting Help about a Major Mode
 667 -------------------------------
 668
 669    The `describe-mode' function is used to provide information about
 670 major modes.  It is normally called with `C-h m'.  The `describe-mode'
 671 function uses the value of `major-mode', which is why every major mode
 672 function needs to set the `major-mode' variable.
 673
 674  - Command: describe-mode
 675      This function displays the documentation of the current major mode.
 676
 677      The `describe-mode' function calls the `documentation' function
 678      using the value of `major-mode' as an argument.  Thus, it displays
 679      the documentation string of the major mode function.  (*Note
 680      Accessing Documentation::.)
 681
 682  - Variable: major-mode
 683      This variable holds the symbol for the current buffer's major mode.
 684      This symbol should have a function definition that is the command
 685      to switch to that major mode.  The `describe-mode' function uses
 686      the documentation string of the function as the documentation of
 687      the major mode.
 688
 689 \1f
 690 File: lispref.info,  Node: Derived Modes,  Prev: Mode Help,  Up: Major Modes
 691
 692 Defining Derived Modes
 693 ----------------------
 694
 695    It's often useful to define a new major mode in terms of an existing
 696 one.  An easy way to do this is to use `define-derived-mode'.
 697
 698  - Macro: define-derived-mode variant parent name docstring body...
 699      This construct defines VARIANT as a major mode command, using NAME
 700      as the string form of the mode name.
 701
 702      The new command VARIANT is defined to call the function PARENT,
 703      then override certain aspects of that parent mode:
 704
 705         * The new mode has its own keymap, named `VARIANT-map'.
 706           `define-derived-mode' initializes this map to inherit from
 707           `PARENT-map', if it is not already set.
 708
 709         * The new mode has its own syntax table, kept in the variable
 710           `VARIANT-syntax-table'.  `define-derived-mode' initializes
 711           this variable by copying `PARENT-syntax-table', if it is not
 712           already set.
 713
 714         * The new mode has its own abbrev table, kept in the variable
 715           `VARIANT-abbrev-table'.  `define-derived-mode' initializes
 716           this variable by copying `PARENT-abbrev-table', if it is not
 717           already set.
 718
 719         * The new mode has its own mode hook, `VARIANT-hook', which it
 720           runs in standard fashion as the very last thing that it does.
 721           (The new mode also runs the mode hook of PARENT as part of
 722           calling PARENT.)
 723
 724      In addition, you can specify how to override other aspects of
 725      PARENT with BODY.  The command VARIANT evaluates the forms in BODY
 726      after setting up all its usual overrides, just before running
 727      `VARIANT-hook'.
 728
 729      The argument DOCSTRING specifies the documentation string for the
 730      new mode.  If you omit DOCSTRING, `define-derived-mode' generates
 731      a documentation string.
 732
 733      Here is a hypothetical example:
 734
 735           (define-derived-mode hypertext-mode
 736             text-mode "Hypertext"
 737             "Major mode for hypertext.
 738           \\{hypertext-mode-map}"
 739             (setq case-fold-search nil))
 740
 741           (define-key hypertext-mode-map
 742             [down-mouse-3] 'do-hyper-link)
 743
 744 \1f
 745 File: lispref.info,  Node: Minor Modes,  Next: Modeline Format,  Prev: Major Modes,  Up: Modes
 746
 747 Minor Modes
 748 ===========
 749
 750    A "minor mode" provides features that users may enable or disable
 751 independently of the choice of major mode.  Minor modes can be enabled
 752 individually or in combination.  Minor modes would be better named
 753 "Generally available, optional feature modes" except that such a name is
 754 unwieldy.
 755
 756    A minor mode is not usually a modification of single major mode.  For
 757 example, Auto Fill mode may be used in any major mode that permits text
 758 insertion.  To be general, a minor mode must be effectively independent
 759 of the things major modes do.
 760
 761    A minor mode is often much more difficult to implement than a major
 762 mode.  One reason is that you should be able to activate and deactivate
 763 minor modes in any order.  A minor mode should be able to have its
 764 desired effect regardless of the major mode and regardless of the other
 765 minor modes in effect.
 766
 767    Often the biggest problem in implementing a minor mode is finding a
 768 way to insert the necessary hook into the rest of XEmacs.  Minor mode
 769 keymaps make this easier than it used to be.
 770
 771 * Menu:
 772
 773 * Minor Mode Conventions::      Tips for writing a minor mode.
 774 * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
 775
 776 \1f
 777 File: lispref.info,  Node: Minor Mode Conventions,  Next: Keymaps and Minor Modes,  Up: Minor Modes
 778
 779 Conventions for Writing Minor Modes
 780 -----------------------------------
 781
 782    There are conventions for writing minor modes just as there are for
 783 major modes.  Several of the major mode conventions apply to minor
 784 modes as well: those regarding the name of the mode initialization
 785 function, the names of global symbols, and the use of keymaps and other
 786 tables.
 787
 788    In addition, there are several conventions that are specific to
 789 minor modes.
 790
 791    * Make a variable whose name ends in `-mode' to represent the minor
 792      mode.  Its value should enable or disable the mode (`nil' to
 793      disable; anything else to enable.)  We call this the "mode
 794      variable".
 795
 796      This variable is used in conjunction with the `minor-mode-alist' to
 797      display the minor mode name in the modeline.  It can also enable
 798      or disable a minor mode keymap.  Individual commands or hooks can
 799      also check the variable's value.
 800
 801      If you want the minor mode to be enabled separately in each buffer,
 802      make the variable buffer-local.
 803
 804    * Define a command whose name is the same as the mode variable.  Its
 805      job is to enable and disable the mode by setting the variable.
 806
 807      The command should accept one optional argument.  If the argument
 808      is `nil', it should toggle the mode (turn it on if it is off, and
 809      off if it is on).  Otherwise, it should turn the mode on if the
 810      argument is a positive integer, a symbol other than `nil' or `-',
 811      or a list whose CAR is such an integer or symbol; it should turn
 812      the mode off otherwise.
 813
 814      Here is an example taken from the definition of
 815      `transient-mark-mode'.  It shows the use of `transient-mark-mode'
 816      as a variable that enables or disables the mode's behavior, and
 817      also shows the proper way to toggle, enable or disable the minor
 818      mode based on the raw prefix argument value.
 819
 820           (setq transient-mark-mode
 821                 (if (null arg) (not transient-mark-mode)
 822                   (> (prefix-numeric-value arg) 0)))
 823
 824    * Add an element to `minor-mode-alist' for each minor mode (*note
 825      Modeline Variables::).  This element should be a list of the
 826      following form:
 827
 828           (MODE-VARIABLE STRING)
 829
 830      Here MODE-VARIABLE is the variable that controls enabling of the
 831      minor mode, and STRING is a short string, starting with a space,
 832      to represent the mode in the modeline.  These strings must be
 833      short so that there is room for several of them at once.
 834
 835      When you add an element to `minor-mode-alist', use `assq' to check
 836      for an existing element, to avoid duplication.  For example:
 837
 838           (or (assq 'leif-mode minor-mode-alist)
 839               (setq minor-mode-alist
 840                     (cons '(leif-mode " Leif") minor-mode-alist)))
 841
 842 \1f
 843 File: lispref.info,  Node: Keymaps and Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes
 844
 845 Keymaps and Minor Modes
 846 -----------------------
 847
 848    Each minor mode can have its own keymap, which is active when the
 849 mode is enabled.  To set up a keymap for a minor mode, add an element
 850 to the alist `minor-mode-map-alist'.  *Note Active Keymaps::.
 851
 852    One use of minor mode keymaps is to modify the behavior of certain
 853 self-inserting characters so that they do something else as well as
 854 self-insert.  In general, this is the only way to do that, since the
 855 facilities for customizing `self-insert-command' are limited to special
 856 cases (designed for abbrevs and Auto Fill mode).  (Do not try
 857 substituting your own definition of `self-insert-command' for the
 858 standard one.  The editor command loop handles this function specially.)
 859
 860 \1f
 861 File: lispref.info,  Node: Modeline Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes
 862
 863 Modeline Format
 864 ===============
 865
 866    Each Emacs window (aside from minibuffer windows) includes a
 867 modeline, which displays status information about the buffer displayed
 868 in the window.  The modeline contains information about the buffer,
 869 such as its name, associated file, depth of recursive editing, and the
 870 major and minor modes.
 871
 872    This section describes how the contents of the modeline are
 873 controlled.  It is in the chapter on modes because much of the
 874 information displayed in the modeline relates to the enabled major and
 875 minor modes.
 876
 877    `modeline-format' is a buffer-local variable that holds a template
 878 used to display the modeline of the current buffer.  All windows for
 879 the same buffer use the same `modeline-format' and their modelines
 880 appear the same (except for scrolling percentages and line numbers).
 881
 882    The modeline of a window is normally updated whenever a different
 883 buffer is shown in the window, or when the buffer's modified-status
 884 changes from `nil' to `t' or vice-versa.  If you modify any of the
 885 variables referenced by `modeline-format' (*note Modeline Variables::),
 886 you may want to force an update of the modeline so as to display the
 887 new information.
 888
 889  - Function: redraw-modeline &optional all
 890      Force redisplay of the current buffer's modeline.  If ALL is
 891      non-`nil', then force redisplay of all modelines.
 892
 893    The modeline is usually displayed in inverse video.  This is
 894 controlled using the `modeline' face.  *Note Faces::.
 895
 896 * Menu:
 897
 898 * Modeline Data::         The data structure that controls the modeline.
 899 * Modeline Variables::    Variables used in that data structure.
 900 * %-Constructs::          Putting information into a modeline.
 901
 902 \1f
 903 File: lispref.info,  Node: Modeline Data,  Next: Modeline Variables,  Up: Modeline Format
 904
 905 The Data Structure of the Modeline
 906 ----------------------------------
 907
 908    The modeline contents are controlled by a data structure of lists,
 909 strings, symbols, and numbers kept in the buffer-local variable
 910 `modeline-format'.  The data structure is called a "modeline
 911 construct", and it is built in recursive fashion out of simpler modeline
 912 constructs.  The same data structure is used for constructing frame
 913 titles (*note Frame Titles::).
 914
 915  - Variable: modeline-format
 916      The value of this variable is a modeline construct with overall
 917      responsibility for the modeline format.  The value of this variable
 918      controls which other variables are used to form the modeline text,
 919      and where they appear.
 920
 921    A modeline construct may be as simple as a fixed string of text, but
 922 it usually specifies how to use other variables to construct the text.
 923 Many of these variables are themselves defined to have modeline
 924 constructs as their values.
 925
 926    The default value of `modeline-format' incorporates the values of
 927 variables such as `mode-name' and `minor-mode-alist'.  Because of this,
 928 very few modes need to alter `modeline-format'.  For most purposes, it
 929 is sufficient to alter the variables referenced by `modeline-format'.
 930
 931    A modeline construct may be a string, symbol, glyph, generic
 932 specifier, list or cons cell.
 933
 934 `STRING'
 935      A string as a modeline construct is displayed verbatim in the mode
 936      line except for "`%'-constructs".  Decimal digits after the `%'
 937      specify the field width for space filling on the right (i.e., the
 938      data is left justified).  *Note %-Constructs::.
 939
 940 `SYMBOL'
 941      A symbol as a modeline construct stands for its value.  The value
 942      of SYMBOL is processed as a modeline construct, in place of
 943      SYMBOL.  However, the symbols `t' and `nil' are ignored; so is any
 944      symbol whose value is void.
 945
 946      There is one exception: if the value of SYMBOL is a string, it is
 947      displayed verbatim: the `%'-constructs are not recognized.
 948
 949 `GLYPH'
 950      A glyph is displayed as is.
 951
 952 `GENERIC-SPECIFIER'
 953      A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands
 954      for its instance.  The instance of GENERIC-SPECIFIER is computed
 955      in the current window using the equivalent of `specifier-instance'
 956      and the value is processed.
 957
 958 `(STRING REST...) or (LIST REST...)'
 959      A list whose first element is a string or list means to process
 960      all the elements recursively and concatenate the results.  This is
 961      the most common form of mode line construct.
 962
 963 `(SYMBOL THEN ELSE)'
 964      A list whose first element is a symbol is a conditional.  Its
 965      meaning depends on the value of SYMBOL.  If the value is non-`nil',
 966      the second element, THEN, is processed recursively as a modeline
 967      element.  But if the value of SYMBOL is `nil', the third element,
 968      ELSE, is processed recursively.  You may omit ELSE; then the mode
 969      line element displays nothing if the value of SYMBOL is `nil'.
 970
 971 `(WIDTH REST...)'
 972      A list whose first element is an integer specifies truncation or
 973      padding of the results of REST.  The remaining elements REST are
 974      processed recursively as modeline constructs and concatenated
 975      together.  Then the result is space filled (if WIDTH is positive)
 976      or truncated (to -WIDTH columns, if WIDTH is negative) on the
 977      right.
 978
 979      For example, the usual way to show what percentage of a buffer is
 980      above the top of the window is to use a list like this: `(-3
 981      "%p")'.
 982
 983 `(EXTENT REST...)'
 984      A list whose car is an extent means the cdr of the list is
 985      processed normally but the results are displayed using the face of
 986      the extent, and mouse clicks over this section are processed using
 987      the keymap of the extent. (In addition, if the extent has a
 988      help-echo property, that string will be echoed when the mouse
 989      moves over this section.) If extents are nested, all keymaps are
 990      properly consulted when processing mouse clicks, but multiple
 991      faces are not correctly merged (only the first face is used), and
 992      lists of faces are not correctly handled.
 993
 994    If you do alter `modeline-format' itself, the new value should use
 995 the same variables that appear in the default value (*note Modeline
 996 Variables::), rather than duplicating their contents or displaying the
 997 information in another fashion.  This way, customizations made by the
 998 user or by Lisp programs (such as `display-time' and major modes) via
 999 changes to those variables remain effective.
1000
1001    Here is an example of a `modeline-format' that might be useful for
1002 `shell-mode', since it contains the hostname and default directory.
1003
1004      (setq modeline-format
1005        (list ""
1006         'modeline-modified
1007         "%b--"
1008         (getenv "HOST")      ; One element is not constant.
1009         ":"
1010         'default-directory
1011         "   "
1012         'global-mode-string
1013         "   %[("
1014         'mode-name
1015         'modeline-process
1016         'minor-mode-alist
1017         "%n"
1018         ")%]----"
1019         '(line-number-mode "L%l--")
1020         '(-3 . "%p")
1021         "-%-"))
1022
1023 \1f
1024 File: lispref.info,  Node: Modeline Variables,  Next: %-Constructs,  Prev: Modeline Data,  Up: Modeline Format
1025
1026 Variables Used in the Modeline
1027 ------------------------------
1028
1029    This section describes variables incorporated by the standard value
1030 of `modeline-format' into the text of the mode line.  There is nothing
1031 inherently special about these variables; any other variables could
1032 have the same effects on the modeline if `modeline-format' were changed
1033 to use them.
1034
1035  - Variable: modeline-modified
1036      This variable holds the value of the modeline construct that
1037      displays whether the current buffer is modified.
1038
1039      The default value of `modeline-modified' is `("--%1*%1+-")'.  This
1040      means that the modeline displays `--**-' if the buffer is
1041      modified, `-----' if the buffer is not modified, `--%%-' if the
1042      buffer is read only, and `--%*--' if the buffer is read only and
1043      modified.
1044
1045      Changing this variable does not force an update of the modeline.
1046
1047  - Variable: modeline-buffer-identification
1048      This variable identifies the buffer being displayed in the window.
1049      Its default value is `("%F: %17b")', which means that it usually
1050      displays `Emacs:' followed by seventeen characters of the buffer
1051      name.  (In a terminal frame, it displays the frame name instead of
1052      `Emacs'; this has the effect of showing the frame number.)  You may
1053      want to change this in modes such as Rmail that do not behave like
1054      a "normal" XEmacs.
1055
1056  - Variable: global-mode-string
1057      This variable holds a modeline spec that appears in the mode line
1058      by default, just after the buffer name.  The command `display-time'
1059      sets `global-mode-string' to refer to the variable
1060      `display-time-string', which holds a string containing the time and
1061      load information.
1062
1063      The `%M' construct substitutes the value of `global-mode-string',
1064      but this is obsolete, since the variable is included directly in
1065      the modeline.
1066
1067  - Variable: mode-name
1068      This buffer-local variable holds the "pretty" name of the current
1069      buffer's major mode.  Each major mode should set this variable so
1070      that the mode name will appear in the modeline.
1071
1072  - Variable: minor-mode-alist
1073      This variable holds an association list whose elements specify how
1074      the modeline should indicate that a minor mode is active.  Each
1075      element of the `minor-mode-alist' should be a two-element list:
1076
1077           (MINOR-MODE-VARIABLE MODELINE-STRING)
1078
1079      More generally, MODELINE-STRING can be any mode line spec.  It
1080      appears in the mode line when the value of MINOR-MODE-VARIABLE is
1081      non-`nil', and not otherwise.  These strings should begin with
1082      spaces so that they don't run together.  Conventionally, the
1083      MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
1084      value when that minor mode is activated.
1085
1086      The default value of `minor-mode-alist' is:
1087
1088           minor-mode-alist
1089           => ((vc-mode vc-mode)
1090               (abbrev-mode " Abbrev")
1091               (overwrite-mode overwrite-mode)
1092               (auto-fill-function " Fill")
1093               (defining-kbd-macro " Def")
1094               (isearch-mode isearch-mode))
1095
1096      `minor-mode-alist' is not buffer-local.  The variables mentioned
1097      in the alist should be buffer-local if the minor mode can be
1098      enabled separately in each buffer.
1099
1100  - Variable: modeline-process
1101      This buffer-local variable contains the modeline information on
1102      process status in modes used for communicating with subprocesses.
1103      It is displayed immediately following the major mode name, with no
1104      intervening space.  For example, its value in the `*shell*' buffer
1105      is `(": %s")', which allows the shell to display its status along
1106      with the major mode as: `(Shell: run)'.  Normally this variable is
1107      `nil'.
1108
1109  - Variable: default-modeline-format
1110      This variable holds the default `modeline-format' for buffers that
1111      do not override it.  This is the same as `(default-value
1112      'modeline-format)'.
1113
1114      The default value of `default-modeline-format' is:
1115
1116           (""
1117            modeline-modified
1118            modeline-buffer-identification
1119            "   "
1120            global-mode-string
1121            "   %[("
1122            mode-name
1123            modeline-process
1124            minor-mode-alist
1125            "%n"
1126            ")%]----"
1127            (line-number-mode "L%l--")
1128            (-3 . "%p")
1129            "-%-")
1130
1131  - Variable: vc-mode
1132      The variable `vc-mode', local in each buffer, records whether the
1133      buffer's visited file is maintained with version control, and, if
1134      so, which kind.  Its value is `nil' for no version control, or a
1135      string that appears in the mode line.
1136