1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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)
162 ("\\.el\\'" . emacs-lisp-mode)
167 When you visit a file whose expanded file name (*note File Name
168 Expansion::.) matches a REGEXP, `set-auto-mode' calls the
169 corresponding MODE-FUNCTION. This feature enables XEmacs to select
170 the proper major mode for most files.
172 If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
173 t)', then after calling FUNCTION, XEmacs searches
174 `auto-mode-alist' again for a match against the portion of the file
175 name that did not match before.
177 This match-again feature is useful for uncompression packages: an
178 entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
179 and then put the uncompressed file in the proper mode according to
182 Here is an example of how to prepend several pattern pairs to
183 `auto-mode-alist'. (You might use this sort of expression in your
186 (setq auto-mode-alist
188 ;; File name starts with a dot.
189 '(("/\\.[^/]*\\'" . fundamental-mode)
190 ;; File name has no dot.
191 ("[^\\./]*\\'" . fundamental-mode)
192 ;; File name ends in `.C'.
193 ("\\.C\\'" . c++-mode))
196 - Variable: interpreter-mode-alist
197 This variable specifies major modes to use for scripts that
198 specify a command interpreter in an `#!' line. Its value is a
199 list of elements of the form `(INTERPRETER . MODE)'; for example,
200 `("perl" . perl-mode)' is one element present by default. The
201 element says to use mode MODE if the file specifies INTERPRETER.
203 This variable is applicable only when the `auto-mode-alist' does
204 not indicate which major mode to use.
206 - Function: hack-local-variables &optional FORCE
207 This function parses, and binds or evaluates as appropriate, any
208 local variables for the current buffer.
210 The handling of `enable-local-variables' documented for
211 `normal-mode' actually takes place here. The argument FORCE
212 usually comes from the argument FIND-FILE given to `normal-mode'.
215 File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes
217 Getting Help about a Major Mode
218 -------------------------------
220 The `describe-mode' function is used to provide information about
221 major modes. It is normally called with `C-h m'. The `describe-mode'
222 function uses the value of `major-mode', which is why every major mode
223 function needs to set the `major-mode' variable.
225 - Command: describe-mode
226 This function displays the documentation of the current major mode.
228 The `describe-mode' function calls the `documentation' function
229 using the value of `major-mode' as an argument. Thus, it displays
230 the documentation string of the major mode function. (*Note
231 Accessing Documentation::.)
233 - Variable: major-mode
234 This variable holds the symbol for the current buffer's major mode.
235 This symbol should have a function definition that is the command
236 to switch to that major mode. The `describe-mode' function uses
237 the documentation string of the function as the documentation of
241 File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes
243 Defining Derived Modes
244 ----------------------
246 It's often useful to define a new major mode in terms of an existing
247 one. An easy way to do this is to use `define-derived-mode'.
249 - Macro: define-derived-mode VARIANT PARENT NAME DOCSTRING BODY...
250 This construct defines VARIANT as a major mode command, using NAME
251 as the string form of the mode name.
253 The new command VARIANT is defined to call the function PARENT,
254 then override certain aspects of that parent mode:
256 * The new mode has its own keymap, named `VARIANT-map'.
257 `define-derived-mode' initializes this map to inherit from
258 `PARENT-map', if it is not already set.
260 * The new mode has its own syntax table, kept in the variable
261 `VARIANT-syntax-table'. `define-derived-mode' initializes
262 this variable by copying `PARENT-syntax-table', if it is not
265 * The new mode has its own abbrev table, kept in the variable
266 `VARIANT-abbrev-table'. `define-derived-mode' initializes
267 this variable by copying `PARENT-abbrev-table', if it is not
270 * The new mode has its own mode hook, `VARIANT-hook', which it
271 runs in standard fashion as the very last thing that it does.
272 (The new mode also runs the mode hook of PARENT as part of
275 In addition, you can specify how to override other aspects of
276 PARENT with BODY. The command VARIANT evaluates the forms in BODY
277 after setting up all its usual overrides, just before running
280 The argument DOCSTRING specifies the documentation string for the
281 new mode. If you omit DOCSTRING, `define-derived-mode' generates
282 a documentation string.
284 Here is a hypothetical example:
286 (define-derived-mode hypertext-mode
287 text-mode "Hypertext"
288 "Major mode for hypertext.
289 \\{hypertext-mode-map}"
290 (setq case-fold-search nil))
292 (define-key hypertext-mode-map
293 [down-mouse-3] 'do-hyper-link)
296 File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes
301 A "minor mode" provides features that users may enable or disable
302 independently of the choice of major mode. Minor modes can be enabled
303 individually or in combination. Minor modes would be better named
304 "Generally available, optional feature modes" except that such a name is
307 A minor mode is not usually a modification of single major mode. For
308 example, Auto Fill mode may be used in any major mode that permits text
309 insertion. To be general, a minor mode must be effectively independent
310 of the things major modes do.
312 A minor mode is often much more difficult to implement than a major
313 mode. One reason is that you should be able to activate and deactivate
314 minor modes in any order. A minor mode should be able to have its
315 desired effect regardless of the major mode and regardless of the other
316 minor modes in effect.
318 Often the biggest problem in implementing a minor mode is finding a
319 way to insert the necessary hook into the rest of XEmacs. Minor mode
320 keymaps make this easier than it used to be.
324 * Minor Mode Conventions:: Tips for writing a minor mode.
325 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
328 File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes
330 Conventions for Writing Minor Modes
331 -----------------------------------
333 There are conventions for writing minor modes just as there are for
334 major modes. Several of the major mode conventions apply to minor
335 modes as well: those regarding the name of the mode initialization
336 function, the names of global symbols, and the use of keymaps and other
339 In addition, there are several conventions that are specific to
342 * Make a variable whose name ends in `-mode' to represent the minor
343 mode. Its value should enable or disable the mode (`nil' to
344 disable; anything else to enable.) We call this the "mode
347 This variable is used in conjunction with the `minor-mode-alist' to
348 display the minor mode name in the modeline. It can also enable
349 or disable a minor mode keymap. Individual commands or hooks can
350 also check the variable's value.
352 If you want the minor mode to be enabled separately in each buffer,
353 make the variable buffer-local.
355 * Define a command whose name is the same as the mode variable. Its
356 job is to enable and disable the mode by setting the variable.
358 The command should accept one optional argument. If the argument
359 is `nil', it should toggle the mode (turn it on if it is off, and
360 off if it is on). Otherwise, it should turn the mode on if the
361 argument is a positive integer, a symbol other than `nil' or `-',
362 or a list whose CAR is such an integer or symbol; it should turn
363 the mode off otherwise.
365 Here is an example taken from the definition of
366 `transient-mark-mode'. It shows the use of `transient-mark-mode'
367 as a variable that enables or disables the mode's behavior, and
368 also shows the proper way to toggle, enable or disable the minor
369 mode based on the raw prefix argument value.
371 (setq transient-mark-mode
372 (if (null arg) (not transient-mark-mode)
373 (> (prefix-numeric-value arg) 0)))
375 * Add an element to `minor-mode-alist' for each minor mode (*note
376 Modeline Variables::.). This element should be a list of the
379 (MODE-VARIABLE STRING)
381 Here MODE-VARIABLE is the variable that controls enabling of the
382 minor mode, and STRING is a short string, starting with a space,
383 to represent the mode in the modeline. These strings must be
384 short so that there is room for several of them at once.
386 When you add an element to `minor-mode-alist', use `assq' to check
387 for an existing element, to avoid duplication. For example:
389 (or (assq 'leif-mode minor-mode-alist)
390 (setq minor-mode-alist
391 (cons '(leif-mode " Leif") minor-mode-alist)))
394 File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes
396 Keymaps and Minor Modes
397 -----------------------
399 Each minor mode can have its own keymap, which is active when the
400 mode is enabled. To set up a keymap for a minor mode, add an element
401 to the alist `minor-mode-map-alist'. *Note Active Keymaps::.
403 One use of minor mode keymaps is to modify the behavior of certain
404 self-inserting characters so that they do something else as well as
405 self-insert. In general, this is the only way to do that, since the
406 facilities for customizing `self-insert-command' are limited to special
407 cases (designed for abbrevs and Auto Fill mode). (Do not try
408 substituting your own definition of `self-insert-command' for the
409 standard one. The editor command loop handles this function specially.)
412 File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes
417 Each Emacs window (aside from minibuffer windows) includes a
418 modeline, which displays status information about the buffer displayed
419 in the window. The modeline contains information about the buffer,
420 such as its name, associated file, depth of recursive editing, and the
421 major and minor modes.
423 This section describes how the contents of the modeline are
424 controlled. It is in the chapter on modes because much of the
425 information displayed in the modeline relates to the enabled major and
428 `modeline-format' is a buffer-local variable that holds a template
429 used to display the modeline of the current buffer. All windows for
430 the same buffer use the same `modeline-format' and their modelines
431 appear the same (except for scrolling percentages and line numbers).
433 The modeline of a window is normally updated whenever a different
434 buffer is shown in the window, or when the buffer's modified-status
435 changes from `nil' to `t' or vice-versa. If you modify any of the
436 variables referenced by `modeline-format' (*note Modeline
437 Variables::.), you may want to force an update of the modeline so as to
438 display the new information.
440 - Function: redraw-modeline &optional ALL
441 Force redisplay of the current buffer's modeline. If ALL is
442 non-`nil', then force redisplay of all modelines.
444 The modeline is usually displayed in inverse video. This is
445 controlled using the `modeline' face. *Note Faces::.
449 * Modeline Data:: The data structure that controls the modeline.
450 * Modeline Variables:: Variables used in that data structure.
451 * %-Constructs:: Putting information into a modeline.
454 File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format
456 The Data Structure of the Modeline
457 ----------------------------------
459 The modeline contents are controlled by a data structure of lists,
460 strings, symbols, and numbers kept in the buffer-local variable
461 `mode-line-format'. The data structure is called a "modeline
462 construct", and it is built in recursive fashion out of simpler modeline
463 constructs. The same data structure is used for constructing frame
464 titles (*note Frame Titles::.).
466 - Variable: modeline-format
467 The value of this variable is a modeline construct with overall
468 responsibility for the modeline format. The value of this variable
469 controls which other variables are used to form the modeline text,
470 and where they appear.
472 A modeline construct may be as simple as a fixed string of text, but
473 it usually specifies how to use other variables to construct the text.
474 Many of these variables are themselves defined to have modeline
475 constructs as their values.
477 The default value of `modeline-format' incorporates the values of
478 variables such as `mode-name' and `minor-mode-alist'. Because of this,
479 very few modes need to alter `modeline-format'. For most purposes, it
480 is sufficient to alter the variables referenced by `modeline-format'.
482 A modeline construct may be a list, a symbol, or a string. If the
483 value is a list, each element may be a list, a symbol, or a string.
486 A string as a modeline construct is displayed verbatim in the mode
487 line except for "`%'-constructs". Decimal digits after the `%'
488 specify the field width for space filling on the right (i.e., the
489 data is left justified). *Note %-Constructs::.
492 A symbol as a modeline construct stands for its value. The value
493 of SYMBOL is used as a modeline construct, in place of SYMBOL.
494 However, the symbols `t' and `nil' are ignored; so is any symbol
497 There is one exception: if the value of SYMBOL is a string, it is
498 displayed verbatim: the `%'-constructs are not recognized.
500 `(STRING REST...) or (LIST REST...)'
501 A list whose first element is a string or list means to process
502 all the elements recursively and concatenate the results. This is
503 the most common form of mode line construct.
506 A list whose first element is a symbol is a conditional. Its
507 meaning depends on the value of SYMBOL. If the value is non-`nil',
508 the second element, THEN, is processed recursively as a modeline
509 element. But if the value of SYMBOL is `nil', the third element,
510 ELSE, is processed recursively. You may omit ELSE; then the mode
511 line element displays nothing if the value of SYMBOL is `nil'.
514 A list whose first element is an integer specifies truncation or
515 padding of the results of REST. The remaining elements REST are
516 processed recursively as modeline constructs and concatenated
517 together. Then the result is space filled (if WIDTH is positive)
518 or truncated (to -WIDTH columns, if WIDTH is negative) on the
521 For example, the usual way to show what percentage of a buffer is
522 above the top of the window is to use a list like this: `(-3
525 If you do alter `modeline-format' itself, the new value should use
526 the same variables that appear in the default value (*note Modeline
527 Variables::.), rather than duplicating their contents or displaying the
528 information in another fashion. This way, customizations made by the
529 user or by Lisp programs (such as `display-time' and major modes) via
530 changes to those variables remain effective.
532 Here is an example of a `modeline-format' that might be useful for
533 `shell-mode', since it contains the hostname and default directory.
535 (setq modeline-format
539 (getenv "HOST") ; One element is not constant.
550 '(line-number-mode "L%l--")
555 File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format
557 Variables Used in the Modeline
558 ------------------------------
560 This section describes variables incorporated by the standard value
561 of `modeline-format' into the text of the mode line. There is nothing
562 inherently special about these variables; any other variables could
563 have the same effects on the modeline if `modeline-format' were changed
566 - Variable: modeline-modified
567 This variable holds the value of the modeline construct that
568 displays whether the current buffer is modified.
570 The default value of `modeline-modified' is `("--%1*%1+-")'. This
571 means that the modeline displays `--**-' if the buffer is
572 modified, `-----' if the buffer is not modified, `--%%-' if the
573 buffer is read only, and `--%*--' if the buffer is read only and
576 Changing this variable does not force an update of the modeline.
578 - Variable: modeline-buffer-identification
579 This variable identifies the buffer being displayed in the window.
580 Its default value is `("%F: %17b")', which means that it usually
581 displays `Emacs:' followed by seventeen characters of the buffer
582 name. (In a terminal frame, it displays the frame name instead of
583 `Emacs'; this has the effect of showing the frame number.) You may
584 want to change this in modes such as Rmail that do not behave like
587 - Variable: global-mode-string
588 This variable holds a modeline spec that appears in the mode line
589 by default, just after the buffer name. The command `display-time'
590 sets `global-mode-string' to refer to the variable
591 `display-time-string', which holds a string containing the time and
594 The `%M' construct substitutes the value of `global-mode-string',
595 but this is obsolete, since the variable is included directly in
598 - Variable: mode-name
599 This buffer-local variable holds the "pretty" name of the current
600 buffer's major mode. Each major mode should set this variable so
601 that the mode name will appear in the modeline.
603 - Variable: minor-mode-alist
604 This variable holds an association list whose elements specify how
605 the modeline should indicate that a minor mode is active. Each
606 element of the `minor-mode-alist' should be a two-element list:
608 (MINOR-MODE-VARIABLE MODELINE-STRING)
610 More generally, MODELINE-STRING can be any mode line spec. It
611 appears in the mode line when the value of MINOR-MODE-VARIABLE is
612 non-`nil', and not otherwise. These strings should begin with
613 spaces so that they don't run together. Conventionally, the
614 MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
615 value when that minor mode is activated.
617 The default value of `minor-mode-alist' is:
620 => ((vc-mode vc-mode)
621 (abbrev-mode " Abbrev")
622 (overwrite-mode overwrite-mode)
623 (auto-fill-function " Fill")
624 (defining-kbd-macro " Def")
625 (isearch-mode isearch-mode))
627 `minor-mode-alist' is not buffer-local. The variables mentioned
628 in the alist should be buffer-local if the minor mode can be
629 enabled separately in each buffer.
631 - Variable: modeline-process
632 This buffer-local variable contains the modeline information on
633 process status in modes used for communicating with subprocesses.
634 It is displayed immediately following the major mode name, with no
635 intervening space. For example, its value in the `*shell*' buffer
636 is `(": %s")', which allows the shell to display its status along
637 with the major mode as: `(Shell: run)'. Normally this variable is
640 - Variable: default-modeline-format
641 This variable holds the default `modeline-format' for buffers that
642 do not override it. This is the same as `(default-value
645 The default value of `default-modeline-format' is:
649 modeline-buffer-identification
658 (line-number-mode "L%l--")
663 The variable `vc-mode', local in each buffer, records whether the
664 buffer's visited file is maintained with version control, and, if
665 so, which kind. Its value is `nil' for no version control, or a
666 string that appears in the mode line.
669 File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format
671 `%'-Constructs in the ModeLine
672 ------------------------------
674 The following table lists the recognized `%'-constructs and what
675 they mean. In any construct except `%%', you can add a decimal integer
676 after the `%' to specify how many characters to display.
679 The current buffer name, obtained with the `buffer-name' function.
680 *Note Buffer Names::.
683 The visited file name, obtained with the `buffer-file-name'
684 function. *Note Buffer File Name::.
687 The name of the selected frame.
690 The current column number of point.
693 The current line number of point.
696 `%' if the buffer is read only (see `buffer-read-only');
697 `*' if the buffer is modified (see `buffer-modified-p');
698 `-' otherwise. *Note Buffer Modification::.
701 `*' if the buffer is modified (see `buffer-modified-p');
702 `%' if the buffer is read only (see `buffer-read-only');
703 `-' otherwise. This differs from `%*' only for a modified
704 read-only buffer. *Note Buffer Modification::.
707 `*' if the buffer is modified, and `-' otherwise.
710 The status of the subprocess belonging to the current buffer,
711 obtained with `process-status'. *Note Process Information::.
714 the current line number.
717 the name of the selected frame; this is only meaningful under the
718 X Window System. *Note Frame Name::.
721 Whether the visited file is a text file or a binary file. (This
722 is a meaningful distinction only on certain operating systems.)
725 The percentage of the buffer text above the *top* of window, or
726 `Top', `Bottom' or `All'.
729 The percentage of the buffer text that is above the *bottom* of
730 the window (which includes the text visible in the window, as well
731 as the text above the top), plus `Top' if the top of the buffer is
732 visible on screen; or `Bottom' or `All'.
735 `Narrow' when narrowing is in effect; nothing otherwise (see
736 `narrow-to-region' in *Note Narrowing::).
739 An indication of the depth of recursive editing levels (not
740 counting minibuffer levels): one `[' for each editing level.
741 *Note Recursive Editing::.
744 One `]' for each recursive editing level (not counting minibuffer
748 The character `%'--this is how to include a literal `%' in a
749 string in which `%'-constructs are allowed.
752 Dashes sufficient to fill the remainder of the modeline.
754 The following two `%'-constructs are still supported, but they are
755 obsolete, since you can get the same results with the variables
756 `mode-name' and `global-mode-string'.
759 The value of `mode-name'.
762 The value of `global-mode-string'. Currently, only `display-time'
763 modifies the value of `global-mode-string'.
766 File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
771 A "hook" is a variable where you can store a function or functions
772 to be called on a particular occasion by an existing program. XEmacs
773 provides hooks for the sake of customization. Most often, hooks are set
774 up in the `.emacs' file, but Lisp programs can set them also. *Note
775 Standard Hooks::, for a list of standard hook variables.
777 Most of the hooks in XEmacs are "normal hooks". These variables
778 contain lists of functions to be called with no arguments. The reason
779 most hooks are normal hooks is so that you can use them in a uniform
780 way. You can usually tell when a hook is a normal hook, because its
781 name ends in `-hook'.
783 The recommended way to add a hook function to a normal hook is by
784 calling `add-hook' (see below). The hook functions may be any of the
785 valid kinds of functions that `funcall' accepts (*note What Is a
786 Function::.). Most normal hook variables are initially void;
787 `add-hook' knows how to deal with this.
789 As for abnormal hooks, those whose names end in `-function' have a
790 value that is a single function. Those whose names end in `-hooks'
791 have a value that is a list of functions. Any hook that is abnormal is
792 abnormal because a normal hook won't do the job; either the functions
793 are called with arguments, or their values are meaningful. The name
794 shows you that the hook is abnormal and that you should look at its
795 documentation string to see how to use it properly.
797 Major mode functions are supposed to run a hook called the "mode
798 hook" as the last step of initialization. This makes it easy for a user
799 to customize the behavior of the mode, by overriding the local variable
800 assignments already made by the mode. But hooks are used in other
801 contexts too. For example, the hook `suspend-hook' runs just before
802 XEmacs suspends itself (*note Suspending XEmacs::.).
804 Here's an expression that uses a mode hook to turn on Auto Fill mode
805 when in Lisp Interaction mode:
807 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
809 The next example shows how to use a hook to customize the way XEmacs
810 formats C code. (People often have strong personal preferences for one
811 format or another.) Here the hook function is an anonymous lambda
814 (add-hook 'c-mode-hook
816 (setq c-indent-level 4
819 c-continued-statement-indent 0
821 comment-column 40))))
823 (setq c++-mode-hook c-mode-hook)
825 The final example shows how the appearance of the modeline can be
826 modified for a particular class of buffers only.
828 (add-hook 'text-mode-hook
830 (setq modeline-format
846 At the appropriate time, XEmacs uses the `run-hooks' function to run
847 particular hooks. This function calls the hook functions you have
848 added with `add-hooks'.
850 - Function: run-hooks &rest HOOKVAR
851 This function takes one or more hook variable names as arguments,
852 and runs each hook in turn. Each HOOKVAR argument should be a
853 symbol that is a hook variable. These arguments are processed in
856 If a hook variable has a non-`nil' value, that value may be a
857 function or a list of functions. If the value is a function
858 (either a lambda expression or a symbol with a function
859 definition), it is called. If it is a list, the elements are
860 called, in order. The hook functions are called with no arguments.
862 For example, here's how `emacs-lisp-mode' runs its mode hook:
864 (run-hooks 'emacs-lisp-mode-hook)
866 - Function: add-hook HOOK FUNCTION &optional APPEND LOCAL
867 This function is the handy way to add function FUNCTION to hook
868 variable HOOK. The argument FUNCTION may be any valid Lisp
869 function with the proper number of arguments. For example,
871 (add-hook 'text-mode-hook 'my-text-hook-function)
873 adds `my-text-hook-function' to the hook called `text-mode-hook'.
875 You can use `add-hook' for abnormal hooks as well as for normal
878 It is best to design your hook functions so that the order in
879 which they are executed does not matter. Any dependence on the
880 order is "asking for trouble." However, the order is predictable:
881 normally, FUNCTION goes at the front of the hook list, so it will
882 be executed first (barring another `add-hook' call).
884 If the optional argument APPEND is non-`nil', the new hook
885 function goes at the end of the hook list and will be executed
888 If LOCAL is non-`nil', that says to make the new hook function
889 local to the current buffer. Before you can do this, you must
890 make the hook itself buffer-local by calling `make-local-hook'
891 (*not* `make-local-variable'). If the hook itself is not
892 buffer-local, then the value of LOCAL makes no difference--the
893 hook function is always global.
895 - Function: remove-hook HOOK FUNCTION &optional LOCAL
896 This function removes FUNCTION from the hook variable HOOK.
898 If LOCAL is non-`nil', that says to remove FUNCTION from the local
899 hook list instead of from the global hook list. If the hook
900 itself is not buffer-local, then the value of LOCAL makes no
903 - Function: make-local-hook HOOK
904 This function makes the hook variable `hook' local to the current
905 buffer. When a hook variable is local, it can have local and
906 global hook functions, and `run-hooks' runs all of them.
908 This function works by making `t' an element of the buffer-local
909 value. That serves as a flag to use the hook functions in the
910 default value of the hook variable as well as those in the local
911 value. Since `run-hooks' understands this flag, `make-local-hook'
912 works with all normal hooks. It works for only some non-normal
913 hooks--those whose callers have been updated to understand this
916 Do not use `make-local-variable' directly for hook variables; it is
920 File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
925 XEmacs Lisp has convenient on-line help facilities, most of which
926 derive their information from the documentation strings associated with
927 functions and variables. This chapter describes how to write good
928 documentation strings for your Lisp programs, as well as how to write
929 programs to access documentation.
931 Note that the documentation strings for XEmacs are not the same thing
932 as the XEmacs manual. Manuals have their own source files, written in
933 the Texinfo language; documentation strings are specified in the
934 definitions of the functions and variables they apply to. A collection
935 of documentation strings is not sufficient as a manual because a good
936 manual is not organized in that fashion; it is organized in terms of
937 topics of discussion.
941 * Documentation Basics:: Good style for doc strings.
942 Where to put them. How XEmacs stores them.
943 * Accessing Documentation:: How Lisp programs can access doc strings.
944 * Keys in Documentation:: Substituting current key bindings.
945 * Describing Characters:: Making printable descriptions of
946 non-printing characters and key sequences.
947 * Help Functions:: Subroutines used by XEmacs help facilities.
948 * Obsoleteness:: Upgrading Lisp functionality over time.
951 File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
956 A documentation string is written using the Lisp syntax for strings,
957 with double-quote characters surrounding the text of the string. This
958 is because it really is a Lisp string object. The string serves as
959 documentation when it is written in the proper place in the definition
960 of a function or variable. In a function definition, the documentation
961 string follows the argument list. In a variable definition, the
962 documentation string follows the initial value of the variable.
964 When you write a documentation string, make the first line a complete
965 sentence (or two complete sentences) since some commands, such as
966 `apropos', show only the first line of a multi-line documentation
967 string. Also, you should not indent the second line of a documentation
968 string, if you have one, because that looks odd when you use `C-h f'
969 (`describe-function') or `C-h v' (`describe-variable'). *Note
970 Documentation Tips::.
972 Documentation strings may contain several special substrings, which
973 stand for key bindings to be looked up in the current keymaps when the
974 documentation is displayed. This allows documentation strings to refer
975 to the keys for related commands and be accurate even when a user
976 rearranges the key bindings. (*Note Accessing Documentation::.)
978 Within the Lisp world, a documentation string is accessible through
979 the function or variable that it describes:
981 * The documentation for a function is stored in the function
982 definition itself (*note Lambda Expressions::.). The function
983 `documentation' knows how to extract it.
985 * The documentation for a variable is stored in the variable's
986 property list under the property name `variable-documentation'.
987 The function `documentation-property' knows how to extract it.
989 To save space, the documentation for preloaded functions and
990 variables (including primitive functions and autoloaded functions) is
991 stored in the "internal doc file" `DOC'. The documentation for
992 functions and variables loaded during the XEmacs session from
993 byte-compiled files is stored in those very same byte-compiled files
994 (*note Docs and Compilation::.).
996 XEmacs does not keep documentation strings in memory unless
997 necessary. Instead, XEmacs maintains, for preloaded symbols, an
998 integer offset into the internal doc file, and for symbols loaded from
999 byte-compiled files, a list containing the filename of the
1000 byte-compiled file and an integer offset, in place of the documentation
1001 string. The functions `documentation' and `documentation-property' use
1002 that information to read the documentation from the appropriate file;
1003 this is transparent to the user.
1005 For information on the uses of documentation strings, see *Note
1008 The `emacs/lib-src' directory contains two utilities that you can
1009 use to print nice-looking hardcopy for the file
1010 `emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'.
1013 File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
1015 Access to Documentation Strings
1016 ===============================
1018 - Function: documentation-property SYMBOL PROPERTY &optional VERBATIM
1019 This function returns the documentation string that is recorded in
1020 SYMBOL's property list under property PROPERTY. It retrieves the
1021 text from a file if necessary, and runs `substitute-command-keys'
1022 to substitute actual key bindings. (This substitution is not done
1023 if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
1026 (documentation-property 'command-line-processed
1027 'variable-documentation)
1028 => "t once command line has been processed"
1030 (symbol-plist 'command-line-processed)
1031 => (variable-documentation 188902)
1033 - Function: documentation FUNCTION &optional VERBATIM
1034 This function returns the documentation string of FUNCTION. It
1035 reads the text from a file if necessary. Then (unless VERBATIM is
1036 non-`nil') it calls `substitute-command-keys', to return a value
1037 containing the actual (current) key bindings.
1039 The function `documentation' signals a `void-function' error if
1040 FUNCTION has no function definition. However, it is ok if the
1041 function definition has no documentation string. In that case,
1042 `documentation' returns `nil'.
1044 Here is an example of using the two functions, `documentation' and
1045 `documentation-property', to display the documentation strings for
1046 several symbols in a `*Help*' buffer.
1048 (defun describe-symbols (pattern)
1049 "Describe the XEmacs Lisp symbols matching PATTERN.
1050 All symbols that have PATTERN in their name are described
1051 in the `*Help*' buffer."
1052 (interactive "sDescribe symbols matching: ")
1053 (let ((describe-func
1057 ;; Print description of symbol.
1058 (if (fboundp s) ; It is a function.
1060 (format "%s\t%s\n%s\n\n" s
1062 (let ((keys (where-is-internal s)))
1066 (mapconcat 'key-description
1071 (or (documentation s)
1072 "not documented"))))
1074 (if (boundp s) ; It is a variable.
1077 (format "%s\t%s\n%s\n\n" s
1078 (if (user-variable-p s)
1079 "Option " "Variable")
1081 (or (documentation-property
1082 s 'variable-documentation)
1083 "not documented")))))))
1086 ;; Build a list of symbols that match pattern.
1089 (if (string-match pattern (symbol-name sym))
1090 (setq sym-list (cons sym sym-list))))))
1092 ;; Display the data.
1093 (with-output-to-temp-buffer "*Help*"
1094 (mapcar describe-func (sort sym-list 'string<))
1095 (print-help-return-message))))
1097 The `describe-symbols' function works like `apropos', but provides
1100 (describe-symbols "goal")
1102 ---------- Buffer: *Help* ----------
1104 *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
1106 set-goal-column Command: C-x C-n
1107 Set the current horizontal position as a goal for C-n and C-p.
1109 Those commands will move to this position in the line moved to
1110 rather than trying to keep the same horizontal position.
1111 With a non-nil argument, clears out the goal column
1112 so that C-n and C-p resume vertical motion.
1113 The goal column is stored in the variable `goal-column'.
1115 temporary-goal-column Variable
1116 Current goal column for vertical motion.
1117 It is the column where point was
1118 at the start of current run of vertical motion commands.
1119 When the `track-eol' feature is doing its job, the value is 9999.
1120 ---------- Buffer: *Help* ----------
1122 - Function: Snarf-documentation FILENAME
1123 This function is used only during XEmacs initialization, just
1124 before the runnable XEmacs is dumped. It finds the file offsets
1125 of the documentation strings stored in the file FILENAME, and
1126 records them in the in-core function definitions and variable
1127 property lists in place of the actual strings. *Note Building
1130 XEmacs finds the file FILENAME in the `lib-src' directory. When
1131 the dumped XEmacs is later executed, the same file is found in the
1132 directory `doc-directory'. The usual value for FILENAME is `DOC',
1133 but this can be changed by modifying the variable
1134 `internal-doc-file-name'.
1136 - Variable: internal-doc-file-name
1137 This variable holds the name of the file containing documentation
1138 strings of built-in symbols, usually `DOC'. The full pathname of
1139 the internal doc file is `(concat doc-directory
1140 internal-doc-file-name)'.
1142 - Variable: doc-directory
1143 This variable holds the name of the directory which contains the
1144 "internal doc file" that contains documentation strings for
1145 built-in and preloaded functions and variables.
1147 In most cases, this is the same as `exec-directory'. They may be
1148 different when you run XEmacs from the directory where you built
1149 it, without actually installing it. See `exec-directory' in *Note
1152 In older Emacs versions, `exec-directory' was used for this.
1154 - Variable: data-directory
1155 This variable holds the name of the directory in which XEmacs finds
1156 certain system independent documentation and text files that come
1157 with XEmacs. In older Emacs versions, `exec-directory' was used