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: %-Constructs, Prev: Modeline Variables, Up: Modeline Format
55 `%'-Constructs in the ModeLine
56 ------------------------------
58 The following table lists the recognized `%'-constructs and what
59 they mean. In any construct except `%%', you can add a decimal integer
60 after the `%' to specify how many characters to display.
63 The current buffer name, obtained with the `buffer-name' function.
67 The visited file name, obtained with the `buffer-file-name'
68 function. *Note Buffer File Name::.
71 The name of the selected frame.
74 The current column number of point.
77 The current line number of point.
80 `%' if the buffer is read only (see `buffer-read-only');
81 `*' if the buffer is modified (see `buffer-modified-p');
82 `-' otherwise. *Note Buffer Modification::.
85 `*' if the buffer is modified (see `buffer-modified-p');
86 `%' if the buffer is read only (see `buffer-read-only');
87 `-' otherwise. This differs from `%*' only for a modified
88 read-only buffer. *Note Buffer Modification::.
91 `*' if the buffer is modified, and `-' otherwise.
94 The status of the subprocess belonging to the current buffer,
95 obtained with `process-status'. *Note Process Information::.
98 The current line number.
101 The name of the selected frame; this is only meaningful under the
102 X Window System. *Note Frame Name::.
105 Whether the visited file is a text file or a binary file. (This
106 is a meaningful distinction only on certain operating systems.)
109 The percentage of the buffer text above the *top* of window, or
110 `Top', `Bottom' or `All'.
113 The percentage of the buffer text that is above the *bottom* of
114 the window (which includes the text visible in the window, as well
115 as the text above the top), plus `Top' if the top of the buffer is
116 visible on screen; or `Bottom' or `All'.
119 `Narrow' when narrowing is in effect; nothing otherwise (see
120 `narrow-to-region' in *Note Narrowing::).
123 Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.
126 An indication of the depth of recursive editing levels (not
127 counting minibuffer levels): one `[' for each editing level.
128 *Note Recursive Editing::.
131 One `]' for each recursive editing level (not counting minibuffer
135 The character `%'--this is how to include a literal `%' in a
136 string in which `%'-constructs are allowed.
139 Dashes sufficient to fill the remainder of the modeline.
141 The following two `%'-constructs are still supported, but they are
142 obsolete, since you can get the same results with the variables
143 `mode-name' and `global-mode-string'.
146 The value of `mode-name'.
149 The value of `global-mode-string'. Currently, only `display-time'
150 modifies the value of `global-mode-string'.
153 File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
158 A "hook" is a variable where you can store a function or functions
159 to be called on a particular occasion by an existing program. XEmacs
160 provides hooks for the sake of customization. Most often, hooks are set
161 up in the `.emacs' file, but Lisp programs can set them also. *Note
162 Standard Hooks::, for a list of standard hook variables.
164 Most of the hooks in XEmacs are "normal hooks". These variables
165 contain lists of functions to be called with no arguments. The reason
166 most hooks are normal hooks is so that you can use them in a uniform
167 way. You can usually tell when a hook is a normal hook, because its
168 name ends in `-hook'.
170 The recommended way to add a hook function to a normal hook is by
171 calling `add-hook' (see below). The hook functions may be any of the
172 valid kinds of functions that `funcall' accepts (*note What Is a
173 Function::). Most normal hook variables are initially void; `add-hook'
174 knows how to deal with this.
176 As for abnormal hooks, those whose names end in `-function' have a
177 value that is a single function. Those whose names end in `-hooks'
178 have a value that is a list of functions. Any hook that is abnormal is
179 abnormal because a normal hook won't do the job; either the functions
180 are called with arguments, or their values are meaningful. The name
181 shows you that the hook is abnormal and that you should look at its
182 documentation string to see how to use it properly.
184 Major mode functions are supposed to run a hook called the "mode
185 hook" as the last step of initialization. This makes it easy for a user
186 to customize the behavior of the mode, by overriding the local variable
187 assignments already made by the mode. But hooks are used in other
188 contexts too. For example, the hook `suspend-hook' runs just before
189 XEmacs suspends itself (*note Suspending XEmacs::).
191 Here's an expression that uses a mode hook to turn on Auto Fill mode
192 when in Lisp Interaction mode:
194 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
196 The next example shows how to use a hook to customize the way XEmacs
197 formats C code. (People often have strong personal preferences for one
198 format or another.) Here the hook function is an anonymous lambda
201 (add-hook 'c-mode-hook
203 (setq c-indent-level 4
206 c-continued-statement-indent 0
208 comment-column 40))))
210 (setq c++-mode-hook c-mode-hook)
212 The final example shows how the appearance of the modeline can be
213 modified for a particular class of buffers only.
215 (add-hook 'text-mode-hook
217 (setq modeline-format
233 At the appropriate time, XEmacs uses the `run-hooks' function to run
234 particular hooks. This function calls the hook functions you have
235 added with `add-hooks'.
237 - Function: run-hooks &rest hookvar
238 This function takes one or more hook variable names as arguments,
239 and runs each hook in turn. Each HOOKVAR argument should be a
240 symbol that is a hook variable. These arguments are processed in
243 If a hook variable has a non-`nil' value, that value may be a
244 function or a list of functions. If the value is a function
245 (either a lambda expression or a symbol with a function
246 definition), it is called. If it is a list, the elements are
247 called, in order. The hook functions are called with no arguments.
249 For example, here's how `emacs-lisp-mode' runs its mode hook:
251 (run-hooks 'emacs-lisp-mode-hook)
253 - Function: add-hook hook function &optional append local
254 This function is the handy way to add function FUNCTION to hook
255 variable HOOK. The argument FUNCTION may be any valid Lisp
256 function with the proper number of arguments. For example,
258 (add-hook 'text-mode-hook 'my-text-hook-function)
260 adds `my-text-hook-function' to the hook called `text-mode-hook'.
262 You can use `add-hook' for abnormal hooks as well as for normal
265 It is best to design your hook functions so that the order in
266 which they are executed does not matter. Any dependence on the
267 order is "asking for trouble." However, the order is predictable:
268 normally, FUNCTION goes at the front of the hook list, so it will
269 be executed first (barring another `add-hook' call).
271 If the optional argument APPEND is non-`nil', the new hook
272 function goes at the end of the hook list and will be executed
275 If LOCAL is non-`nil', that says to make the new hook function
276 local to the current buffer. Before you can do this, you must
277 make the hook itself buffer-local by calling `make-local-hook'
278 (*not* `make-local-variable'). If the hook itself is not
279 buffer-local, then the value of LOCAL makes no difference--the
280 hook function is always global.
282 - Function: remove-hook hook function &optional local
283 This function removes FUNCTION from the hook variable HOOK.
285 If LOCAL is non-`nil', that says to remove FUNCTION from the local
286 hook list instead of from the global hook list. If the hook
287 itself is not buffer-local, then the value of LOCAL makes no
290 - Function: make-local-hook hook
291 This function makes the hook variable `hook' local to the current
292 buffer. When a hook variable is local, it can have local and
293 global hook functions, and `run-hooks' runs all of them.
295 This function works by making `t' an element of the buffer-local
296 value. That serves as a flag to use the hook functions in the
297 default value of the hook variable as well as those in the local
298 value. Since `run-hooks' understands this flag, `make-local-hook'
299 works with all normal hooks. It works for only some non-normal
300 hooks--those whose callers have been updated to understand this
303 Do not use `make-local-variable' directly for hook variables; it is
307 File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
312 XEmacs Lisp has convenient on-line help facilities, most of which
313 derive their information from the documentation strings associated with
314 functions and variables. This chapter describes how to write good
315 documentation strings for your Lisp programs, as well as how to write
316 programs to access documentation.
318 Note that the documentation strings for XEmacs are not the same thing
319 as the XEmacs manual. Manuals have their own source files, written in
320 the Texinfo language; documentation strings are specified in the
321 definitions of the functions and variables they apply to. A collection
322 of documentation strings is not sufficient as a manual because a good
323 manual is not organized in that fashion; it is organized in terms of
324 topics of discussion.
328 * Documentation Basics:: Good style for doc strings.
329 Where to put them. How XEmacs stores them.
330 * Accessing Documentation:: How Lisp programs can access doc strings.
331 * Keys in Documentation:: Substituting current key bindings.
332 * Describing Characters:: Making printable descriptions of
333 non-printing characters and key sequences.
334 * Help Functions:: Subroutines used by XEmacs help facilities.
335 * Obsoleteness:: Upgrading Lisp functionality over time.
338 File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
343 A documentation string is written using the Lisp syntax for strings,
344 with double-quote characters surrounding the text of the string. This
345 is because it really is a Lisp string object. The string serves as
346 documentation when it is written in the proper place in the definition
347 of a function or variable. In a function definition, the documentation
348 string follows the argument list. In a variable definition, the
349 documentation string follows the initial value of the variable.
351 When you write a documentation string, make the first line a complete
352 sentence (or two complete sentences) since some commands, such as
353 `apropos', show only the first line of a multi-line documentation
354 string. Also, you should not indent the second line of a documentation
355 string, if you have one, because that looks odd when you use `C-h f'
356 (`describe-function') or `C-h v' (`describe-variable'). *Note
357 Documentation Tips::.
359 Documentation strings may contain several special substrings, which
360 stand for key bindings to be looked up in the current keymaps when the
361 documentation is displayed. This allows documentation strings to refer
362 to the keys for related commands and be accurate even when a user
363 rearranges the key bindings. (*Note Accessing Documentation::.)
365 Within the Lisp world, a documentation string is accessible through
366 the function or variable that it describes:
368 * The documentation for a function is stored in the function
369 definition itself (*note Lambda Expressions::). The function
370 `documentation' knows how to extract it.
372 * The documentation for a variable is stored in the variable's
373 property list under the property name `variable-documentation'.
374 The function `documentation-property' knows how to extract it.
376 To save space, the documentation for preloaded functions and
377 variables (including primitive functions and autoloaded functions) is
378 stored in the "internal doc file" `DOC'. The documentation for
379 functions and variables loaded during the XEmacs session from
380 byte-compiled files is stored in those very same byte-compiled files
381 (*note Docs and Compilation::).
383 XEmacs does not keep documentation strings in memory unless
384 necessary. Instead, XEmacs maintains, for preloaded symbols, an
385 integer offset into the internal doc file, and for symbols loaded from
386 byte-compiled files, a list containing the filename of the
387 byte-compiled file and an integer offset, in place of the documentation
388 string. The functions `documentation' and `documentation-property' use
389 that information to read the documentation from the appropriate file;
390 this is transparent to the user.
392 For information on the uses of documentation strings, see *Note
395 The `emacs/lib-src' directory contains two utilities that you can
396 use to print nice-looking hardcopy for the file
397 `emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'.
400 File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
402 Access to Documentation Strings
403 ===============================
405 - Function: documentation-property symbol property &optional verbatim
406 This function returns the documentation string that is recorded in
407 SYMBOL's property list under property PROPERTY. It retrieves the
408 text from a file if necessary, and runs `substitute-command-keys'
409 to substitute actual key bindings. (This substitution is not done
410 if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
413 (documentation-property 'command-line-processed
414 'variable-documentation)
415 => "t once command line has been processed"
416 (symbol-plist 'command-line-processed)
417 => (variable-documentation 188902)
419 - Function: documentation function &optional verbatim
420 This function returns the documentation string of FUNCTION. It
421 reads the text from a file if necessary. Then (unless VERBATIM is
422 non-`nil') it calls `substitute-command-keys', to return a value
423 containing the actual (current) key bindings.
425 The function `documentation' signals a `void-function' error if
426 FUNCTION has no function definition. However, it is ok if the
427 function definition has no documentation string. In that case,
428 `documentation' returns `nil'.
430 Here is an example of using the two functions, `documentation' and
431 `documentation-property', to display the documentation strings for
432 several symbols in a `*Help*' buffer.
434 (defun describe-symbols (pattern)
435 "Describe the XEmacs Lisp symbols matching PATTERN.
436 All symbols that have PATTERN in their name are described
437 in the `*Help*' buffer."
438 (interactive "sDescribe symbols matching: ")
442 ;; Print description of symbol.
443 (if (fboundp s) ; It is a function.
445 (format "%s\t%s\n%s\n\n" s
447 (let ((keys (where-is-internal s)))
451 (mapconcat 'key-description
455 (or (documentation s)
458 (if (boundp s) ; It is a variable.
460 (format "%s\t%s\n%s\n\n" s
461 (if (user-variable-p s)
462 "Option " "Variable")
463 (or (documentation-property
464 s 'variable-documentation)
465 "not documented")))))))
468 ;; Build a list of symbols that match pattern.
471 (if (string-match pattern (symbol-name sym))
472 (setq sym-list (cons sym sym-list))))))
475 (with-output-to-temp-buffer "*Help*"
476 (mapcar describe-func (sort sym-list 'string<))
477 (print-help-return-message))))
479 The `describe-symbols' function works like `apropos', but provides
482 (describe-symbols "goal")
484 ---------- Buffer: *Help* ----------
486 *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
488 set-goal-column Command: C-x C-n
489 Set the current horizontal position as a goal for C-n and C-p.
490 Those commands will move to this position in the line moved to
491 rather than trying to keep the same horizontal position.
492 With a non-nil argument, clears out the goal column
493 so that C-n and C-p resume vertical motion.
494 The goal column is stored in the variable `goal-column'.
496 temporary-goal-column Variable
497 Current goal column for vertical motion.
498 It is the column where point was
499 at the start of current run of vertical motion commands.
500 When the `track-eol' feature is doing its job, the value is 9999.
501 ---------- Buffer: *Help* ----------
503 - Function: Snarf-documentation filename
504 This function is used only during XEmacs initialization, just
505 before the runnable XEmacs is dumped. It finds the file offsets
506 of the documentation strings stored in the file FILENAME, and
507 records them in the in-core function definitions and variable
508 property lists in place of the actual strings. *Note Building
511 XEmacs finds the file FILENAME in the `lib-src' directory. When
512 the dumped XEmacs is later executed, the same file is found in the
513 directory `doc-directory'. The usual value for FILENAME is `DOC',
514 but this can be changed by modifying the variable
515 `internal-doc-file-name'.
517 - Variable: internal-doc-file-name
518 This variable holds the name of the file containing documentation
519 strings of built-in symbols, usually `DOC'. The full pathname of
520 the internal doc file is `(concat doc-directory
521 internal-doc-file-name)'.
523 - Variable: doc-directory
524 This variable holds the name of the directory which contains the
525 "internal doc file" that contains documentation strings for
526 built-in and preloaded functions and variables.
528 In most cases, this is the same as `exec-directory'. They may be
529 different when you run XEmacs from the directory where you built
530 it, without actually installing it. See `exec-directory' in *Note
533 In older Emacs versions, `exec-directory' was used for this.
535 - Variable: data-directory
536 This variable holds the name of the directory in which XEmacs finds
537 certain system independent documentation and text files that come
538 with XEmacs. In older Emacs versions, `exec-directory' was used
542 File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
544 Substituting Key Bindings in Documentation
545 ==========================================
547 When documentation strings refer to key sequences, they should use
548 the current, actual key bindings. They can do so using certain special
549 text sequences described below. Accessing documentation strings in the
550 usual way substitutes current key binding information for these special
551 sequences. This works by calling `substitute-command-keys'. You can
552 also call that function yourself.
554 Here is a list of the special sequences and what they mean:
557 stands for a key sequence that will invoke COMMAND, or `M-x
558 COMMAND' if COMMAND has no key bindings.
561 stands for a summary of the value of MAPVAR, which should be a
562 keymap. The summary is made by `describe-bindings'.
565 stands for no text itself. It is used for a side effect: it
566 specifies MAPVAR as the keymap for any following `\[COMMAND]'
567 sequences in this documentation string.
570 quotes the following character and is discarded; this `\=\=' puts
571 `\=' into the output, and `\=\[' puts `\[' into the output.
573 *Please note:* Each `\' must be doubled when written in a string in
576 - Function: substitute-command-keys string
577 This function scans STRING for the above special sequences and
578 replaces them by what they stand for, returning the result as a
579 string. This permits display of documentation that refers
580 accurately to the user's own customized key bindings.
582 Here are examples of the special sequences:
584 (substitute-command-keys
585 "To abort recursive edit, type: \\[abort-recursive-edit]")
586 => "To abort recursive edit, type: C-]"
588 (substitute-command-keys
589 "The keys that are defined for the minibuffer here are:
590 \\{minibuffer-local-must-match-map}")
591 => "The keys that are defined for the minibuffer here are:
593 ? minibuffer-completion-help
594 SPC minibuffer-complete-word
595 TAB minibuffer-complete
596 LFD minibuffer-complete-and-exit
597 RET minibuffer-complete-and-exit
598 C-g abort-recursive-edit
601 (substitute-command-keys
602 "To abort a recursive edit from the minibuffer, type\
603 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
604 => "To abort a recursive edit from the minibuffer, type C-g."
606 (substitute-command-keys
607 "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
608 \(made by describe-bindings) of the value of MAPVAR, taken as a keymap.
609 Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
610 as the keymap for future \\=\\[COMMAND] substrings.
611 \\=\\= quotes the following character and is discarded;
612 thus, \\=\\=\\=\\= puts \\=\\= into the output,
613 and \\=\\=\\=\\[ puts \\=\\[ into the output.")
614 => "Substrings of the form \{MAPVAR} are replaced by summaries
615 (made by describe-bindings) of the value of MAPVAR, taken as a keymap.
616 Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
617 as the keymap for future \[COMMAND] substrings.
618 \= quotes the following character and is discarded;
619 thus, \=\= puts \= into the output,
620 and \=\[ puts \[ into the output."
623 File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
625 Describing Characters for Help Messages
626 =======================================
628 These functions convert events, key sequences or characters to
629 textual descriptions. These descriptions are useful for including
630 arbitrary text characters or key sequences in messages, because they
631 convert non-printing and whitespace characters to sequences of printing
632 characters. The description of a non-whitespace printing character is
633 the character itself.
635 - Function: key-description sequence
636 This function returns a string containing the XEmacs standard
637 notation for the input events in SEQUENCE. The argument SEQUENCE
638 may be a string, vector or list. *Note Events::, for more
639 information about valid events. See also the examples for
640 `single-key-description', below.
642 - Function: single-key-description key
643 This function returns a string describing KEY in the standard
644 XEmacs notation for keyboard input. A normal printing character
645 appears as itself, but a control character turns into a string
646 starting with `C-', a meta character turns into a string starting
647 with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
648 A symbol appears as the name of the symbol. An event that is a
649 list appears as the name of the symbol in the CAR of the list.
651 (single-key-description ?\C-x)
653 (key-description "\C-x \M-y \n \t \r \f123")
654 => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
655 (single-key-description 'kp_next)
657 (single-key-description '(shift button1))
660 - Function: text-char-description character
661 This function returns a string describing CHARACTER in the
662 standard XEmacs notation for characters that appear in text--like
663 `single-key-description', except that control characters are
664 represented with a leading caret (which is how control characters
665 in XEmacs buffers are usually displayed).
667 (text-char-description ?\C-c)
669 (text-char-description ?\M-m)
671 (text-char-description ?\C-\M-m)
675 File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
680 XEmacs provides a variety of on-line help functions, all accessible
681 to the user as subcommands of the prefix `C-h', or on some keyboards,
682 `help'. For more information about them, see *Note Help: (emacs)Help.
683 Here we describe some program-level interfaces to the same information.
685 - Command: apropos regexp &optional do-all predicate
686 This function finds all symbols whose names contain a match for the
687 regular expression REGEXP, and returns a list of them (*note
688 Regular Expressions::). It also displays the symbols in a buffer
689 named `*Help*', each with a one-line description.
691 If DO-ALL is non-`nil', then `apropos' also shows key bindings for
692 the functions that are found.
694 If PREDICATE is non-`nil', it should be a function to be called on
695 each symbol that has matched REGEXP. Only symbols for which
696 PREDICATE returns a non-`nil' value are listed or displayed.
698 In the first of the following examples, `apropos' finds all the
699 symbols with names containing `exec'. In the second example, it
700 finds and returns only those symbols that are also commands. (We
701 don't show the output that results in the `*Help*' buffer.)
704 => (Buffer-menu-execute command-execute exec-directory
705 exec-path execute-extended-command execute-kbd-macro
706 executing-kbd-macro executing-macro)
708 (apropos "exec" nil 'commandp)
709 => (Buffer-menu-execute execute-extended-command)
711 `apropos' is used by various user-level commands, such as `C-h a'
712 (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
713 (`command-apropos'), which does an apropos over only those
714 functions which are user commands. `command-apropos' calls
715 `apropos', specifying a PREDICATE to restrict the output to
716 symbols that are commands. The call to `apropos' looks like this:
718 (apropos string t 'commandp)
721 The value of this variable is a local keymap for characters
722 following the Help key, `C-h'.
724 - Prefix Command: help-command
725 This symbol is not a function; its function definition is actually
726 the keymap known as `help-map'. It is defined in `help.el' as
729 (define-key global-map "\C-h" 'help-command)
730 (fset 'help-command help-map)
732 - Function: print-help-return-message &optional function
733 This function builds a string that explains how to restore the
734 previous state of the windows after a help command. After
735 building the message, it applies FUNCTION to it if FUNCTION is
736 non-`nil'. Otherwise it calls `message' to display it in the echo
739 This function expects to be called inside a
740 `with-output-to-temp-buffer' special form, and expects
741 `standard-output' to have the value bound by that special form.
742 For an example of its use, see the long example in *Note Accessing
745 - Variable: help-char
746 The value of this variable is the help character--the character
747 that XEmacs recognizes as meaning Help. By default, it is the
748 character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this
749 character, if `help-form' is non-`nil' Lisp expression, it
750 evaluates that expression, and displays the result in a window if
753 `help-char' can be a character or a key description such as `help'
756 Usually the value of `help-form''s value is `nil'. Then the help
757 character has no special meaning at the level of command input, and
758 it becomes part of a key sequence in the normal way. The standard
759 key binding of `C-h' is a prefix key for several general-purpose
762 The help character is special after prefix keys, too. If it has no
763 binding as a subcommand of the prefix key, it runs
764 `describe-prefix-bindings', which displays a list of all the
765 subcommands of the prefix key.
767 - Variable: help-form
768 If this variable is non-`nil', its value is a form to evaluate
769 whenever the character `help-char' is read. If evaluating the form
770 produces a string, that string is displayed.
772 A command that calls `next-command-event' or `next-event' probably
773 should bind `help-form' to a non-`nil' expression while it does
774 input. (The exception is when `C-h' is meaningful input.)
775 Evaluating this expression should result in a string that explains
776 what the input is for and how to enter it properly.
778 Entry to the minibuffer binds this variable to the value of
779 `minibuffer-help-form' (*note Minibuffer Misc::).
781 - Variable: prefix-help-command
782 This variable holds a function to print help for a prefix
783 character. The function is called when the user types a prefix
784 key followed by the help character, and the help character has no
785 binding after that prefix. The variable's default value is
786 `describe-prefix-bindings'.
788 - Function: describe-prefix-bindings
789 This function calls `describe-bindings' to display a list of all
790 the subcommands of the prefix key of the most recent key sequence.
791 The prefix described consists of all but the last event of that
792 key sequence. (The last event is, presumably, the help character.)
794 The following two functions are found in the library `helper'. They
795 are for modes that want to provide help without relinquishing control,
796 such as the "electric" modes. You must load that library with
797 `(require 'helper)' in order to use them. Their names begin with
798 `Helper' to distinguish them from the ordinary help functions.
800 - Command: Helper-describe-bindings
801 This command pops up a window displaying a help buffer containing a
802 listing of all of the key bindings from both the local and global
803 keymaps. It works by calling `describe-bindings'.
805 - Command: Helper-help
806 This command provides help for the current mode. It prompts the
807 user in the minibuffer with the message `Help (Type ? for further
808 options)', and then provides assistance in finding out what the key
809 bindings are, and what the mode is intended for. It returns `nil'.
811 This can be customized by changing the map `Helper-help-map'.
814 File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
819 As you add functionality to a package, you may at times want to
820 replace an older function with a new one. To preserve compatibility
821 with existing code, the older function needs to still exist; but users
822 of that function should be told to use the newer one instead. XEmacs
823 Lisp lets you mark a function or variable as "obsolete", and indicate
824 what should be used instead.
826 - Function: make-obsolete function new
827 This function indicates that FUNCTION is an obsolete function, and
828 the function NEW should be used instead. The byte compiler will
829 issue a warning to this effect when it encounters a usage of the
830 older function, and the help system will also note this in the
831 function's documentation. NEW can also be a string (if there is
832 not a single function with the same functionality any more), and
833 should be a descriptive statement, such as "use FOO or BAR
834 instead" or "this function is unnecessary".
836 - Function: make-obsolete-variable variable new
837 This is like `make-obsolete' but is for variables instead of
840 - Function: define-obsolete-function-alias oldfun newfun
841 This function combines `make-obsolete' and `define-function',
842 declaring OLDFUN to be an obsolete variant of NEWFUN and defining
843 OLDFUN as an alias for NEWFUN.
845 - Function: define-obsolete-variable-alias oldvar newvar
846 This is like `define-obsolete-function-alias' but for variables.
848 Note that you should not normally put obsoleteness information
849 explicitly in a function or variable's doc string. The obsoleteness
850 information that you specify using the above functions will be displayed
851 whenever the doc string is displayed, and by adding it explicitly the
852 result is redundancy.
854 Also, if an obsolete function is substantially the same as a newer
855 one but is not actually an alias, you should consider omitting the doc
856 string entirely (use a null string `""' as the doc string). That way,
857 the user is told about the obsoleteness and is forced to look at the
858 documentation of the new function, making it more likely that he will
859 use the new function.
861 - Function: function-obsoleteness-doc function
862 If FUNCTION is obsolete, this function returns a string describing
863 this. This is the message that is printed out during byte
864 compilation or in the function's documentation. If FUNCTION is
865 not obsolete, `nil' is returned.
867 - Function: variable-obsoleteness-doc variable
868 This is like `function-obsoleteness-doc' but for variables.
870 The obsoleteness information is stored internally by putting a
871 property `byte-obsolete-info' (for functions) or
872 `byte-obsolete-variable' (for variables) on the symbol that specifies
873 the obsolete function or variable. For more information, see the
874 implementation of `make-obsolete' and `make-obsolete-variable' in
875 `lisp/bytecomp/bytecomp-runtime.el'.
878 File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
883 In XEmacs, you can find, create, view, save, and otherwise work with
884 files and file directories. This chapter describes most of the
885 file-related functions of XEmacs Lisp, but a few others are described in
886 *Note Buffers::, and those related to backups and auto-saving are
887 described in *Note Backups and Auto-Saving::.
889 Many of the file functions take one or more arguments that are file
890 names. A file name is actually a string. Most of these functions
891 expand file name arguments using `expand-file-name', so that `~' is
892 handled correctly, as are relative file names (including `../'). These
893 functions don't recognize environment variable substitutions such as
894 `$HOME'. *Note File Name Expansion::.
898 * Visiting Files:: Reading files into Emacs buffers for editing.
899 * Saving Buffers:: Writing changed buffers back into files.
900 * Reading from Files:: Reading files into buffers without visiting.
901 * Writing to Files:: Writing new files from parts of buffers.
902 * File Locks:: Locking and unlocking files, to prevent
903 simultaneous editing by two people.
904 * Information about Files:: Testing existence, accessibility, size of files.
905 * Changing File Attributes:: Renaming files, changing protection, etc.
906 * File Names:: Decomposing and expanding file names.
907 * Contents of Directories:: Getting a list of the files in a directory.
908 * Create/Delete Dirs:: Creating and Deleting Directories.
909 * Magic File Names:: Defining "magic" special handling
910 for certain file names.
911 * Partial Files:: Treating a section of a buffer as a file.
912 * Format Conversion:: Conversion to and from various file formats.
913 * Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
916 File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
921 Visiting a file means reading a file into a buffer. Once this is
922 done, we say that the buffer is "visiting" that file, and call the file
923 "the visited file" of the buffer.
925 A file and a buffer are two different things. A file is information
926 recorded permanently in the computer (unless you delete it). A buffer,
927 on the other hand, is information inside of XEmacs that will vanish at
928 the end of the editing session (or when you kill the buffer). Usually,
929 a buffer contains information that you have copied from a file; then we
930 say the buffer is visiting that file. The copy in the buffer is what
931 you modify with editing commands. Such changes to the buffer do not
932 change the file; therefore, to make the changes permanent, you must
933 "save" the buffer, which means copying the altered buffer contents back
936 In spite of the distinction between files and buffers, people often
937 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
938 "I am editing a file," rather than, "I am editing a buffer that I will
939 soon save as a file of the same name." Humans do not usually need to
940 make the distinction explicit. When dealing with a computer program,
941 however, it is good to keep the distinction in mind.
945 * Visiting Functions:: The usual interface functions for visiting.
946 * Subroutines of Visiting:: Lower-level subroutines that they use.
949 File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
951 Functions for Visiting Files
952 ----------------------------
954 This section describes the functions normally used to visit files.
955 For historical reasons, these functions have names starting with
956 `find-' rather than `visit-'. *Note Buffer File Name::, for functions
957 and variables that access the visited file name of a buffer or that
958 find an existing buffer by its visited file name.
960 In a Lisp program, if you want to look at the contents of a file but
961 not alter it, the fastest way is to use `insert-file-contents' in a
962 temporary buffer. Visiting the file is not necessary and takes longer.
963 *Note Reading from Files::.
965 - Command: find-file filename
966 This command selects a buffer visiting the file FILENAME, using an
967 existing buffer if there is one, and otherwise creating a new
968 buffer and reading the file into it. It also returns that buffer.
970 The body of the `find-file' function is very simple and looks like
973 (switch-to-buffer (find-file-noselect filename))
975 (See `switch-to-buffer' in *Note Displaying Buffers::.)
977 When `find-file' is called interactively, it prompts for FILENAME
980 - Function: find-file-noselect filename &optional nowarn
981 This function is the guts of all the file-visiting functions. It
982 finds or creates a buffer visiting the file FILENAME, and returns
983 it. It uses an existing buffer if there is one, and otherwise
984 creates a new buffer and reads the file into it. You may make the
985 buffer current or display it in a window if you wish, but this
986 function does not do so.
988 When `find-file-noselect' uses an existing buffer, it first
989 verifies that the file has not changed since it was last visited or
990 saved in that buffer. If the file has changed, then this function
991 asks the user whether to reread the changed file. If the user says
992 `yes', any changes previously made in the buffer are lost.
994 If `find-file-noselect' needs to create a buffer, and there is no
995 file named FILENAME, it displays the message `New file' in the
996 echo area, and leaves the buffer empty.
998 If NO-WARN is non-`nil', various warnings that XEmacs normally
999 gives (e.g. if another buffer is already visiting FILENAME but
1000 FILENAME has been removed from disk since that buffer was created)
1003 The `find-file-noselect' function calls `after-find-file' after
1004 reading the file (*note Subroutines of Visiting::). That function
1005 sets the buffer major mode, parses local variables, warns the user
1006 if there exists an auto-save file more recent than the file just
1007 visited, and finishes by running the functions in
1010 The `find-file-noselect' function returns the buffer that is
1011 visiting the file FILENAME.
1013 (find-file-noselect "/etc/fstab")
1016 - Command: find-file-other-window filename
1017 This command selects a buffer visiting the file FILENAME, but does
1018 so in a window other than the selected window. It may use another
1019 existing window or split a window; see *Note Displaying Buffers::.
1021 When this command is called interactively, it prompts for FILENAME.
1023 - Command: find-file-read-only filename
1024 This command selects a buffer visiting the file FILENAME, like
1025 `find-file', but it marks the buffer as read-only. *Note Read
1026 Only Buffers::, for related functions and variables.
1028 When this command is called interactively, it prompts for FILENAME.
1030 - Command: view-file filename
1031 This command visits FILENAME in View mode, and displays it in a
1032 recursive edit, returning to the previous buffer when done. View
1033 mode is a mode that allows you to skim rapidly through the file
1034 but does not let you modify it. Entering View mode runs the
1035 normal hook `view-mode-hook'. *Note Hooks::.
1037 When `view-file' is called interactively, it prompts for FILENAME.
1039 - Variable: find-file-hooks
1040 The value of this variable is a list of functions to be called
1041 after a file is visited. The file's local-variables specification
1042 (if any) will have been processed before the hooks are run. The
1043 buffer visiting the file is current when the hook functions are
1046 This variable works just like a normal hook, but we think that
1047 renaming it would not be advisable.
1049 - Variable: find-file-not-found-hooks
1050 The value of this variable is a list of functions to be called when
1051 `find-file' or `find-file-noselect' is passed a nonexistent file
1052 name. `find-file-noselect' calls these functions as soon as it
1053 detects a nonexistent file. It calls them in the order of the
1054 list, until one of them returns non-`nil'. `buffer-file-name' is
1057 This is not a normal hook because the values of the functions are
1058 used and they may not all be called.
1061 File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
1063 Subroutines of Visiting
1064 -----------------------
1066 The `find-file-noselect' function uses the `create-file-buffer' and
1067 `after-find-file' functions as subroutines. Sometimes it is useful to
1070 - Function: create-file-buffer filename
1071 This function creates a suitably named buffer for visiting
1072 FILENAME, and returns it. It uses FILENAME (sans directory) as
1073 the name if that name is free; otherwise, it appends a string such
1074 as `<2>' to get an unused name. See also *Note Creating Buffers::.
1076 *Please note:* `create-file-buffer' does _not_ associate the new
1077 buffer with a file and does not select the buffer. It also does
1078 not use the default major mode.
1080 (create-file-buffer "foo")
1082 (create-file-buffer "foo")
1084 (create-file-buffer "foo")
1087 This function is used by `find-file-noselect'. It uses
1088 `generate-new-buffer' (*note Creating Buffers::).
1090 - Function: after-find-file &optional error warn noauto
1091 This function sets the buffer major mode, and parses local
1092 variables (*note Auto Major Mode::). It is called by
1093 `find-file-noselect' and by the default revert function (*note
1096 If reading the file got an error because the file does not exist,
1097 but its directory does exist, the caller should pass a non-`nil'
1098 value for ERROR. In that case, `after-find-file' issues a warning:
1099 `(New File)'. For more serious errors, the caller should usually
1100 not call `after-find-file'.
1102 If WARN is non-`nil', then this function issues a warning if an
1103 auto-save file exists and is more recent than the visited file.
1105 If NOAUTO is non-`nil', then this function does not turn on
1106 auto-save mode; otherwise, it does.
1108 The last thing `after-find-file' does is call all the functions in
projects / chise / xemacs-chise.git- / blob