info/lispref.info-22

   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: Mode Help,  Next: Derived Modes,  Prev: Auto Major Mode,  Up: Major Modes
  54
  55 Getting Help about a Major Mode
  56 -------------------------------
  57
  58    The `describe-mode' function is used to provide information about
  59 major modes.  It is normally called with `C-h m'.  The `describe-mode'
  60 function uses the value of `major-mode', which is why every major mode
  61 function needs to set the `major-mode' variable.
  62
  63  - Command: describe-mode
  64      This function displays the documentation of the current major mode.
  65
  66      The `describe-mode' function calls the `documentation' function
  67      using the value of `major-mode' as an argument.  Thus, it displays
  68      the documentation string of the major mode function.  (*Note
  69      Accessing Documentation::.)
  70
  71  - Variable: major-mode
  72      This variable holds the symbol for the current buffer's major mode.
  73      This symbol should have a function definition that is the command
  74      to switch to that major mode.  The `describe-mode' function uses
  75      the documentation string of the function as the documentation of
  76      the major mode.
  77
  78 \1f
  79 File: lispref.info,  Node: Derived Modes,  Prev: Mode Help,  Up: Major Modes
  80
  81 Defining Derived Modes
  82 ----------------------
  83
  84    It's often useful to define a new major mode in terms of an existing
  85 one.  An easy way to do this is to use `define-derived-mode'.
  86
  87  - Macro: define-derived-mode variant parent name docstring body...
  88      This construct defines VARIANT as a major mode command, using NAME
  89      as the string form of the mode name.
  90
  91      The new command VARIANT is defined to call the function PARENT,
  92      then override certain aspects of that parent mode:
  93
  94         * The new mode has its own keymap, named `VARIANT-map'.
  95           `define-derived-mode' initializes this map to inherit from
  96           `PARENT-map', if it is not already set.
  97
  98         * The new mode has its own syntax table, kept in the variable
  99           `VARIANT-syntax-table'.  `define-derived-mode' initializes
 100           this variable by copying `PARENT-syntax-table', if it is not
 101           already set.
 102
 103         * The new mode has its own abbrev table, kept in the variable
 104           `VARIANT-abbrev-table'.  `define-derived-mode' initializes
 105           this variable by copying `PARENT-abbrev-table', if it is not
 106           already set.
 107
 108         * The new mode has its own mode hook, `VARIANT-hook', which it
 109           runs in standard fashion as the very last thing that it does.
 110           (The new mode also runs the mode hook of PARENT as part of
 111           calling PARENT.)
 112
 113      In addition, you can specify how to override other aspects of
 114      PARENT with BODY.  The command VARIANT evaluates the forms in BODY
 115      after setting up all its usual overrides, just before running
 116      `VARIANT-hook'.
 117
 118      The argument DOCSTRING specifies the documentation string for the
 119      new mode.  If you omit DOCSTRING, `define-derived-mode' generates
 120      a documentation string.
 121
 122      Here is a hypothetical example:
 123
 124           (define-derived-mode hypertext-mode
 125             text-mode "Hypertext"
 126             "Major mode for hypertext.
 127           \\{hypertext-mode-map}"
 128             (setq case-fold-search nil))
 129
 130           (define-key hypertext-mode-map
 131             [down-mouse-3] 'do-hyper-link)
 132
 133 \1f
 134 File: lispref.info,  Node: Minor Modes,  Next: Modeline Format,  Prev: Major Modes,  Up: Modes
 135
 136 Minor Modes
 137 ===========
 138
 139    A "minor mode" provides features that users may enable or disable
 140 independently of the choice of major mode.  Minor modes can be enabled
 141 individually or in combination.  Minor modes would be better named
 142 "Generally available, optional feature modes" except that such a name is
 143 unwieldy.
 144
 145    A minor mode is not usually a modification of single major mode.  For
 146 example, Auto Fill mode may be used in any major mode that permits text
 147 insertion.  To be general, a minor mode must be effectively independent
 148 of the things major modes do.
 149
 150    A minor mode is often much more difficult to implement than a major
 151 mode.  One reason is that you should be able to activate and deactivate
 152 minor modes in any order.  A minor mode should be able to have its
 153 desired effect regardless of the major mode and regardless of the other
 154 minor modes in effect.
 155
 156    Often the biggest problem in implementing a minor mode is finding a
 157 way to insert the necessary hook into the rest of XEmacs.  Minor mode
 158 keymaps make this easier than it used to be.
 159
 160 * Menu:
 161
 162 * Minor Mode Conventions::      Tips for writing a minor mode.
 163 * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
 164
 165 \1f
 166 File: lispref.info,  Node: Minor Mode Conventions,  Next: Keymaps and Minor Modes,  Up: Minor Modes
 167
 168 Conventions for Writing Minor Modes
 169 -----------------------------------
 170
 171    There are conventions for writing minor modes just as there are for
 172 major modes.  Several of the major mode conventions apply to minor
 173 modes as well: those regarding the name of the mode initialization
 174 function, the names of global symbols, and the use of keymaps and other
 175 tables.
 176
 177    In addition, there are several conventions that are specific to
 178 minor modes.
 179
 180    * Make a variable whose name ends in `-mode' to represent the minor
 181      mode.  Its value should enable or disable the mode (`nil' to
 182      disable; anything else to enable.)  We call this the "mode
 183      variable".
 184
 185      This variable is used in conjunction with the `minor-mode-alist' to
 186      display the minor mode name in the modeline.  It can also enable
 187      or disable a minor mode keymap.  Individual commands or hooks can
 188      also check the variable's value.
 189
 190      If you want the minor mode to be enabled separately in each buffer,
 191      make the variable buffer-local.
 192
 193    * Define a command whose name is the same as the mode variable.  Its
 194      job is to enable and disable the mode by setting the variable.
 195
 196      The command should accept one optional argument.  If the argument
 197      is `nil', it should toggle the mode (turn it on if it is off, and
 198      off if it is on).  Otherwise, it should turn the mode on if the
 199      argument is a positive integer, a symbol other than `nil' or `-',
 200      or a list whose CAR is such an integer or symbol; it should turn
 201      the mode off otherwise.
 202
 203      Here is an example taken from the definition of
 204      `transient-mark-mode'.  It shows the use of `transient-mark-mode'
 205      as a variable that enables or disables the mode's behavior, and
 206      also shows the proper way to toggle, enable or disable the minor
 207      mode based on the raw prefix argument value.
 208
 209           (setq transient-mark-mode
 210                 (if (null arg) (not transient-mark-mode)
 211                   (> (prefix-numeric-value arg) 0)))
 212
 213    * Add an element to `minor-mode-alist' for each minor mode (*note
 214      Modeline Variables::).  This element should be a list of the
 215      following form:
 216
 217           (MODE-VARIABLE STRING)
 218
 219      Here MODE-VARIABLE is the variable that controls enabling of the
 220      minor mode, and STRING is a short string, starting with a space,
 221      to represent the mode in the modeline.  These strings must be
 222      short so that there is room for several of them at once.
 223
 224      When you add an element to `minor-mode-alist', use `assq' to check
 225      for an existing element, to avoid duplication.  For example:
 226
 227           (or (assq 'leif-mode minor-mode-alist)
 228               (setq minor-mode-alist
 229                     (cons '(leif-mode " Leif") minor-mode-alist)))
 230
 231 \1f
 232 File: lispref.info,  Node: Keymaps and Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes
 233
 234 Keymaps and Minor Modes
 235 -----------------------
 236
 237    Each minor mode can have its own keymap, which is active when the
 238 mode is enabled.  To set up a keymap for a minor mode, add an element
 239 to the alist `minor-mode-map-alist'.  *Note Active Keymaps::.
 240
 241    One use of minor mode keymaps is to modify the behavior of certain
 242 self-inserting characters so that they do something else as well as
 243 self-insert.  In general, this is the only way to do that, since the
 244 facilities for customizing `self-insert-command' are limited to special
 245 cases (designed for abbrevs and Auto Fill mode).  (Do not try
 246 substituting your own definition of `self-insert-command' for the
 247 standard one.  The editor command loop handles this function specially.)
 248
 249 \1f
 250 File: lispref.info,  Node: Modeline Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes
 251
 252 Modeline Format
 253 ===============
 254
 255    Each Emacs window (aside from minibuffer windows) includes a
 256 modeline, which displays status information about the buffer displayed
 257 in the window.  The modeline contains information about the buffer,
 258 such as its name, associated file, depth of recursive editing, and the
 259 major and minor modes.
 260
 261    This section describes how the contents of the modeline are
 262 controlled.  It is in the chapter on modes because much of the
 263 information displayed in the modeline relates to the enabled major and
 264 minor modes.
 265
 266    `modeline-format' is a buffer-local variable that holds a template
 267 used to display the modeline of the current buffer.  All windows for
 268 the same buffer use the same `modeline-format' and their modelines
 269 appear the same (except for scrolling percentages and line numbers).
 270
 271    The modeline of a window is normally updated whenever a different
 272 buffer is shown in the window, or when the buffer's modified-status
 273 changes from `nil' to `t' or vice-versa.  If you modify any of the
 274 variables referenced by `modeline-format' (*note Modeline Variables::),
 275 you may want to force an update of the modeline so as to display the
 276 new information.
 277
 278  - Function: redraw-modeline &optional all
 279      Force redisplay of the current buffer's modeline.  If ALL is
 280      non-`nil', then force redisplay of all modelines.
 281
 282    The modeline is usually displayed in inverse video.  This is
 283 controlled using the `modeline' face.  *Note Faces::.
 284
 285 * Menu:
 286
 287 * Modeline Data::         The data structure that controls the modeline.
 288 * Modeline Variables::    Variables used in that data structure.
 289 * %-Constructs::          Putting information into a modeline.
 290
 291 \1f
 292 File: lispref.info,  Node: Modeline Data,  Next: Modeline Variables,  Up: Modeline Format
 293
 294 The Data Structure of the Modeline
 295 ----------------------------------
 296
 297    The modeline contents are controlled by a data structure of lists,
 298 strings, symbols, and numbers kept in the buffer-local variable
 299 `modeline-format'.  The data structure is called a "modeline
 300 construct", and it is built in recursive fashion out of simpler modeline
 301 constructs.  The same data structure is used for constructing frame
 302 titles (*note Frame Titles::).
 303
 304  - Variable: modeline-format
 305      The value of this variable is a modeline construct with overall
 306      responsibility for the modeline format.  The value of this variable
 307      controls which other variables are used to form the modeline text,
 308      and where they appear.
 309
 310    A modeline construct may be as simple as a fixed string of text, but
 311 it usually specifies how to use other variables to construct the text.
 312 Many of these variables are themselves defined to have modeline
 313 constructs as their values.
 314
 315    The default value of `modeline-format' incorporates the values of
 316 variables such as `mode-name' and `minor-mode-alist'.  Because of this,
 317 very few modes need to alter `modeline-format'.  For most purposes, it
 318 is sufficient to alter the variables referenced by `modeline-format'.
 319
 320    A modeline construct may be a string, symbol, glyph, generic
 321 specifier, list or cons cell.
 322
 323 `STRING'
 324      A string as a modeline construct is displayed verbatim in the mode
 325      line except for "`%'-constructs".  Decimal digits after the `%'
 326      specify the field width for space filling on the right (i.e., the
 327      data is left justified).  *Note %-Constructs::.
 328
 329 `SYMBOL'
 330      A symbol as a modeline construct stands for its value.  The value
 331      of SYMBOL is processed as a modeline construct, in place of
 332      SYMBOL.  However, the symbols `t' and `nil' are ignored; so is any
 333      symbol whose value is void.
 334
 335      There is one exception: if the value of SYMBOL is a string, it is
 336      displayed verbatim: the `%'-constructs are not recognized.
 337
 338 `GLYPH'
 339      A glyph is displayed as is.
 340
 341 `GENERIC-SPECIFIER'
 342      A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands
 343      for its instance.  The instance of GENERIC-SPECIFIER is computed
 344      in the current window using the equivalent of `specifier-instance'
 345      and the value is processed.
 346
 347 `(STRING REST...) or (LIST REST...)'
 348      A list whose first element is a string or list means to process
 349      all the elements recursively and concatenate the results.  This is
 350      the most common form of mode line construct.
 351
 352 `(SYMBOL THEN ELSE)'
 353      A list whose first element is a symbol is a conditional.  Its
 354      meaning depends on the value of SYMBOL.  If the value is non-`nil',
 355      the second element, THEN, is processed recursively as a modeline
 356      element.  But if the value of SYMBOL is `nil', the third element,
 357      ELSE, is processed recursively.  You may omit ELSE; then the mode
 358      line element displays nothing if the value of SYMBOL is `nil'.
 359
 360 `(WIDTH REST...)'
 361      A list whose first element is an integer specifies truncation or
 362      padding of the results of REST.  The remaining elements REST are
 363      processed recursively as modeline constructs and concatenated
 364      together.  Then the result is space filled (if WIDTH is positive)
 365      or truncated (to -WIDTH columns, if WIDTH is negative) on the
 366      right.
 367
 368      For example, the usual way to show what percentage of a buffer is
 369      above the top of the window is to use a list like this: `(-3
 370      "%p")'.
 371
 372 `(EXTENT REST...)'
 373      A list whose car is an extent means the cdr of the list is
 374      processed normally but the results are displayed using the face of
 375      the extent, and mouse clicks over this section are processed using
 376      the keymap of the extent. (In addition, if the extent has a
 377      help-echo property, that string will be echoed when the mouse
 378      moves over this section.) If extents are nested, all keymaps are
 379      properly consulted when processing mouse clicks, but multiple
 380      faces are not correctly merged (only the first face is used), and
 381      lists of faces are not correctly handled.
 382
 383    If you do alter `modeline-format' itself, the new value should use
 384 the same variables that appear in the default value (*note Modeline
 385 Variables::), rather than duplicating their contents or displaying the
 386 information in another fashion.  This way, customizations made by the
 387 user or by Lisp programs (such as `display-time' and major modes) via
 388 changes to those variables remain effective.
 389
 390    Here is an example of a `modeline-format' that might be useful for
 391 `shell-mode', since it contains the hostname and default directory.
 392
 393      (setq modeline-format
 394        (list ""
 395         'modeline-modified
 396         "%b--"
 397         (getenv "HOST")      ; One element is not constant.
 398         ":"
 399         'default-directory
 400         "   "
 401         'global-mode-string
 402         "   %[("
 403         'mode-name
 404         'modeline-process
 405         'minor-mode-alist
 406         "%n"
 407         ")%]----"
 408         '(line-number-mode "L%l--")
 409         '(-3 . "%p")
 410         "-%-"))
 411
 412 \1f
 413 File: lispref.info,  Node: Modeline Variables,  Next: %-Constructs,  Prev: Modeline Data,  Up: Modeline Format
 414
 415 Variables Used in the Modeline
 416 ------------------------------
 417
 418    This section describes variables incorporated by the standard value
 419 of `modeline-format' into the text of the mode line.  There is nothing
 420 inherently special about these variables; any other variables could
 421 have the same effects on the modeline if `modeline-format' were changed
 422 to use them.
 423
 424  - Variable: modeline-modified
 425      This variable holds the value of the modeline construct that
 426      displays whether the current buffer is modified.
 427
 428      The default value of `modeline-modified' is `("--%1*%1+-")'.  This
 429      means that the modeline displays `--**-' if the buffer is
 430      modified, `-----' if the buffer is not modified, `--%%-' if the
 431      buffer is read only, and `--%*--' if the buffer is read only and
 432      modified.
 433
 434      Changing this variable does not force an update of the modeline.
 435
 436  - Variable: modeline-buffer-identification
 437      This variable identifies the buffer being displayed in the window.
 438      Its default value is `("%F: %17b")', which means that it usually
 439      displays `Emacs:' followed by seventeen characters of the buffer
 440      name.  (In a terminal frame, it displays the frame name instead of
 441      `Emacs'; this has the effect of showing the frame number.)  You may
 442      want to change this in modes such as Rmail that do not behave like
 443      a "normal" XEmacs.
 444
 445  - Variable: global-mode-string
 446      This variable holds a modeline spec that appears in the mode line
 447      by default, just after the buffer name.  The command `display-time'
 448      sets `global-mode-string' to refer to the variable
 449      `display-time-string', which holds a string containing the time and
 450      load information.
 451
 452      The `%M' construct substitutes the value of `global-mode-string',
 453      but this is obsolete, since the variable is included directly in
 454      the modeline.
 455
 456  - Variable: mode-name
 457      This buffer-local variable holds the "pretty" name of the current
 458      buffer's major mode.  Each major mode should set this variable so
 459      that the mode name will appear in the modeline.
 460
 461  - Variable: minor-mode-alist
 462      This variable holds an association list whose elements specify how
 463      the modeline should indicate that a minor mode is active.  Each
 464      element of the `minor-mode-alist' should be a two-element list:
 465
 466           (MINOR-MODE-VARIABLE MODELINE-STRING)
 467
 468      More generally, MODELINE-STRING can be any mode line spec.  It
 469      appears in the mode line when the value of MINOR-MODE-VARIABLE is
 470      non-`nil', and not otherwise.  These strings should begin with
 471      spaces so that they don't run together.  Conventionally, the
 472      MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
 473      value when that minor mode is activated.
 474
 475      The default value of `minor-mode-alist' is:
 476
 477           minor-mode-alist
 478           => ((vc-mode vc-mode)
 479               (abbrev-mode " Abbrev")
 480               (overwrite-mode overwrite-mode)
 481               (auto-fill-function " Fill")
 482               (defining-kbd-macro " Def")
 483               (isearch-mode isearch-mode))
 484
 485      `minor-mode-alist' is not buffer-local.  The variables mentioned
 486      in the alist should be buffer-local if the minor mode can be
 487      enabled separately in each buffer.
 488
 489  - Variable: modeline-process
 490      This buffer-local variable contains the modeline information on
 491      process status in modes used for communicating with subprocesses.
 492      It is displayed immediately following the major mode name, with no
 493      intervening space.  For example, its value in the `*shell*' buffer
 494      is `(": %s")', which allows the shell to display its status along
 495      with the major mode as: `(Shell: run)'.  Normally this variable is
 496      `nil'.
 497
 498  - Variable: default-modeline-format
 499      This variable holds the default `modeline-format' for buffers that
 500      do not override it.  This is the same as `(default-value
 501      'modeline-format)'.
 502
 503      The default value of `default-modeline-format' is:
 504
 505           (""
 506            modeline-modified
 507            modeline-buffer-identification
 508            "   "
 509            global-mode-string
 510            "   %[("
 511            mode-name
 512            modeline-process
 513            minor-mode-alist
 514            "%n"
 515            ")%]----"
 516            (line-number-mode "L%l--")
 517            (-3 . "%p")
 518            "-%-")
 519
 520  - Variable: vc-mode
 521      The variable `vc-mode', local in each buffer, records whether the
 522      buffer's visited file is maintained with version control, and, if
 523      so, which kind.  Its value is `nil' for no version control, or a
 524      string that appears in the mode line.
 525
 526 \1f
 527 File: lispref.info,  Node: %-Constructs,  Prev: Modeline Variables,  Up: Modeline Format
 528
 529 `%'-Constructs in the ModeLine
 530 ------------------------------
 531
 532    The following table lists the recognized `%'-constructs and what
 533 they mean.  In any construct except `%%', you can add a decimal integer
 534 after the `%' to specify how many characters to display.
 535
 536 `%b'
 537      The current buffer name, obtained with the `buffer-name' function.
 538      *Note Buffer Names::.
 539
 540 `%f'
 541      The visited file name, obtained with the `buffer-file-name'
 542      function.  *Note Buffer File Name::.
 543
 544 `%F'
 545      The name of the selected frame.
 546
 547 `%c'
 548      The current column number of point.
 549
 550 `%l'
 551      The current line number of point.
 552
 553 `%*'
 554      `%' if the buffer is read only (see `buffer-read-only');
 555      `*' if the buffer is modified (see `buffer-modified-p');
 556      `-' otherwise.  *Note Buffer Modification::.
 557
 558 `%+'
 559      `*' if the buffer is modified (see `buffer-modified-p');
 560      `%' if the buffer is read only (see `buffer-read-only');
 561      `-' otherwise.  This differs from `%*' only for a modified
 562      read-only buffer.  *Note Buffer Modification::.
 563
 564 `%&'
 565      `*' if the buffer is modified, and `-' otherwise.
 566
 567 `%s'
 568      The status of the subprocess belonging to the current buffer,
 569      obtained with `process-status'.  *Note Process Information::.
 570
 571 `%l'
 572      The current line number.
 573
 574 `%S'
 575      The name of the selected frame; this is only meaningful under the
 576      X Window System.  *Note Frame Name::.
 577
 578 `%t'
 579      Whether the visited file is a text file or a binary file.  (This
 580      is a meaningful distinction only on certain operating systems.)
 581
 582 `%p'
 583      The percentage of the buffer text above the *top* of window, or
 584      `Top', `Bottom' or `All'.
 585
 586 `%P'
 587      The percentage of the buffer text that is above the *bottom* of
 588      the window (which includes the text visible in the window, as well
 589      as the text above the top), plus `Top' if the top of the buffer is
 590      visible on screen; or `Bottom' or `All'.
 591
 592 `%n'
 593      `Narrow' when narrowing is in effect; nothing otherwise (see
 594      `narrow-to-region' in *Note Narrowing::).
 595
 596 `%C'
 597      Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.
 598
 599 `%['
 600      An indication of the depth of recursive editing levels (not
 601      counting minibuffer levels): one `[' for each editing level.
 602      *Note Recursive Editing::.
 603
 604 `%]'
 605      One `]' for each recursive editing level (not counting minibuffer
 606      levels).
 607
 608 `%%'
 609      The character `%'--this is how to include a literal `%' in a
 610      string in which `%'-constructs are allowed.
 611
 612 `%-'
 613      Dashes sufficient to fill the remainder of the modeline.
 614
 615    The following two `%'-constructs are still supported, but they are
 616 obsolete, since you can get the same results with the variables
 617 `mode-name' and `global-mode-string'.
 618
 619 `%m'
 620      The value of `mode-name'.
 621
 622 `%M'
 623      The value of `global-mode-string'.  Currently, only `display-time'
 624      modifies the value of `global-mode-string'.
 625
 626 \1f
 627 File: lispref.info,  Node: Hooks,  Prev: Modeline Format,  Up: Modes
 628
 629 Hooks
 630 =====
 631
 632    A "hook" is a variable where you can store a function or functions
 633 to be called on a particular occasion by an existing program.  XEmacs
 634 provides hooks for the sake of customization.  Most often, hooks are set
 635 up in the `.emacs' file, but Lisp programs can set them also.  *Note
 636 Standard Hooks::, for a list of standard hook variables.
 637
 638    Most of the hooks in XEmacs are "normal hooks".  These variables
 639 contain lists of functions to be called with no arguments.  The reason
 640 most hooks are normal hooks is so that you can use them in a uniform
 641 way.  You can usually tell when a hook is a normal hook, because its
 642 name ends in `-hook'.
 643
 644    The recommended way to add a hook function to a normal hook is by
 645 calling `add-hook' (see below).  The hook functions may be any of the
 646 valid kinds of functions that `funcall' accepts (*note What Is a
 647 Function::).  Most normal hook variables are initially void; `add-hook'
 648 knows how to deal with this.
 649
 650    As for abnormal hooks, those whose names end in `-function' have a
 651 value that is a single function.  Those whose names end in `-hooks'
 652 have a value that is a list of functions.  Any hook that is abnormal is
 653 abnormal because a normal hook won't do the job; either the functions
 654 are called with arguments, or their values are meaningful.  The name
 655 shows you that the hook is abnormal and that you should look at its
 656 documentation string to see how to use it properly.
 657
 658    Major mode functions are supposed to run a hook called the "mode
 659 hook" as the last step of initialization.  This makes it easy for a user
 660 to customize the behavior of the mode, by overriding the local variable
 661 assignments already made by the mode.  But hooks are used in other
 662 contexts too.  For example, the hook `suspend-hook' runs just before
 663 XEmacs suspends itself (*note Suspending XEmacs::).
 664
 665    Here's an expression that uses a mode hook to turn on Auto Fill mode
 666 when in Lisp Interaction mode:
 667
 668      (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
 669
 670    The next example shows how to use a hook to customize the way XEmacs
 671 formats C code.  (People often have strong personal preferences for one
 672 format or another.)  Here the hook function is an anonymous lambda
 673 expression.
 674
 675      (add-hook 'c-mode-hook
 676        (function (lambda ()
 677                    (setq c-indent-level 4
 678                          c-argdecl-indent 0
 679                          c-label-offset -4
 680                          c-continued-statement-indent 0
 681                          c-brace-offset 0
 682                          comment-column 40))))
 683
 684      (setq c++-mode-hook c-mode-hook)
 685
 686    The final example shows how the appearance of the modeline can be
 687 modified for a particular class of buffers only.
 688
 689      (add-hook 'text-mode-hook
 690        (function (lambda ()
 691                    (setq modeline-format
 692                          '(modeline-modified
 693                            "Emacs: %14b"
 694                            "  "
 695                            default-directory
 696                            " "
 697                            global-mode-string
 698                            "%[("
 699                            mode-name
 700                            minor-mode-alist
 701                            "%n"
 702                            modeline-process
 703                            ") %]---"
 704                            (-3 . "%p")
 705                            "-%-")))))
 706
 707    At the appropriate time, XEmacs uses the `run-hooks' function to run
 708 particular hooks.  This function calls the hook functions you have
 709 added with `add-hooks'.
 710
 711  - Function: run-hooks &rest hookvar
 712      This function takes one or more hook variable names as arguments,
 713      and runs each hook in turn.  Each HOOKVAR argument should be a
 714      symbol that is a hook variable.  These arguments are processed in
 715      the order specified.
 716
 717      If a hook variable has a non-`nil' value, that value may be a
 718      function or a list of functions.  If the value is a function
 719      (either a lambda expression or a symbol with a function
 720      definition), it is called.  If it is a list, the elements are
 721      called, in order.  The hook functions are called with no arguments.
 722
 723      For example, here's how `emacs-lisp-mode' runs its mode hook:
 724
 725           (run-hooks 'emacs-lisp-mode-hook)
 726
 727  - Function: add-hook hook function &optional append local
 728      This function is the handy way to add function FUNCTION to hook
 729      variable HOOK.  The argument FUNCTION may be any valid Lisp
 730      function with the proper number of arguments.  For example,
 731
 732           (add-hook 'text-mode-hook 'my-text-hook-function)
 733
 734      adds `my-text-hook-function' to the hook called `text-mode-hook'.
 735
 736      You can use `add-hook' for abnormal hooks as well as for normal
 737      hooks.
 738
 739      It is best to design your hook functions so that the order in
 740      which they are executed does not matter.  Any dependence on the
 741      order is "asking for trouble."  However, the order is predictable:
 742      normally, FUNCTION goes at the front of the hook list, so it will
 743      be executed first (barring another `add-hook' call).
 744
 745      If the optional argument APPEND is non-`nil', the new hook
 746      function goes at the end of the hook list and will be executed
 747      last.
 748
 749      If LOCAL is non-`nil', that says to make the new hook function
 750      local to the current buffer.  Before you can do this, you must
 751      make the hook itself buffer-local by calling `make-local-hook'
 752      (*not* `make-local-variable').  If the hook itself is not
 753      buffer-local, then the value of LOCAL makes no difference--the
 754      hook function is always global.
 755
 756  - Function: remove-hook hook function &optional local
 757      This function removes FUNCTION from the hook variable HOOK.
 758
 759      If LOCAL is non-`nil', that says to remove FUNCTION from the local
 760      hook list instead of from the global hook list.  If the hook
 761      itself is not buffer-local, then the value of LOCAL makes no
 762      difference.
 763
 764  - Function: make-local-hook hook
 765      This function makes the hook variable HOOK local to the current
 766      buffer.  When a hook variable is local, it can have local and
 767      global hook functions, and `run-hooks' runs all of them.
 768
 769      This function works by making `t' an element of the buffer-local
 770      value.  That serves as a flag to use the hook functions in the
 771      default value of the hook variable as well as those in the local
 772      value.  Since `run-hooks' understands this flag, `make-local-hook'
 773      works with all normal hooks.  It works for only some non-normal
 774      hooks--those whose callers have been updated to understand this
 775      meaning of `t'.
 776
 777      Do not use `make-local-variable' directly for hook variables; it is
 778      not sufficient.
 779
 780 \1f
 781 File: lispref.info,  Node: Documentation,  Next: Files,  Prev: Modes,  Up: Top
 782
 783 Documentation
 784 *************
 785
 786    XEmacs Lisp has convenient on-line help facilities, most of which
 787 derive their information from the documentation strings associated with
 788 functions and variables.  This chapter describes how to write good
 789 documentation strings for your Lisp programs, as well as how to write
 790 programs to access documentation.
 791
 792    Note that the documentation strings for XEmacs are not the same thing
 793 as the XEmacs manual.  Manuals have their own source files, written in
 794 the Texinfo language; documentation strings are specified in the
 795 definitions of the functions and variables they apply to.  A collection
 796 of documentation strings is not sufficient as a manual because a good
 797 manual is not organized in that fashion; it is organized in terms of
 798 topics of discussion.
 799
 800 * Menu:
 801
 802 * Documentation Basics::      Good style for doc strings.
 803                                 Where to put them.  How XEmacs stores them.
 804 * Accessing Documentation::   How Lisp programs can access doc strings.
 805 * Keys in Documentation::     Substituting current key bindings.
 806 * Describing Characters::     Making printable descriptions of
 807                                 non-printing characters and key sequences.
 808 * Help Functions::            Subroutines used by XEmacs help facilities.
 809 * Obsoleteness::              Upgrading Lisp functionality over time.
 810
 811 \1f
 812 File: lispref.info,  Node: Documentation Basics,  Next: Accessing Documentation,  Up: Documentation
 813
 814 Documentation Basics
 815 ====================
 816
 817    A documentation string is written using the Lisp syntax for strings,
 818 with double-quote characters surrounding the text of the string.  This
 819 is because it really is a Lisp string object.  The string serves as
 820 documentation when it is written in the proper place in the definition
 821 of a function or variable.  In a function definition, the documentation
 822 string follows the argument list.  In a variable definition, the
 823 documentation string follows the initial value of the variable.
 824
 825    When you write a documentation string, make the first line a complete
 826 sentence (or two complete sentences) since some commands, such as
 827 `apropos', show only the first line of a multi-line documentation
 828 string.  Also, you should not indent the second line of a documentation
 829 string, if you have one, because that looks odd when you use `C-h f'
 830 (`describe-function') or `C-h v' (`describe-variable').  *Note
 831 Documentation Tips::.
 832
 833    Documentation strings may contain several special substrings, which
 834 stand for key bindings to be looked up in the current keymaps when the
 835 documentation is displayed.  This allows documentation strings to refer
 836 to the keys for related commands and be accurate even when a user
 837 rearranges the key bindings.  (*Note Accessing Documentation::.)
 838
 839    Within the Lisp world, a documentation string is accessible through
 840 the function or variable that it describes:
 841
 842    * The documentation for a function is stored in the function
 843      definition itself (*note Lambda Expressions::).  The function
 844      `documentation' knows how to extract it.
 845
 846    * The documentation for a variable is stored in the variable's
 847      property list under the property name `variable-documentation'.
 848      The function `documentation-property' knows how to extract it.
 849
 850    To save space, the documentation for preloaded functions and
 851 variables (including primitive functions and autoloaded functions) is
 852 stored in the "internal doc file" `DOC'.  The documentation for
 853 functions and variables loaded during the XEmacs session from
 854 byte-compiled files is stored in those very same byte-compiled files
 855 (*note Docs and Compilation::).
 856
 857    XEmacs does not keep documentation strings in memory unless
 858 necessary.  Instead, XEmacs maintains, for preloaded symbols, an
 859 integer offset into the internal doc file, and for symbols loaded from
 860 byte-compiled files, a list containing the filename of the
 861 byte-compiled file and an integer offset, in place of the documentation
 862 string.  The functions `documentation' and `documentation-property' use
 863 that information to read the documentation from the appropriate file;
 864 this is transparent to the user.
 865
 866    For information on the uses of documentation strings, see *Note
 867 Help: (emacs)Help.
 868
 869    The `emacs/lib-src' directory contains two utilities that you can
 870 use to print nice-looking hardcopy for the file
 871 `emacs/etc/DOC-VERSION'.  These are `sorted-doc.c' and `digest-doc.c'.
 872
 873 \1f
 874 File: lispref.info,  Node: Accessing Documentation,  Next: Keys in Documentation,  Prev: Documentation Basics,  Up: Documentation
 875
 876 Access to Documentation Strings
 877 ===============================
 878
 879  - Function: documentation-property symbol property &optional verbatim
 880      This function returns the documentation string that is recorded in
 881      SYMBOL's property list under property PROPERTY.  It retrieves the
 882      text from a file if necessary, and runs `substitute-command-keys'
 883      to substitute actual key bindings.  (This substitution is not done
 884      if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
 885      Emacs 19.)
 886
 887           (documentation-property 'command-line-processed
 888              'variable-documentation)
 889                => "t once command line has been processed"
 890           (symbol-plist 'command-line-processed)
 891                => (variable-documentation 188902)
 892
 893  - Function: documentation function &optional verbatim
 894      This function returns the documentation string of FUNCTION.  It
 895      reads the text from a file if necessary.  Then (unless VERBATIM is
 896      non-`nil') it calls `substitute-command-keys', to return a value
 897      containing the actual (current) key bindings.
 898
 899      The function `documentation' signals a `void-function' error if
 900      FUNCTION has no function definition.  However, it is ok if the
 901      function definition has no documentation string.  In that case,
 902      `documentation' returns `nil'.
 903
 904    Here is an example of using the two functions, `documentation' and
 905 `documentation-property', to display the documentation strings for
 906 several symbols in a `*Help*' buffer.
 907
 908      (defun describe-symbols (pattern)
 909        "Describe the XEmacs Lisp symbols matching PATTERN.
 910      All symbols that have PATTERN in their name are described
 911      in the `*Help*' buffer."
 912        (interactive "sDescribe symbols matching: ")
 913        (let ((describe-func
 914               (function
 915                (lambda (s)
 916                  ;; Print description of symbol.
 917                  (if (fboundp s)             ; It is a function.
 918                      (princ
 919                       (format "%s\t%s\n%s\n\n" s
 920                         (if (commandp s)
 921                             (let ((keys (where-is-internal s)))
 922                               (if keys
 923                                   (concat
 924                                    "Keys: "
 925                                    (mapconcat 'key-description
 926                                               keys " "))
 927                                 "Keys: none"))
 928                           "Function")
 929                         (or (documentation s)
 930                             "not documented"))))
 931
 932                  (if (boundp s)              ; It is a variable.
 933                      (princ
 934                       (format "%s\t%s\n%s\n\n" s
 935                         (if (user-variable-p s)
 936                             "Option " "Variable")
 937                         (or (documentation-property
 938                               s 'variable-documentation)
 939                             "not documented")))))))
 940              sym-list)
 941
 942          ;; Build a list of symbols that match pattern.
 943          (mapatoms (function
 944                     (lambda (sym)
 945                       (if (string-match pattern (symbol-name sym))
 946                           (setq sym-list (cons sym sym-list))))))
 947
 948          ;; Display the data.
 949          (with-output-to-temp-buffer "*Help*"
 950            (mapcar describe-func (sort sym-list 'string<))
 951            (print-help-return-message))))
 952
 953    The `describe-symbols' function works like `apropos', but provides
 954 more information.
 955
 956      (describe-symbols "goal")
 957
 958      ---------- Buffer: *Help* ----------
 959      goal-column     Option
 960      *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
 961
 962      set-goal-column Command: C-x C-n
 963      Set the current horizontal position as a goal for C-n and C-p.
 964      Those commands will move to this position in the line moved to
 965      rather than trying to keep the same horizontal position.
 966      With a non-`nil' argument, clears out the goal column
 967      so that C-n and C-p resume vertical motion.
 968      The goal column is stored in the variable `goal-column'.
 969
 970      temporary-goal-column   Variable
 971      Current goal column for vertical motion.
 972      It is the column where point was
 973      at the start of current run of vertical motion commands.
 974      When the `track-eol' feature is doing its job, the value is 9999.
 975      ---------- Buffer: *Help* ----------
 976
 977  - Function: Snarf-documentation filename
 978      This function is used only during XEmacs initialization, just
 979      before the runnable XEmacs is dumped.  It finds the file offsets
 980      of the documentation strings stored in the file FILENAME, and
 981      records them in the in-core function definitions and variable
 982      property lists in place of the actual strings.  *Note Building
 983      XEmacs::.
 984
 985      XEmacs finds the file FILENAME in the `lib-src' directory.  When
 986      the dumped XEmacs is later executed, the same file is found in the
 987      directory `doc-directory'.  The usual value for FILENAME is `DOC',
 988      but this can be changed by modifying the variable
 989      `internal-doc-file-name'.
 990
 991  - Variable: internal-doc-file-name
 992      This variable holds the name of the file containing documentation
 993      strings of built-in symbols, usually `DOC'.  The full pathname of
 994      the internal doc file is `(concat doc-directory
 995      internal-doc-file-name)'.
 996
 997  - Variable: doc-directory
 998      This variable holds the name of the directory which contains the
 999      "internal doc file" that contains documentation strings for
1000      built-in and preloaded functions and variables.
1001
1002      In most cases, this is the same as `exec-directory'.  They may be
1003      different when you run XEmacs from the directory where you built
1004      it, without actually installing it.  See `exec-directory' in *Note
1005      Help Functions::.
1006
1007      In older Emacs versions, `exec-directory' was used for this.
1008
1009  - Variable: data-directory
1010      This variable holds the name of the directory in which XEmacs finds
1011      certain system independent documentation and text files that come
1012      with XEmacs.  In older Emacs versions, `exec-directory' was used
1013      for this.
1014
1015 \1f
1016 File: lispref.info,  Node: Keys in Documentation,  Next: Describing Characters,  Prev: Accessing Documentation,  Up: Documentation
1017
1018 Substituting Key Bindings in Documentation
1019 ==========================================
1020
1021    When documentation strings refer to key sequences, they should use
1022 the current, actual key bindings.  They can do so using certain special
1023 text sequences described below.  Accessing documentation strings in the
1024 usual way substitutes current key binding information for these special
1025 sequences.  This works by calling `substitute-command-keys'.  You can
1026 also call that function yourself.
1027
1028    Here is a list of the special sequences and what they mean:
1029
1030 `\[COMMAND]'
1031      stands for a key sequence that will invoke COMMAND, or `M-x
1032      COMMAND' if COMMAND has no key bindings.
1033
1034 `\{MAPVAR}'
1035      stands for a summary of the value of MAPVAR, which should be a
1036      keymap.  The summary is made by `describe-bindings'.
1037
1038 `\<MAPVAR>'
1039      stands for no text itself.  It is used for a side effect: it
1040      specifies MAPVAR as the keymap for any following `\[COMMAND]'
1041      sequences in this documentation string.
1042
1043 `\='
1044      quotes the following character and is discarded; this `\=\=' puts
1045      `\=' into the output, and `\=\[' puts `\[' into the output.
1046
1047    *Please note:* Each `\' must be doubled when written in a string in
1048 XEmacs Lisp.
1049
1050  - Function: substitute-command-keys string
1051      This function scans STRING for the above special sequences and
1052      replaces them by what they stand for, returning the result as a
1053      string.  This permits display of documentation that refers
1054      accurately to the user's own customized key bindings.
1055
1056    Here are examples of the special sequences:
1057
1058      (substitute-command-keys
1059         "To abort recursive edit, type: \\[abort-recursive-edit]")
1060      => "To abort recursive edit, type: C-]"
1061
1062      (substitute-command-keys
1063         "The keys that are defined for the minibuffer here are:
1064        \\{minibuffer-local-must-match-map}")
1065      => "The keys that are defined for the minibuffer here are:
1066
1067      ?               minibuffer-completion-help
1068      SPC             minibuffer-complete-word
1069      TAB             minibuffer-complete
1070      LFD             minibuffer-complete-and-exit
1071      RET             minibuffer-complete-and-exit
1072      C-g             abort-recursive-edit
1073      "
1074
1075      (substitute-command-keys
1076         "To abort a recursive edit from the minibuffer, type\
1077      \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
1078      => "To abort a recursive edit from the minibuffer, type C-g."
1079
1080      (substitute-command-keys
1081        "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
1082      \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
1083      Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
1084      as the keymap for future \\=\\[COMMAND] substrings.
1085      \\=\\= quotes the following character and is discarded;
1086      thus, \\=\\=\\=\\= puts \\=\\= into the output,
1087      and \\=\\=\\=\\[ puts \\=\\[ into the output.")
1088      => "Substrings of the form \{MAPVAR} are replaced by summaries
1089      (made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
1090      Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
1091      as the keymap for future \[COMMAND] substrings.
1092      \= quotes the following character and is discarded;
1093      thus, \=\= puts \= into the output,
1094      and \=\[ puts \[ into the output."
1095
1096 \1f
1097 File: lispref.info,  Node: Describing Characters,  Next: Help Functions,  Prev: Keys in Documentation,  Up: Documentation
1098
1099 Describing Characters for Help Messages
1100 =======================================
1101
1102    These functions convert events, key sequences or characters to
1103 textual descriptions.  These descriptions are useful for including
1104 arbitrary text characters or key sequences in messages, because they
1105 convert non-printing and whitespace characters to sequences of printing
1106 characters.  The description of a non-whitespace printing character is
1107 the character itself.
1108
1109  - Function: key-description sequence
1110      This function returns a string containing the XEmacs standard
1111      notation for the input events in SEQUENCE.  The argument SEQUENCE
1112      may be a string, vector or list.  *Note Events::, for more
1113      information about valid events.  See also the examples for
1114      `single-key-description', below.
1115
1116  - Function: single-key-description key
1117      This function returns a string describing KEY in the standard
1118      XEmacs notation for keyboard input.  A normal printing character
1119      appears as itself, but a control character turns into a string
1120      starting with `C-', a meta character turns into a string starting
1121      with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
1122      A symbol appears as the name of the symbol.  An event that is a
1123      list appears as the name of the symbol in the CAR of the list.
1124
1125           (single-key-description ?\C-x)
1126                => "C-x"
1127           (key-description "\C-x \M-y \n \t \r \f123")
1128                => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
1129           (single-key-description 'kp_next)
1130                => "kp_next"
1131           (single-key-description '(shift button1))
1132                => "Sh-button1"
1133
1134  - Function: text-char-description character
1135      This function returns a string describing CHARACTER in the
1136      standard XEmacs notation for characters that appear in text--like
1137      `single-key-description', except that control characters are
1138      represented with a leading caret (which is how control characters
1139      in XEmacs buffers are usually displayed).
1140
1141           (text-char-description ?\C-c)
1142                => "^C"
1143           (text-char-description ?\M-m)
1144                => "M-m"
1145           (text-char-description ?\C-\M-m)
1146                => "M-^M"
1147