1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
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
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.
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.
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.
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.
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.
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.
53 File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes
55 How XEmacs Chooses a Major Mode
56 -------------------------------
58 Based on information in the file name or in the file itself, XEmacs
59 automatically selects a major mode for the new buffer when a file is
62 - Command: fundamental-mode
63 Fundamental mode is a major mode that is not specialized for
64 anything in particular. Other major modes are defined in effect
65 by comparison with this one--their definitions say what to change,
66 starting from Fundamental mode. The `fundamental-mode' function
67 does _not_ run any hooks; you're not supposed to customize it.
68 (If you want Emacs to behave differently in Fundamental mode,
69 change the _global_ state of Emacs.)
71 - Command: normal-mode &optional find-file
72 This function establishes the proper major mode and local variable
73 bindings for the current buffer. First it calls `set-auto-mode',
74 then it runs `hack-local-variables' to parse, and bind or evaluate
75 as appropriate, any local variables.
77 If the FIND-FILE argument to `normal-mode' is non-`nil',
78 `normal-mode' assumes that the `find-file' function is calling it.
79 In this case, it may process a local variables list at the end of
80 the file and in the `-*-' line. The variable
81 `enable-local-variables' controls whether to do so.
83 If you run `normal-mode' interactively, the argument FIND-FILE is
84 normally `nil'. In this case, `normal-mode' unconditionally
85 processes any local variables list. *Note Local Variables in
86 Files: (emacs)File variables, for the syntax of the local
87 variables section of a file.
89 `normal-mode' uses `condition-case' around the call to the major
90 mode function, so errors are caught and reported as a `File mode
91 specification error', followed by the original error message.
93 - User Option: enable-local-variables
94 This variable controls processing of local variables lists in files
95 being visited. A value of `t' means process the local variables
96 lists unconditionally; `nil' means ignore them; anything else means
97 ask the user what to do for each file. The default value is `t'.
99 - Variable: ignored-local-variables
100 This variable holds a list of variables that should not be set by
101 a local variables list. Any value specified for one of these
102 variables is ignored.
104 In addition to this list, any variable whose name has a non-`nil'
105 `risky-local-variable' property is also ignored.
107 - User Option: enable-local-eval
108 This variable controls processing of `Eval:' in local variables
109 lists in files being visited. A value of `t' means process them
110 unconditionally; `nil' means ignore them; anything else means ask
111 the user what to do for each file. The default value is `maybe'.
113 - Function: set-auto-mode
114 This function selects the major mode that is appropriate for the
115 current buffer. It may base its decision on the value of the `-*-'
116 line, on the visited file name (using `auto-mode-alist'), or on the
117 value of a local variable. However, this function does not look
118 for the `mode:' local variable near the end of a file; the
119 `hack-local-variables' function does that. *Note How Major Modes
120 are Chosen: (emacs)Choosing Modes.
122 - User Option: default-major-mode
123 This variable holds the default major mode for new buffers. The
124 standard value is `fundamental-mode'.
126 If the value of `default-major-mode' is `nil', XEmacs uses the
127 (previously) current buffer's major mode for the major mode of a
128 new buffer. However, if the major mode symbol has a `mode-class'
129 property with value `special', then it is not used for new buffers;
130 Fundamental mode is used instead. The modes that have this
131 property are those such as Dired and Rmail that are useful only
132 with text that has been specially prepared.
134 - Function: set-buffer-major-mode buffer
135 This function sets the major mode of BUFFER to the value of
136 `default-major-mode'. If that variable is `nil', it uses the
137 current buffer's major mode (if that is suitable).
139 The low-level primitives for creating buffers do not use this
140 function, but medium-level commands such as `switch-to-buffer' and
141 `find-file-noselect' use it whenever they create buffers.
143 - Variable: initial-major-mode
144 The value of this variable determines the major mode of the initial
145 `*scratch*' buffer. The value should be a symbol that is a major
146 mode command name. The default value is `lisp-interaction-mode'.
148 - Variable: auto-mode-alist
149 This variable contains an association list of file name patterns
150 (regular expressions; *note Regular Expressions::) and
151 corresponding major mode functions. Usually, the file name
152 patterns test for suffixes, such as `.el' and `.c', but this need
153 not be the case. An ordinary element of the alist looks like
154 `(REGEXP . MODE-FUNCTION)'.
158 (("^/tmp/fol/" . text-mode)
159 ("\\.texinfo\\'" . texinfo-mode)
160 ("\\.texi\\'" . texinfo-mode)
161 ("\\.el\\'" . emacs-lisp-mode)
166 When you visit a file whose expanded file name (*note File Name
167 Expansion::) matches a REGEXP, `set-auto-mode' calls the
168 corresponding MODE-FUNCTION. This feature enables XEmacs to select
169 the proper major mode for most files.
171 If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
172 t)', then after calling FUNCTION, XEmacs searches
173 `auto-mode-alist' again for a match against the portion of the file
174 name that did not match before.
176 This match-again feature is useful for uncompression packages: an
177 entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
178 and then put the uncompressed file in the proper mode according to
181 Here is an example of how to prepend several pattern pairs to
182 `auto-mode-alist'. (You might use this sort of expression in your
185 (setq auto-mode-alist
187 ;; File name starts with a dot.
188 '(("/\\.[^/]*\\'" . fundamental-mode)
189 ;; File name has no dot.
190 ("[^\\./]*\\'" . fundamental-mode)
191 ;; File name ends in `.C'.
192 ("\\.C\\'" . c++-mode))
195 - Variable: interpreter-mode-alist
196 This variable specifies major modes to use for scripts that
197 specify a command interpreter in an `#!' line. Its value is a
198 list of elements of the form `(INTERPRETER . MODE)'; for example,
199 `("perl" . perl-mode)' is one element present by default. The
200 element says to use mode MODE if the file specifies INTERPRETER.
202 This variable is applicable only when the `auto-mode-alist' does
203 not indicate which major mode to use.
205 - Function: hack-local-variables &optional force
206 This function parses, and binds or evaluates as appropriate, any
207 local variables for the current buffer.
209 The handling of `enable-local-variables' documented for
210 `normal-mode' actually takes place here. The argument FORCE
211 usually comes from the argument FIND-FILE given to `normal-mode'.
214 File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes
216 Getting Help about a Major Mode
217 -------------------------------
219 The `describe-mode' function is used to provide information about
220 major modes. It is normally called with `C-h m'. The `describe-mode'
221 function uses the value of `major-mode', which is why every major mode
222 function needs to set the `major-mode' variable.
224 - Command: describe-mode
225 This function displays the documentation of the current major mode.
227 The `describe-mode' function calls the `documentation' function
228 using the value of `major-mode' as an argument. Thus, it displays
229 the documentation string of the major mode function. (*Note
230 Accessing Documentation::.)
232 - Variable: major-mode
233 This variable holds the symbol for the current buffer's major mode.
234 This symbol should have a function definition that is the command
235 to switch to that major mode. The `describe-mode' function uses
236 the documentation string of the function as the documentation of
240 File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes
242 Defining Derived Modes
243 ----------------------
245 It's often useful to define a new major mode in terms of an existing
246 one. An easy way to do this is to use `define-derived-mode'.
248 - Macro: define-derived-mode variant parent name docstring body...
249 This construct defines VARIANT as a major mode command, using NAME
250 as the string form of the mode name.
252 The new command VARIANT is defined to call the function PARENT,
253 then override certain aspects of that parent mode:
255 * The new mode has its own keymap, named `VARIANT-map'.
256 `define-derived-mode' initializes this map to inherit from
257 `PARENT-map', if it is not already set.
259 * The new mode has its own syntax table, kept in the variable
260 `VARIANT-syntax-table'. `define-derived-mode' initializes
261 this variable by copying `PARENT-syntax-table', if it is not
264 * The new mode has its own abbrev table, kept in the variable
265 `VARIANT-abbrev-table'. `define-derived-mode' initializes
266 this variable by copying `PARENT-abbrev-table', if it is not
269 * The new mode has its own mode hook, `VARIANT-hook', which it
270 runs in standard fashion as the very last thing that it does.
271 (The new mode also runs the mode hook of PARENT as part of
274 In addition, you can specify how to override other aspects of
275 PARENT with BODY. The command VARIANT evaluates the forms in BODY
276 after setting up all its usual overrides, just before running
279 The argument DOCSTRING specifies the documentation string for the
280 new mode. If you omit DOCSTRING, `define-derived-mode' generates
281 a documentation string.
283 Here is a hypothetical example:
285 (define-derived-mode hypertext-mode
286 text-mode "Hypertext"
287 "Major mode for hypertext.
288 \\{hypertext-mode-map}"
289 (setq case-fold-search nil))
291 (define-key hypertext-mode-map
292 [down-mouse-3] 'do-hyper-link)
295 File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes
300 A "minor mode" provides features that users may enable or disable
301 independently of the choice of major mode. Minor modes can be enabled
302 individually or in combination. Minor modes would be better named
303 "Generally available, optional feature modes" except that such a name is
306 A minor mode is not usually a modification of single major mode. For
307 example, Auto Fill mode may be used in any major mode that permits text
308 insertion. To be general, a minor mode must be effectively independent
309 of the things major modes do.
311 A minor mode is often much more difficult to implement than a major
312 mode. One reason is that you should be able to activate and deactivate
313 minor modes in any order. A minor mode should be able to have its
314 desired effect regardless of the major mode and regardless of the other
315 minor modes in effect.
317 Often the biggest problem in implementing a minor mode is finding a
318 way to insert the necessary hook into the rest of XEmacs. Minor mode
319 keymaps make this easier than it used to be.
323 * Minor Mode Conventions:: Tips for writing a minor mode.
324 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
327 File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes
329 Conventions for Writing Minor Modes
330 -----------------------------------
332 There are conventions for writing minor modes just as there are for
333 major modes. Several of the major mode conventions apply to minor
334 modes as well: those regarding the name of the mode initialization
335 function, the names of global symbols, and the use of keymaps and other
338 In addition, there are several conventions that are specific to
341 * Make a variable whose name ends in `-mode' to represent the minor
342 mode. Its value should enable or disable the mode (`nil' to
343 disable; anything else to enable.) We call this the "mode
346 This variable is used in conjunction with the `minor-mode-alist' to
347 display the minor mode name in the modeline. It can also enable
348 or disable a minor mode keymap. Individual commands or hooks can
349 also check the variable's value.
351 If you want the minor mode to be enabled separately in each buffer,
352 make the variable buffer-local.
354 * Define a command whose name is the same as the mode variable. Its
355 job is to enable and disable the mode by setting the variable.
357 The command should accept one optional argument. If the argument
358 is `nil', it should toggle the mode (turn it on if it is off, and
359 off if it is on). Otherwise, it should turn the mode on if the
360 argument is a positive integer, a symbol other than `nil' or `-',
361 or a list whose CAR is such an integer or symbol; it should turn
362 the mode off otherwise.
364 Here is an example taken from the definition of
365 `transient-mark-mode'. It shows the use of `transient-mark-mode'
366 as a variable that enables or disables the mode's behavior, and
367 also shows the proper way to toggle, enable or disable the minor
368 mode based on the raw prefix argument value.
370 (setq transient-mark-mode
371 (if (null arg) (not transient-mark-mode)
372 (> (prefix-numeric-value arg) 0)))
374 * Add an element to `minor-mode-alist' for each minor mode (*note
375 Modeline Variables::). This element should be a list of the
378 (MODE-VARIABLE STRING)
380 Here MODE-VARIABLE is the variable that controls enabling of the
381 minor mode, and STRING is a short string, starting with a space,
382 to represent the mode in the modeline. These strings must be
383 short so that there is room for several of them at once.
385 When you add an element to `minor-mode-alist', use `assq' to check
386 for an existing element, to avoid duplication. For example:
388 (or (assq 'leif-mode minor-mode-alist)
389 (setq minor-mode-alist
390 (cons '(leif-mode " Leif") minor-mode-alist)))
393 File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes
395 Keymaps and Minor Modes
396 -----------------------
398 Each minor mode can have its own keymap, which is active when the
399 mode is enabled. To set up a keymap for a minor mode, add an element
400 to the alist `minor-mode-map-alist'. *Note Active Keymaps::.
402 One use of minor mode keymaps is to modify the behavior of certain
403 self-inserting characters so that they do something else as well as
404 self-insert. In general, this is the only way to do that, since the
405 facilities for customizing `self-insert-command' are limited to special
406 cases (designed for abbrevs and Auto Fill mode). (Do not try
407 substituting your own definition of `self-insert-command' for the
408 standard one. The editor command loop handles this function specially.)
411 File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes
416 Each Emacs window (aside from minibuffer windows) includes a
417 modeline, which displays status information about the buffer displayed
418 in the window. The modeline contains information about the buffer,
419 such as its name, associated file, depth of recursive editing, and the
420 major and minor modes.
422 This section describes how the contents of the modeline are
423 controlled. It is in the chapter on modes because much of the
424 information displayed in the modeline relates to the enabled major and
427 `modeline-format' is a buffer-local variable that holds a template
428 used to display the modeline of the current buffer. All windows for
429 the same buffer use the same `modeline-format' and their modelines
430 appear the same (except for scrolling percentages and line numbers).
432 The modeline of a window is normally updated whenever a different
433 buffer is shown in the window, or when the buffer's modified-status
434 changes from `nil' to `t' or vice-versa. If you modify any of the
435 variables referenced by `modeline-format' (*note Modeline Variables::),
436 you may want to force an update of the modeline so as to display the
439 - Function: redraw-modeline &optional all
440 Force redisplay of the current buffer's modeline. If ALL is
441 non-`nil', then force redisplay of all modelines.
443 The modeline is usually displayed in inverse video. This is
444 controlled using the `modeline' face. *Note Faces::.
448 * Modeline Data:: The data structure that controls the modeline.
449 * Modeline Variables:: Variables used in that data structure.
450 * %-Constructs:: Putting information into a modeline.
453 File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format
455 The Data Structure of the Modeline
456 ----------------------------------
458 The modeline contents are controlled by a data structure of lists,
459 strings, symbols, and numbers kept in the buffer-local variable
460 `mode-line-format'. The data structure is called a "modeline
461 construct", and it is built in recursive fashion out of simpler modeline
462 constructs. The same data structure is used for constructing frame
463 titles (*note Frame Titles::).
465 - Variable: modeline-format
466 The value of this variable is a modeline construct with overall
467 responsibility for the modeline format. The value of this variable
468 controls which other variables are used to form the modeline text,
469 and where they appear.
471 A modeline construct may be as simple as a fixed string of text, but
472 it usually specifies how to use other variables to construct the text.
473 Many of these variables are themselves defined to have modeline
474 constructs as their values.
476 The default value of `modeline-format' incorporates the values of
477 variables such as `mode-name' and `minor-mode-alist'. Because of this,
478 very few modes need to alter `modeline-format'. For most purposes, it
479 is sufficient to alter the variables referenced by `modeline-format'.
481 A modeline construct may be a list, a symbol, or a string. If the
482 value is a list, each element may be a list, a symbol, or a string.
485 A string as a modeline construct is displayed verbatim in the mode
486 line except for "`%'-constructs". Decimal digits after the `%'
487 specify the field width for space filling on the right (i.e., the
488 data is left justified). *Note %-Constructs::.
491 A symbol as a modeline construct stands for its value. The value
492 of SYMBOL is used as a modeline construct, in place of SYMBOL.
493 However, the symbols `t' and `nil' are ignored; so is any symbol
496 There is one exception: if the value of SYMBOL is a string, it is
497 displayed verbatim: the `%'-constructs are not recognized.
499 `(STRING REST...) or (LIST REST...)'
500 A list whose first element is a string or list means to process
501 all the elements recursively and concatenate the results. This is
502 the most common form of mode line construct.
505 A list whose first element is a symbol is a conditional. Its
506 meaning depends on the value of SYMBOL. If the value is non-`nil',
507 the second element, THEN, is processed recursively as a modeline
508 element. But if the value of SYMBOL is `nil', the third element,
509 ELSE, is processed recursively. You may omit ELSE; then the mode
510 line element displays nothing if the value of SYMBOL is `nil'.
513 A list whose first element is an integer specifies truncation or
514 padding of the results of REST. The remaining elements REST are
515 processed recursively as modeline constructs and concatenated
516 together. Then the result is space filled (if WIDTH is positive)
517 or truncated (to -WIDTH columns, if WIDTH is negative) on the
520 For example, the usual way to show what percentage of a buffer is
521 above the top of the window is to use a list like this: `(-3
524 If you do alter `modeline-format' itself, the new value should use
525 the same variables that appear in the default value (*note Modeline
526 Variables::), rather than duplicating their contents or displaying the
527 information in another fashion. This way, customizations made by the
528 user or by Lisp programs (such as `display-time' and major modes) via
529 changes to those variables remain effective.
531 Here is an example of a `modeline-format' that might be useful for
532 `shell-mode', since it contains the hostname and default directory.
534 (setq modeline-format
538 (getenv "HOST") ; One element is not constant.
549 '(line-number-mode "L%l--")
554 File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format
556 Variables Used in the Modeline
557 ------------------------------
559 This section describes variables incorporated by the standard value
560 of `modeline-format' into the text of the mode line. There is nothing
561 inherently special about these variables; any other variables could
562 have the same effects on the modeline if `modeline-format' were changed
565 - Variable: modeline-modified
566 This variable holds the value of the modeline construct that
567 displays whether the current buffer is modified.
569 The default value of `modeline-modified' is `("--%1*%1+-")'. This
570 means that the modeline displays `--**-' if the buffer is
571 modified, `-----' if the buffer is not modified, `--%%-' if the
572 buffer is read only, and `--%*--' if the buffer is read only and
575 Changing this variable does not force an update of the modeline.
577 - Variable: modeline-buffer-identification
578 This variable identifies the buffer being displayed in the window.
579 Its default value is `("%F: %17b")', which means that it usually
580 displays `Emacs:' followed by seventeen characters of the buffer
581 name. (In a terminal frame, it displays the frame name instead of
582 `Emacs'; this has the effect of showing the frame number.) You may
583 want to change this in modes such as Rmail that do not behave like
586 - Variable: global-mode-string
587 This variable holds a modeline spec that appears in the mode line
588 by default, just after the buffer name. The command `display-time'
589 sets `global-mode-string' to refer to the variable
590 `display-time-string', which holds a string containing the time and
593 The `%M' construct substitutes the value of `global-mode-string',
594 but this is obsolete, since the variable is included directly in
597 - Variable: mode-name
598 This buffer-local variable holds the "pretty" name of the current
599 buffer's major mode. Each major mode should set this variable so
600 that the mode name will appear in the modeline.
602 - Variable: minor-mode-alist
603 This variable holds an association list whose elements specify how
604 the modeline should indicate that a minor mode is active. Each
605 element of the `minor-mode-alist' should be a two-element list:
607 (MINOR-MODE-VARIABLE MODELINE-STRING)
609 More generally, MODELINE-STRING can be any mode line spec. It
610 appears in the mode line when the value of MINOR-MODE-VARIABLE is
611 non-`nil', and not otherwise. These strings should begin with
612 spaces so that they don't run together. Conventionally, the
613 MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
614 value when that minor mode is activated.
616 The default value of `minor-mode-alist' is:
619 => ((vc-mode vc-mode)
620 (abbrev-mode " Abbrev")
621 (overwrite-mode overwrite-mode)
622 (auto-fill-function " Fill")
623 (defining-kbd-macro " Def")
624 (isearch-mode isearch-mode))
626 `minor-mode-alist' is not buffer-local. The variables mentioned
627 in the alist should be buffer-local if the minor mode can be
628 enabled separately in each buffer.
630 - Variable: modeline-process
631 This buffer-local variable contains the modeline information on
632 process status in modes used for communicating with subprocesses.
633 It is displayed immediately following the major mode name, with no
634 intervening space. For example, its value in the `*shell*' buffer
635 is `(": %s")', which allows the shell to display its status along
636 with the major mode as: `(Shell: run)'. Normally this variable is
639 - Variable: default-modeline-format
640 This variable holds the default `modeline-format' for buffers that
641 do not override it. This is the same as `(default-value
644 The default value of `default-modeline-format' is:
648 modeline-buffer-identification
657 (line-number-mode "L%l--")
662 The variable `vc-mode', local in each buffer, records whether the
663 buffer's visited file is maintained with version control, and, if
664 so, which kind. Its value is `nil' for no version control, or a
665 string that appears in the mode line.
668 File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format
670 `%'-Constructs in the ModeLine
671 ------------------------------
673 The following table lists the recognized `%'-constructs and what
674 they mean. In any construct except `%%', you can add a decimal integer
675 after the `%' to specify how many characters to display.
678 The current buffer name, obtained with the `buffer-name' function.
679 *Note Buffer Names::.
682 The visited file name, obtained with the `buffer-file-name'
683 function. *Note Buffer File Name::.
686 The name of the selected frame.
689 The current column number of point.
692 The current line number of point.
695 `%' if the buffer is read only (see `buffer-read-only');
696 `*' if the buffer is modified (see `buffer-modified-p');
697 `-' otherwise. *Note Buffer Modification::.
700 `*' if the buffer is modified (see `buffer-modified-p');
701 `%' if the buffer is read only (see `buffer-read-only');
702 `-' otherwise. This differs from `%*' only for a modified
703 read-only buffer. *Note Buffer Modification::.
706 `*' if the buffer is modified, and `-' otherwise.
709 The status of the subprocess belonging to the current buffer,
710 obtained with `process-status'. *Note Process Information::.
713 the current line number.
716 the name of the selected frame; this is only meaningful under the
717 X Window System. *Note Frame Name::.
720 Whether the visited file is a text file or a binary file. (This
721 is a meaningful distinction only on certain operating systems.)
724 The percentage of the buffer text above the *top* of window, or
725 `Top', `Bottom' or `All'.
728 The percentage of the buffer text that is above the *bottom* of
729 the window (which includes the text visible in the window, as well
730 as the text above the top), plus `Top' if the top of the buffer is
731 visible on screen; or `Bottom' or `All'.
734 `Narrow' when narrowing is in effect; nothing otherwise (see
735 `narrow-to-region' in *Note Narrowing::).
738 An indication of the depth of recursive editing levels (not
739 counting minibuffer levels): one `[' for each editing level.
740 *Note Recursive Editing::.
743 One `]' for each recursive editing level (not counting minibuffer
747 The character `%'--this is how to include a literal `%' in a
748 string in which `%'-constructs are allowed.
751 Dashes sufficient to fill the remainder of the modeline.
753 The following two `%'-constructs are still supported, but they are
754 obsolete, since you can get the same results with the variables
755 `mode-name' and `global-mode-string'.
758 The value of `mode-name'.
761 The value of `global-mode-string'. Currently, only `display-time'
762 modifies the value of `global-mode-string'.
765 File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
770 A "hook" is a variable where you can store a function or functions
771 to be called on a particular occasion by an existing program. XEmacs
772 provides hooks for the sake of customization. Most often, hooks are set
773 up in the `.emacs' file, but Lisp programs can set them also. *Note
774 Standard Hooks::, for a list of standard hook variables.
776 Most of the hooks in XEmacs are "normal hooks". These variables
777 contain lists of functions to be called with no arguments. The reason
778 most hooks are normal hooks is so that you can use them in a uniform
779 way. You can usually tell when a hook is a normal hook, because its
780 name ends in `-hook'.
782 The recommended way to add a hook function to a normal hook is by
783 calling `add-hook' (see below). The hook functions may be any of the
784 valid kinds of functions that `funcall' accepts (*note What Is a
785 Function::). Most normal hook variables are initially void; `add-hook'
786 knows how to deal with this.
788 As for abnormal hooks, those whose names end in `-function' have a
789 value that is a single function. Those whose names end in `-hooks'
790 have a value that is a list of functions. Any hook that is abnormal is
791 abnormal because a normal hook won't do the job; either the functions
792 are called with arguments, or their values are meaningful. The name
793 shows you that the hook is abnormal and that you should look at its
794 documentation string to see how to use it properly.
796 Major mode functions are supposed to run a hook called the "mode
797 hook" as the last step of initialization. This makes it easy for a user
798 to customize the behavior of the mode, by overriding the local variable
799 assignments already made by the mode. But hooks are used in other
800 contexts too. For example, the hook `suspend-hook' runs just before
801 XEmacs suspends itself (*note Suspending XEmacs::).
803 Here's an expression that uses a mode hook to turn on Auto Fill mode
804 when in Lisp Interaction mode:
806 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
808 The next example shows how to use a hook to customize the way XEmacs
809 formats C code. (People often have strong personal preferences for one
810 format or another.) Here the hook function is an anonymous lambda
813 (add-hook 'c-mode-hook
815 (setq c-indent-level 4
818 c-continued-statement-indent 0
820 comment-column 40))))
822 (setq c++-mode-hook c-mode-hook)
824 The final example shows how the appearance of the modeline can be
825 modified for a particular class of buffers only.
827 (add-hook 'text-mode-hook
829 (setq modeline-format
845 At the appropriate time, XEmacs uses the `run-hooks' function to run
846 particular hooks. This function calls the hook functions you have
847 added with `add-hooks'.
849 - Function: run-hooks &rest hookvar
850 This function takes one or more hook variable names as arguments,
851 and runs each hook in turn. Each HOOKVAR argument should be a
852 symbol that is a hook variable. These arguments are processed in
855 If a hook variable has a non-`nil' value, that value may be a
856 function or a list of functions. If the value is a function
857 (either a lambda expression or a symbol with a function
858 definition), it is called. If it is a list, the elements are
859 called, in order. The hook functions are called with no arguments.
861 For example, here's how `emacs-lisp-mode' runs its mode hook:
863 (run-hooks 'emacs-lisp-mode-hook)
865 - Function: add-hook hook function &optional append local
866 This function is the handy way to add function FUNCTION to hook
867 variable HOOK. The argument FUNCTION may be any valid Lisp
868 function with the proper number of arguments. For example,
870 (add-hook 'text-mode-hook 'my-text-hook-function)
872 adds `my-text-hook-function' to the hook called `text-mode-hook'.
874 You can use `add-hook' for abnormal hooks as well as for normal
877 It is best to design your hook functions so that the order in
878 which they are executed does not matter. Any dependence on the
879 order is "asking for trouble." However, the order is predictable:
880 normally, FUNCTION goes at the front of the hook list, so it will
881 be executed first (barring another `add-hook' call).
883 If the optional argument APPEND is non-`nil', the new hook
884 function goes at the end of the hook list and will be executed
887 If LOCAL is non-`nil', that says to make the new hook function
888 local to the current buffer. Before you can do this, you must
889 make the hook itself buffer-local by calling `make-local-hook'
890 (*not* `make-local-variable'). If the hook itself is not
891 buffer-local, then the value of LOCAL makes no difference--the
892 hook function is always global.
894 - Function: remove-hook hook function &optional local
895 This function removes FUNCTION from the hook variable HOOK.
897 If LOCAL is non-`nil', that says to remove FUNCTION from the local
898 hook list instead of from the global hook list. If the hook
899 itself is not buffer-local, then the value of LOCAL makes no
902 - Function: make-local-hook hook
903 This function makes the hook variable `hook' local to the current
904 buffer. When a hook variable is local, it can have local and
905 global hook functions, and `run-hooks' runs all of them.
907 This function works by making `t' an element of the buffer-local
908 value. That serves as a flag to use the hook functions in the
909 default value of the hook variable as well as those in the local
910 value. Since `run-hooks' understands this flag, `make-local-hook'
911 works with all normal hooks. It works for only some non-normal
912 hooks--those whose callers have been updated to understand this
915 Do not use `make-local-variable' directly for hook variables; it is
919 File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
924 XEmacs Lisp has convenient on-line help facilities, most of which
925 derive their information from the documentation strings associated with
926 functions and variables. This chapter describes how to write good
927 documentation strings for your Lisp programs, as well as how to write
928 programs to access documentation.
930 Note that the documentation strings for XEmacs are not the same thing
931 as the XEmacs manual. Manuals have their own source files, written in
932 the Texinfo language; documentation strings are specified in the
933 definitions of the functions and variables they apply to. A collection
934 of documentation strings is not sufficient as a manual because a good
935 manual is not organized in that fashion; it is organized in terms of
936 topics of discussion.
940 * Documentation Basics:: Good style for doc strings.
941 Where to put them. How XEmacs stores them.
942 * Accessing Documentation:: How Lisp programs can access doc strings.
943 * Keys in Documentation:: Substituting current key bindings.
944 * Describing Characters:: Making printable descriptions of
945 non-printing characters and key sequences.
946 * Help Functions:: Subroutines used by XEmacs help facilities.
947 * Obsoleteness:: Upgrading Lisp functionality over time.
950 File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
955 A documentation string is written using the Lisp syntax for strings,
956 with double-quote characters surrounding the text of the string. This
957 is because it really is a Lisp string object. The string serves as
958 documentation when it is written in the proper place in the definition
959 of a function or variable. In a function definition, the documentation
960 string follows the argument list. In a variable definition, the
961 documentation string follows the initial value of the variable.
963 When you write a documentation string, make the first line a complete
964 sentence (or two complete sentences) since some commands, such as
965 `apropos', show only the first line of a multi-line documentation
966 string. Also, you should not indent the second line of a documentation
967 string, if you have one, because that looks odd when you use `C-h f'
968 (`describe-function') or `C-h v' (`describe-variable'). *Note
969 Documentation Tips::.
971 Documentation strings may contain several special substrings, which
972 stand for key bindings to be looked up in the current keymaps when the
973 documentation is displayed. This allows documentation strings to refer
974 to the keys for related commands and be accurate even when a user
975 rearranges the key bindings. (*Note Accessing Documentation::.)
977 Within the Lisp world, a documentation string is accessible through
978 the function or variable that it describes:
980 * The documentation for a function is stored in the function
981 definition itself (*note Lambda Expressions::). The function
982 `documentation' knows how to extract it.
984 * The documentation for a variable is stored in the variable's
985 property list under the property name `variable-documentation'.
986 The function `documentation-property' knows how to extract it.
988 To save space, the documentation for preloaded functions and
989 variables (including primitive functions and autoloaded functions) is
990 stored in the "internal doc file" `DOC'. The documentation for
991 functions and variables loaded during the XEmacs session from
992 byte-compiled files is stored in those very same byte-compiled files
993 (*note Docs and Compilation::).
995 XEmacs does not keep documentation strings in memory unless
996 necessary. Instead, XEmacs maintains, for preloaded symbols, an
997 integer offset into the internal doc file, and for symbols loaded from
998 byte-compiled files, a list containing the filename of the
999 byte-compiled file and an integer offset, in place of the documentation
1000 string. The functions `documentation' and `documentation-property' use
1001 that information to read the documentation from the appropriate file;
1002 this is transparent to the user.
1004 For information on the uses of documentation strings, see *Note
1007 The `emacs/lib-src' directory contains two utilities that you can
1008 use to print nice-looking hardcopy for the file
1009 `emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'.
1012 File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
1014 Access to Documentation Strings
1015 ===============================
1017 - Function: documentation-property symbol property &optional verbatim
1018 This function returns the documentation string that is recorded in
1019 SYMBOL's property list under property PROPERTY. It retrieves the
1020 text from a file if necessary, and runs `substitute-command-keys'
1021 to substitute actual key bindings. (This substitution is not done
1022 if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
1025 (documentation-property 'command-line-processed
1026 'variable-documentation)
1027 => "t once command line has been processed"
1028 (symbol-plist 'command-line-processed)
1029 => (variable-documentation 188902)
1031 - Function: documentation function &optional verbatim
1032 This function returns the documentation string of FUNCTION. It
1033 reads the text from a file if necessary. Then (unless VERBATIM is
1034 non-`nil') it calls `substitute-command-keys', to return a value
1035 containing the actual (current) key bindings.
1037 The function `documentation' signals a `void-function' error if
1038 FUNCTION has no function definition. However, it is ok if the
1039 function definition has no documentation string. In that case,
1040 `documentation' returns `nil'.
1042 Here is an example of using the two functions, `documentation' and
1043 `documentation-property', to display the documentation strings for
1044 several symbols in a `*Help*' buffer.
1046 (defun describe-symbols (pattern)
1047 "Describe the XEmacs Lisp symbols matching PATTERN.
1048 All symbols that have PATTERN in their name are described
1049 in the `*Help*' buffer."
1050 (interactive "sDescribe symbols matching: ")
1051 (let ((describe-func
1054 ;; Print description of symbol.
1055 (if (fboundp s) ; It is a function.
1057 (format "%s\t%s\n%s\n\n" s
1059 (let ((keys (where-is-internal s)))
1063 (mapconcat 'key-description
1067 (or (documentation s)
1068 "not documented"))))
1070 (if (boundp s) ; It is a variable.
1072 (format "%s\t%s\n%s\n\n" s
1073 (if (user-variable-p s)
1074 "Option " "Variable")
1075 (or (documentation-property
1076 s 'variable-documentation)
1077 "not documented")))))))
1080 ;; Build a list of symbols that match pattern.
1083 (if (string-match pattern (symbol-name sym))
1084 (setq sym-list (cons sym sym-list))))))
1086 ;; Display the data.
1087 (with-output-to-temp-buffer "*Help*"
1088 (mapcar describe-func (sort sym-list 'string<))
1089 (print-help-return-message))))
1091 The `describe-symbols' function works like `apropos', but provides
1094 (describe-symbols "goal")
1096 ---------- Buffer: *Help* ----------
1098 *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
1100 set-goal-column Command: C-x C-n
1101 Set the current horizontal position as a goal for C-n and C-p.
1102 Those commands will move to this position in the line moved to
1103 rather than trying to keep the same horizontal position.
1104 With a non-nil argument, clears out the goal column
1105 so that C-n and C-p resume vertical motion.
1106 The goal column is stored in the variable `goal-column'.
1108 temporary-goal-column Variable
1109 Current goal column for vertical motion.
1110 It is the column where point was
1111 at the start of current run of vertical motion commands.
1112 When the `track-eol' feature is doing its job, the value is 9999.
1113 ---------- Buffer: *Help* ----------
1115 - Function: Snarf-documentation filename
1116 This function is used only during XEmacs initialization, just
1117 before the runnable XEmacs is dumped. It finds the file offsets
1118 of the documentation strings stored in the file FILENAME, and
1119 records them in the in-core function definitions and variable
1120 property lists in place of the actual strings. *Note Building
1123 XEmacs finds the file FILENAME in the `lib-src' directory. When
1124 the dumped XEmacs is later executed, the same file is found in the
1125 directory `doc-directory'. The usual value for FILENAME is `DOC',
1126 but this can be changed by modifying the variable
1127 `internal-doc-file-name'.
1129 - Variable: internal-doc-file-name
1130 This variable holds the name of the file containing documentation
1131 strings of built-in symbols, usually `DOC'. The full pathname of
1132 the internal doc file is `(concat doc-directory
1133 internal-doc-file-name)'.
1135 - Variable: doc-directory
1136 This variable holds the name of the directory which contains the
1137 "internal doc file" that contains documentation strings for
1138 built-in and preloaded functions and variables.
1140 In most cases, this is the same as `exec-directory'. They may be
1141 different when you run XEmacs from the directory where you built
1142 it, without actually installing it. See `exec-directory' in *Note
1145 In older Emacs versions, `exec-directory' was used for this.
1147 - Variable: data-directory
1148 This variable holds the name of the directory in which XEmacs finds
1149 certain system independent documentation and text files that come
1150 with XEmacs. In older Emacs versions, `exec-directory' was used