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: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes
55 Getting Help about a Major Mode
56 -------------------------------
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.
63 - Command: describe-mode
64 This function displays the documentation of the current major mode.
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::.)
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
79 File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes
81 Defining Derived Modes
82 ----------------------
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'.
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.
91 The new command VARIANT is defined to call the function PARENT,
92 then override certain aspects of that parent mode:
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.
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
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
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
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
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.
122 Here is a hypothetical example:
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))
130 (define-key hypertext-mode-map
131 [down-mouse-3] 'do-hyper-link)
134 File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes
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
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.
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.
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.
162 * Minor Mode Conventions:: Tips for writing a minor mode.
163 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
166 File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes
168 Conventions for Writing Minor Modes
169 -----------------------------------
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
177 In addition, there are several conventions that are specific to
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
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.
190 If you want the minor mode to be enabled separately in each buffer,
191 make the variable buffer-local.
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.
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.
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.
209 (setq transient-mark-mode
210 (if (null arg) (not transient-mark-mode)
211 (> (prefix-numeric-value arg) 0)))
213 * Add an element to `minor-mode-alist' for each minor mode (*note
214 Modeline Variables::). This element should be a list of the
217 (MODE-VARIABLE STRING)
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.
224 When you add an element to `minor-mode-alist', use `assq' to check
225 for an existing element, to avoid duplication. For example:
227 (or (assq 'leif-mode minor-mode-alist)
228 (setq minor-mode-alist
229 (cons '(leif-mode " Leif") minor-mode-alist)))
232 File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes
234 Keymaps and Minor Modes
235 -----------------------
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::.
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.)
250 File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes
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.
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
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).
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
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.
282 The modeline is usually displayed in inverse video. This is
283 controlled using the `modeline' face. *Note Faces::.
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.
292 File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format
294 The Data Structure of the Modeline
295 ----------------------------------
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::).
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.
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.
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'.
320 A modeline construct may be a string, symbol, glyph, generic
321 specifier, list or cons cell.
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::.
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.
335 There is one exception: if the value of SYMBOL is a string, it is
336 displayed verbatim: the `%'-constructs are not recognized.
339 A glyph is displayed as is.
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.
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.
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'.
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
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
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.
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.
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.
393 (setq modeline-format
397 (getenv "HOST") ; One element is not constant.
408 '(line-number-mode "L%l--")
413 File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format
415 Variables Used in the Modeline
416 ------------------------------
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
424 - Variable: modeline-modified
425 This variable holds the value of the modeline construct that
426 displays whether the current buffer is modified.
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
434 Changing this variable does not force an update of the modeline.
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
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
452 The `%M' construct substitutes the value of `global-mode-string',
453 but this is obsolete, since the variable is included directly in
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.
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:
466 (MINOR-MODE-VARIABLE MODELINE-STRING)
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.
475 The default value of `minor-mode-alist' is:
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))
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.
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
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
503 The default value of `default-modeline-format' is:
507 modeline-buffer-identification
516 (line-number-mode "L%l--")
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.
527 File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format
529 `%'-Constructs in the ModeLine
530 ------------------------------
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.
537 The current buffer name, obtained with the `buffer-name' function.
538 *Note Buffer Names::.
541 The visited file name, obtained with the `buffer-file-name'
542 function. *Note Buffer File Name::.
545 The name of the selected frame.
548 The current column number of point.
551 The current line number of point.
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::.
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::.
565 `*' if the buffer is modified, and `-' otherwise.
568 The status of the subprocess belonging to the current buffer,
569 obtained with `process-status'. *Note Process Information::.
572 The current line number.
575 The name of the selected frame; this is only meaningful under the
576 X Window System. *Note Frame Name::.
579 Whether the visited file is a text file or a binary file. (This
580 is a meaningful distinction only on certain operating systems.)
583 The percentage of the buffer text above the *top* of window, or
584 `Top', `Bottom' or `All'.
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'.
593 `Narrow' when narrowing is in effect; nothing otherwise (see
594 `narrow-to-region' in *Note Narrowing::).
597 Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.
600 An indication of the depth of recursive editing levels (not
601 counting minibuffer levels): one `[' for each editing level.
602 *Note Recursive Editing::.
605 One `]' for each recursive editing level (not counting minibuffer
609 The character `%'--this is how to include a literal `%' in a
610 string in which `%'-constructs are allowed.
613 Dashes sufficient to fill the remainder of the modeline.
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'.
620 The value of `mode-name'.
623 The value of `global-mode-string'. Currently, only `display-time'
624 modifies the value of `global-mode-string'.
627 File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
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.
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'.
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.
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.
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::).
665 Here's an expression that uses a mode hook to turn on Auto Fill mode
666 when in Lisp Interaction mode:
668 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
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
675 (add-hook 'c-mode-hook
677 (setq c-indent-level 4
680 c-continued-statement-indent 0
682 comment-column 40))))
684 (setq c++-mode-hook c-mode-hook)
686 The final example shows how the appearance of the modeline can be
687 modified for a particular class of buffers only.
689 (add-hook 'text-mode-hook
691 (setq modeline-format
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'.
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
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.
723 For example, here's how `emacs-lisp-mode' runs its mode hook:
725 (run-hooks 'emacs-lisp-mode-hook)
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,
732 (add-hook 'text-mode-hook 'my-text-hook-function)
734 adds `my-text-hook-function' to the hook called `text-mode-hook'.
736 You can use `add-hook' for abnormal hooks as well as for normal
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).
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
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.
756 - Function: remove-hook hook function &optional local
757 This function removes FUNCTION from the hook variable HOOK.
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
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.
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
777 Do not use `make-local-variable' directly for hook variables; it is
781 File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
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.
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.
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.
812 File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
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.
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::.
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::.)
839 Within the Lisp world, a documentation string is accessible through
840 the function or variable that it describes:
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.
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.
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::).
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.
866 For information on the uses of documentation strings, see *Note
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'.
874 File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
876 Access to Documentation Strings
877 ===============================
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
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)
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.
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'.
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.
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: ")
916 ;; Print description of symbol.
917 (if (fboundp s) ; It is a function.
919 (format "%s\t%s\n%s\n\n" s
921 (let ((keys (where-is-internal s)))
925 (mapconcat 'key-description
929 (or (documentation s)
932 (if (boundp s) ; It is a variable.
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")))))))
942 ;; Build a list of symbols that match pattern.
945 (if (string-match pattern (symbol-name sym))
946 (setq sym-list (cons sym sym-list))))))
949 (with-output-to-temp-buffer "*Help*"
950 (mapcar describe-func (sort sym-list 'string<))
951 (print-help-return-message))))
953 The `describe-symbols' function works like `apropos', but provides
956 (describe-symbols "goal")
958 ---------- Buffer: *Help* ----------
960 *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
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'.
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* ----------
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
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'.
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)'.
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.
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
1007 In older Emacs versions, `exec-directory' was used for this.
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
1016 File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
1018 Substituting Key Bindings in Documentation
1019 ==========================================
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.
1028 Here is a list of the special sequences and what they mean:
1031 stands for a key sequence that will invoke COMMAND, or `M-x
1032 COMMAND' if COMMAND has no key bindings.
1035 stands for a summary of the value of MAPVAR, which should be a
1036 keymap. The summary is made by `describe-bindings'.
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.
1044 quotes the following character and is discarded; this `\=\=' puts
1045 `\=' into the output, and `\=\[' puts `\[' into the output.
1047 *Please note:* Each `\' must be doubled when written in a string in
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.
1056 Here are examples of the special sequences:
1058 (substitute-command-keys
1059 "To abort recursive edit, type: \\[abort-recursive-edit]")
1060 => "To abort recursive edit, type: C-]"
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:
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
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."
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."
1097 File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
1099 Describing Characters for Help Messages
1100 =======================================
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.
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.
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.
1125 (single-key-description ?\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)
1131 (single-key-description '(shift button1))
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).
1141 (text-char-description ?\C-c)
1143 (text-char-description ?\M-m)
1145 (text-char-description ?\C-\M-m)