   This version is newer than the second printed edition of the GNU
Emacs Lisp Reference Manual.  It corresponds to Emacs Version 19.19.

   Published by the Free Software Foundation 675 Massachusetts Avenue
Cambridge, MA 02139 USA

   Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

Keymaps and Minor Modes
-----------------------

   As of Emacs version 19, each minor mode can have its own keymap
which is active when the mode is enabled.  See Active Keymaps.  To
set up a keymap for a minor mode, add an element to the alist
`minor-mode-map-alist'.

   One use of minor mode keymaps is to modify the behavior of certain
self-inserting characters so that they do something else as well as
self-insert.  This is the only way to accomplish this in general, since
there is no way to customize what `self-insert-command' does except in
certain special cases (designed for abbrevs and Auto Fill mode).  (Do
not try substituting your own definition of `self-insert-command' for
the standard one.  The editor command loop handles this function
specially.)

 - Variable: minor-mode-map-alist
     This variable is an alist of elements element that look like this:

          (VARIABLE . KEYMAP)

     where VARIABLE is the variable which indicates whether the minor
     mode is enabled, and KEYMAP is the keymap.  The keymap KEYMAP is
     active whenever VARIABLE has a non-`nil' value.

     Note that elements of `minor-mode-map-alist' do not have the same
     structure as elements of `minor-mode-alist'.  The map must be the
     CDR of the element; a list with the map as the second element will
     not do.

     What's more, the keymap itself must appear in the CDR.  It does not
     work to store a variable in the CDR and make the map the value of
     that variable.

     When more than one minor mode keymap is active, their order of
     priority is the order of `minor-mode-map-alist'.  But you should
     design minor modes so that they don't interfere with each other.
     If you do this properly, the order will not matter.

Mode Line Format
================

   Each Emacs window (aside from minibuffer windows) includes a mode
line which displays status information about the buffer displayed in the
window.  The mode line contains information about the buffer such as its
name, associated file, depth of recursive editing, and the major and
minor modes of the buffer.

   This section describes how the contents of the mode line are
controlled.  It is in the chapter on modes because much of the
information displayed in the mode line relates to the enabled major and
minor modes.

   `mode-line-format' is a buffer-local variable that holds a template
used to display the mode line of the current buffer.  All windows for
the same buffer use the same `mode-line-format' and the mode lines will
appear the same (except perhaps for the percentage of the file scrolled
off the top).

   The mode line of a window is normally updated whenever a different
buffer is shown in the window, or when the buffer's modified-status
changes from `nil' to `t' or vice-versa.  If you modify any of the
variables referenced by `mode-line-format', you may want to force an
update of the mode line so as to display the new information.

 - Function: force-mode-line-update &optional ALL
     Force redisplay of the current buffer's mode line.  If ALL is
     non-`nil', then force redisplay of all mode lines.  This function
     is equivalent to `redraw-mode-line'.

   The mode line is usually displayed in inverse video; see
`mode-line-inverse-video' in Inverse Video.

The Data Structure of the Mode Line
-----------------------------------

   The mode line contents are controlled by a data structure of lists,
strings, symbols and numbers kept in the buffer-local variable
`mode-line-format'.  The data structure is called a "mode line
construct", and it is built in recursive fashion out of simpler mode
line constructs.

 - Variable: mode-line-format
     The value of this variable is a mode line construct with overall
     responsibility for the mode line format.  The value of this
     variable controls which other variables are used to form the mode
     line text, and where they appear.

   A mode line construct may be as simple as a fixed string of text, but
it usually specifies how to use other variables to construct the text.
Many of these variables are themselves defined to have mode line
constructs as their values.

   The default value of `mode-line-format' incorporates the values of
variables such as `mode-name' and `minor-mode-alist'.  Because of this,
very few modes need to alter `mode-line-format'.  For most purposes, it
is sufficient to alter the variables referenced by `mode-line-format'.

   A mode line construct may be a list, cons cell, symbol, or string.
If the value is a list, each element may be a list, a cons cell, a
symbol, or a string.

`STRING'
     A string as a mode line construct is displayed verbatim in the
     mode line except for "`%'-constructs".  Decimal digits after the
     `%' specify the field width for space filling on the right (i.e.,
     the data is left justified).  See %-Constructs.

`SYMBOL'
     A symbol as a mode line construct stands for its value.  The value
     of SYMBOL is used in place of SYMBOL unless SYMBOL is `t' or
     `nil', or is void, in which case SYMBOL is ignored.

     There is one exception: if the value of SYMBOL is a string, it is
     processed verbatim in that the `%'-constructs are not recognized.

`(STRING REST...) or (LIST REST...)'
     A list whose first element is a string or list, means to
     concatenate all the elements.  This is the most common form of
     mode line construct.

`(SYMBOL THEN ELSE)'
     A list whose first element is a symbol is a conditional.  Its
     meaning depends on the value of SYMBOL.  If the value is non-`nil',
     the second element of the list (THEN) is processed recursively as
     a mode line element.  But if the value of SYMBOL is `nil', the
     third element of the list (if there is one) is processed
     recursively.

`(WIDTH REST...)'
     A list whose first element is an integer specifies truncation or
     padding of the results of REST.  The remaining elements REST are
     processed recursively as mode line constructs and concatenated
     together.  Then the result is space filled (if WIDTH is positive)
     or truncated (to -WIDTH columns, if WIDTH is negative) on the
     right.

     For example, the usual way to show what percentage of a buffer is
     above the top of the window is to use a list like this: `(-3 .
     "%p")'.

   If you do alter `mode-line-format' itself, the new value should use
all the same variables that are used by the default value, rather than
duplicating their contents or displaying the information in another
fashion.  This permits customizations made by the user, by libraries
(such as `display-time') or by major modes via changes to those
variables remain effective.

   Here is an example of a `mode-line-format' that might be useful for
`shell-mode' since it contains the hostname and default directory.

     (setq mode-line-format
       (list ""
        'mode-line-modified
        "%b--"
        (getenv "HOST")      ; One element is not constant.
        ":"
        'default-directory
        "   "
        'global-mode-string
        "   %[(" 'mode-name
        'minor-mode-alist
        "%n"
        'mode-line-process
        ")%]----"
        '(-3 . "%p")
        "-%-"))

Variables Used in the Mode Line
-------------------------------

   This section describes variables incorporated by the standard value
of `mode-line-format' into the text of the mode line.  There is nothing
inherently special about these variables; any other variables could
have the same effects on the mode line if `mode-line-format' were
changed to use them.

 - Variable: mode-line-modified
     This variable holds the value of the mode-line construct that
     displays whether the current buffer is modified.

     The default value of `mode-line-modified' is `("--%1*%1*-")'.
     This means that the mode line displays `--**-' if the buffer is
     modified, `-----' if the buffer is not modified, and `--%%-' if
     the buffer is read only.

     Changing this variable does not force an update of the mode line.

 - Variable: mode-line-buffer-identification
     This variable identifies the buffer being displayed in the window.
     Its default value is `Emacs: %17b', which means that it displays
     `Emacs:' followed by the buffer name.  You may want to change this
     in modes such as Rmail that do not behave like a "normal" Emacs.

 - Variable: global-mode-string
     This variable holds a string that is displayed in the mode line.
     The command `display-time' puts the time and load in this variable.
     The `%M' construct substitutes the value of `global-mode-string',
     but this is obsolete, since the variable is included directly in
     the mode line.

 - Variable: mode-name
     This buffer-local variable holds the "pretty" name of the current
     buffer's major mode.  Each major mode should set this variable so
     that the mode name will appear in the mode line.

 - Variable: minor-mode-alist
     This variable holds an association list whose elements specify how
     the mode line should indicate that a minor mode is active.  Each
     element of the `minor-mode-alist' should be a two-element list:

          (MINOR-MODE-VARIABLE MODE-LINE-STRING)

     The string MODE-LINE-STRING is included in the mode line when the
     value of MINOR-MODE-VARIABLE is non-`nil' and not otherwise.
     These strings should begin with spaces so that they don't run
     together.  Conventionally, the MINOR-MODE-VARIABLE for a specific
     mode is set to a non-`nil' value when that minor mode is activated.

     The default value of `minor-mode-alist' is:

          minor-mode-alist
          => ((abbrev-mode " Abbrev")
              (overwrite-mode " Ovwrt")
              (auto-fill-function " Fill")
              (defining-kbd-macro " Def"))

     (In earlier Emacs versions, `auto-fill-function' was called
     `auto-fill-hook'.)

     `minor-mode-alist' is not buffer-local.  The variables mentioned
     in the alist should be buffer-local if the minor mode can be
     enabled separately in each buffer.

 - Variable: mode-line-process
     This buffer-local variable contains the mode line information on
     process status in modes used for communicating with subprocesses.
     It is displayed immediately following the major mode name, with no
     intervening space.  For example, its value in the `*shell*' buffer
     is `(": %s")', which allows the shell to display its status along
     with the major mode as: `(Shell: run)'.  Normally this variable is
     `nil'.

 - Variable: default-mode-line-format
     This variable holds the default `mode-line-format' for buffers
     that do not override it.  This is the same as `(default-value
     'mode-line-format)'.

     The default value of `default-mode-line-format' is:

          (""
           mode-line-modified
           mode-line-buffer-identification
           "   "
           global-mode-string
           "   %[("
           mode-name
           minor-mode-alist
           "%n"
           mode-line-process
           ")%]----"
           (-3 . "%p")
           "-%-")

`%'-Constructs in the Mode Line
-------------------------------

   The following table lists the recognized `%'-constructs and what
they mean.

`%b'
     the current buffer name, using the `buffer-name' function.

`%f'
     the visited file name, using the `buffer-file-name' function.

`%*'
     `%' if the buffer is read only (see `buffer-read-only');
     `*' if the buffer is modified (see `buffer-modified-p');
     `-' otherwise.

`%s'
     the status of the subprocess belonging to the current buffer, using
     `process-status'.

`%l'
     the current line number.

`%S'
     the name of the selected screen; this is only meaningful under the
     X Window System.  See Screen Name.

`%p'
     the percent of the buffer above the top of window, or `Top',
     `Bottom' or `All'.

`%n'
     `Narrow' when narrowing is in effect; nothing otherwise (see
     `narrow-to-region' in Narrowing).

`%['
     an indication of the depth of recursive editing levels (not
     counting minibuffer levels): one `[' for each editing level.

`%]'
     one `]' for each recursive editing level (not counting minibuffer
     levels).

`%%'
     the character `%'--this is how to include a literal `%' in a
     string in which `%'-constructs are allowed.

`%-'
     dashes sufficient to fill the remainder of the mode line.

   The following two `%'-constructs are still supported but are
obsolete since use of the `mode-name' and `global-mode-string'
variables will produce the same results.

`%m'
     the value of `mode-name'.

`%M'
     the value of `global-mode-string'.  Currently, only `display-time'
     modifies the value of `global-mode-string'.

Hooks
=====

   A "hook" is a variable where you can store a function or functions
to be called on a particular occasion by an existing program.  Emacs
provides lots of hooks for the sake of customization.  Most often, hooks
are set up in the `.emacs' file, but Lisp programs can set them also.
See Standard Hooks, for a list of standard hook variables.

   Most of the hooks in Emacs are "normal hooks".  These variables
contain lists of functions to be called with no arguments.  The reason
most hooks are normal hooks is so that you can use them in a uniform
way.  You can usually tell when a hook is a normal hook, because its
name ends in `-hook'.

   The recommended way to add a hook function to a normal hook is by
calling `add-hook' (see below).  The hook functions may be any of the
valid kinds of functions that `funcall' accepts (see What Is a Function.).
Most normal hook variables are initially void;
`add-hook' knows how to deal with this.

   As for abnormal hooks, those whose names end in `-function' have a
value which is a single function.  Those whose names end in `-hooks'
have a value which is a list of functions.  Any hook which is abnormal
is abnormal because a normal hook won't do the job; either the
functions are called with arguments, or their values are meaningful.
The name shows you that the hook is abnormal and you need to look up
how to use it properly.

   Most major modes run hooks as the last step of initialization.  This
makes it easy for a user to customize the behavior of the mode, by
overriding the local variable assignments already made by the mode.  But
hooks may also be used in other contexts.  For example, the hook
`suspend-hook' runs just before Emacs suspends itself (see Suspending Emacs.).

   For example, you can put the following expression in your `.emacs'
file if you want to turn on Auto Fill mode when in Lisp Interaction
mode:

     (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)

   The next example shows how to use a hook to customize the way Emacs
formats C code.  (People often have strong personal preferences for one
format compared to another.)  Here the hook function is an anonymous
lambda expression.

     (add-hook 'c-mode-hook
       (function (lambda ()
                   (setq c-indent-level 4
                         c-argdecl-indent 0
                         c-label-offset -4
                         c-continued-statement-indent 0
                         c-brace-offset 0
                         comment-column 40))))

     (setq c++-mode-hook c-mode-hook)

   Finally, here is an example of how to use the Text mode hook to
provide a customized mode line for buffers in Text mode, displaying the
default directory in addition to the standard components of the mode
line.  (This may cause the mode line to run out of space if you have
very long file names or display the time and load.)

     (add-hook 'text-mode-hook
       (function (lambda ()
                   (setq mode-line-format
                         '(mode-line-modified
                           "Emacs: %14b"
                           "  "
                           default-directory
                           " "
                           global-mode-string
                           "%[("
                           mode-name
                           minor-mode-alist
                           "%n"
                           mode-line-process
                           ") %]---"
                           (-3 . "%p")
                           "-%-")))))

   At the appropriate time, Emacs uses the `run-hooks' function to run
particular hooks.  This function calls the hook functions you have
added with `add-hooks'.

 - Function: run-hooks &rest HOOKVAR
     This function takes one or more hook names as arguments and runs
     each one in turn.  Each HOOKVAR argument should be a symbol that
     is a hook variable.  These arguments are processed in the order
     specified.

     If a hook variable has a non-`nil' value, that value may be a
     function or a list of functions.  If the value is a function
     (either a lambda expression or a symbol with a function
     definition), it is called.  If it is a list, the elements are
     called, in order.  The hook functions are called with no arguments.

     For example:

          (run-hooks 'emacs-lisp-mode-hook)

     Major mode functions use this function to call any hooks defined
     by the user.

 - Function: add-hook HOOK FUNCTION &optional APPEND
     This function is the handy way to add function FUNCTION to hook
     variable HOOK.  For example,

          (add-hook 'text-mode-hook 'my-text-hook-function)

     adds `my-text-hook-function' to the hook called `text-mode-hook'.

     It is best to design your hook functions so that the order in
     which they are executed does not matter.  Any dependence on the
     order is "asking for trouble."  However, the order is predictable:
     normally, FUNCTION goes at the front of the hook list, so it will
     be executed first (barring another `add-hook' call).

     If the optional argument APPEND is non-`nil', the new hook
     function goes at the end of the hook list and will be executed
     last.

Documentation
*************

   GNU Emacs Lisp has convenient on-line help facilities, most of which
derive their information from the documentation strings associated with
functions and variables.  This chapter describes how to write good
documentation strings for your Lisp programs, as well as how to write
programs to access documentation.

   Note that the documentation strings for Emacs are not the same thing
as the Emacs manual.  Manuals have their own source files, written in
the Texinfo language; documentation strings are specified in the
definitions of the functions and variables they apply to.  A collection
of documentation strings is not sufficient as a manual because a good
manual is not organized in that fashion; it is organized in terms of
topics of discussion.

Documentation Basics
====================

   A documentation string is written using the Lisp syntax for strings,
with double-quote characters surrounding the text of the string.  This
is because it really is a Lisp string object.  The string serves as
documentation when it is written in the proper place in the definition
of a function or variable.  In a function definition, the documentation
string follows the argument list.  In a variable definition, the
documentation string follows the initial value of the variable.

   When you write a documentation string, make the first line a complete
sentence (or two complete sentences) since some commands, such as
`apropos', print only the first line of a multi-line documentation
string.  Also, you should not indent the second line of a documentation
string, if you have one, because that looks odd when you use `C-h f'
(`describe-function') or `C-h v' (`describe-variable').

   Documentation strings may contain several special substrings, which
stand for key bindings to be looked up in the current keymaps when the
documentation is displayed.  This allows documentation strings to refer
to the keys for related commands and be accurate even when a user
rearranges the key bindings.  (see Accessing Documentation.)

   Within the Lisp world, a documentation string is kept with the
function or variable that it describes:

   * The documentation for a function is stored in the function
     definition itself (see Lambda Expressions.).  The function
     `documentation' knows how to extract it.

   * The documentation for a variable is stored on the variable's
     property list under the property name `variable-documentation'.
     The function `documentation-property' knows how to extract it.

   However, to save space, the documentation for preloaded functions and
variables (including primitive functions and autoloaded functions) are
stored in the `emacs/etc/DOC-VERSION' file.  The
`emacs/etc/DOC-VERSION' file can be accessed by both the
`documentation' and the `documentation-property' functions, and the
process is transparent to the user.  In this case, the documentation
string is replaced with an integer offset into the
`emacs/etc/DOC-VERSION' file.  Keeping the documentation strings out of
the Emacs core image saves a significant amount of space.  See
Building Emacs.

   For information on the uses of documentation strings, see
Help (emacs).

   The `emacs/etc' directory contains two utilities that you can use to
print nice-looking hardcopy for the file `emacs/etc/DOC-VERSION'.
These are `sorted-doc.c' and `digest-doc.c'.

Access to Documentation Strings
===============================

 - Function: documentation-property SYMBOL PROPERTY &optional VERBATIM
     This function returns the documentation string that is recorded
     SYMBOL's property list under property PROPERTY.  This uses the
     function `get', but does more than that: it also retrieves the
     string from the file `emacs/etc/DOC-VERSION' if necessary, and
     runs `substitute-command-keys' to substitute the actual (current)
     key bindings.

     If VERBATIM is non-`nil', that inhibits running
     `substitute-command-keys'.  (The VERBATIM argument exists only as
     of Emacs 19.)

          (documentation-property 'command-line-processed
             'variable-documentation)
               => "t once command line has been processed"

          (symbol-plist 'command-line-processed)
               => (variable-documentation 188902)

 - Function: documentation FUNCTION &optional VERBATIM
     This function returns the documentation string of FUNCTION.  This
     function will access the documentation string if it is stored in
     the `emacs/etc/DOC-VERSION' file.

     In addition, `documentation' runs `substitute-command-keys' on the
     resulting string, so the value contains the actual (current) key
     bindings.  (This is not done if VERBATIM is non-`nil'; the
     VERBATIM argument exists only as of Emacs 19.)

     The function `documentation' signals a `void-function' error
     unless FUNCTION has a function definition.  However, FUNCTION does
     not need to have a documentation string.  If there is no
     documentation string, `documentation' returns `nil'.

   Here is an example of using the two functions, `documentation' and
`documentation-property', to display the documentation strings for
several symbols in a `*Help*' buffer.

     (defun describe-symbols (pattern)
       "Describe the Emacs Lisp symbols matching PATTERN.
     All symbols that have PATTERN in their name are described
     in the `*Help*' buffer."
       (interactive "sDescribe symbols matching: ")
       (let ((describe-func
              (function
               (lambda (s)

     ;; Print description of symbol.
                 (if (fboundp s)             ; It is a function.
                     (princ
                      (format "%s\t%s\n%s\n\n" s
                        (if (commandp s)
                            (let ((keys (where-is-internal s)))
                              (if keys
                                  (concat
                                   "Keys: "
                                   (mapconcat 'key-description
                                              keys " "))
                                "Keys: none"))
                          "Function")

     (or (documentation s)
                            "not documented"))))

                 (if (boundp s)              ; It is a variable.

     (princ
                      (format "%s\t%s\n%s\n\n" s
                        (if (user-variable-p s)
                            "Option " "Variable")

     (or (documentation-property
                              s 'variable-documentation)
                            "not documented")))))))
             sym-list)

     ;; Build a list of symbols that match pattern.
         (mapatoms (function
                    (lambda (sym)
                      (if (string-match pattern (symbol-name sym))
                          (setq sym-list (cons sym sym-list))))))

     ;; Display the data.
         (with-output-to-temp-buffer "*Help*"
           (mapcar describe-func (sort sym-list 'string<))
           (print-help-return-message))))

   The `describe-symbols' function works like `apropos', but provides
more information.

     (describe-symbols "goal")

     ---------- Buffer: *Help* ----------
     goal-column     Option
     *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.

     set-goal-column Command: C-x C-n
     Set the current horizontal position as a goal for C-n and C-p.

     Those commands will move to this position in the line moved to
     rather than trying to keep the same horizontal position.
     With a non-nil argument, clears out the goal column
     so that C-n and C-p resume vertical motion.
     The goal column is stored in the variable `goal-column'.

     temporary-goal-column   Variable
     Current goal column for vertical motion.
     It is the column where point was
     at the start of current run of vertical motion commands.
     When the `track-eol' feature is doing its job, the value is 9999.
     ---------- Buffer: *Help* ----------

 - Function: Snarf-documentation FILENAME
     This function is used only during Emacs initialization, just before
     the runnable Emacs is dumped.  It finds the file offsets of the
     documentation strings stored in the file FILENAME, and records
     them in the in-core function definitions and variable property
     lists in place of the actual strings.  See Building Emacs.

     Emacs finds the file FILENAME in the `emacs/etc' directory.  When
     the dumped Emacs is later executed, the same file is found in the
     directory `data-directory'.  Usually FILENAME is `"DOC-VERSION"'.

 - Variable: data-directory
     This variable holds the name of the directory in which Emacs finds
     certain data files that come with Emacs or are built as part of
     building Emacs.  (In older Emacs versions, this directory was the
     same as `exec-directory'.)

Substituting Key Bindings in Documentation
==========================================

   This function makes it possible for you to write a documentation
string that enables a user to display information about the current,
actual key bindings.  if you call `documentation' with non-`nil'
VERBATIM, you might later call this function to do the substitution
that you prevented `documentation' from doing.

 - Function: substitute-command-keys STRING
     This function returns STRING with certain special substrings
     replaced by the actual (current) key bindings.  This permits the
     documentation to be displayed with accurate information about key
     bindings.  (The key bindings may be changed by the user between
     the time Emacs is built and the time that the documentation is
     asked for.)

     This table lists the forms of the special substrings and what they
     are replaced with:

    `\[COMMAND]'
          is replaced either by a keystroke sequence that will invoke
          COMMAND, or by `M-x COMMAND' if COMMAND is not bound to any
          key sequence.

    `\{MAPVAR}'
          is replaced by a summary of the value of MAPVAR, taken as a
          keymap.  (The summary is made by `describe-bindings'.)

    `\<MAPVAR>'
          makes this call to `substitute-command-keys' use the value of
          MAPVAR as the keymap for future `\[COMMAND]' substrings.
          This special string does not produce any replacement text
          itself; it only affects the replacements done later.

     *Please note:* each `\' must be doubled when written in a string
     in Emacs Lisp.

     Here are examples of the special substrings:

          (substitute-command-keys
             "To abort recursive edit, type: \\[abort-recursive-edit]")

          => "To abort recursive edit, type: C-]"

          (substitute-command-keys
             "The keys that are defined for the minibuffer here are:
            \\{minibuffer-local-must-match-map}")

          => "The keys that are defined for the minibuffer here are:

          ?               minibuffer-completion-help
          SPC             minibuffer-complete-word
          TAB             minibuffer-complete
          LFD             minibuffer-complete-and-exit
          RET             minibuffer-complete-and-exit
          C-g             abort-recursive-edit
          "
          (substitute-command-keys
             "To abort a recursive edit from the minibuffer, type\
          \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
          => "To abort a recursive edit from the minibuffer, type C-g."

Describing Characters for Help Messages
=======================================

   These functions convert events, key sequences or characters to
textual descriptions.  These descriptions are useful for including
arbitrary text characters or key sequences in messages, because they
convert non-printing characters to sequences of printing characters.
The description of a printing character is the character itself.

 - Function: key-description SEQUENCE
     This function returns a string containing the Emacs standard
     notation for the input events in SEQUENCE.  The argument SEQUENCE
     may be a string, vector or list.  See Input Events, for more
     information about valid events.  See also the examples for
     `single-key-description', below.

 - Function: single-key-description EVENT
     This function returns a string describing EVENT in the standard
     Emacs notation for keyboard input.  A normal printing character is
     represented by itself, but a control character turns into a string
     starting with `C-', a meta character turns into a string starting
     with `M-', and space, linefeed, etc. are transformed to `SPC',
     `LFD', etc.  A function key is represented by its name.  An event
     which is a list is represented by the name of the symbol in the CAR
     of the list.

          (single-key-description ?\C-x)
               => "C-x"

          (key-description "\C-x \M-y \n \t \r \f123")
               => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"

          (single-key-description 'C-mouse-1)
               => "C-mouse-1"

 - Function: text-char-description CHARACTER
     This function returns a string describing CHARACTER in the
     standard Emacs notation for characters that appear in text--like
     `single-key-description', except that control characters are
     represented with a leading caret (which is how control characters
     in Emacs buffers are usually displayed).

          (text-char-description ?\C-c)
               => "^C"

          (text-char-description ?\M-m)
               => "M-m"

          (text-char-description ?\C-\M-m)
               => "M-^M"

Help Functions
==============

   Emacs provides a variety of on-line help functions, all accessible to
the user as subcommands of the prefix `C-h'.  For more information
about them, see Help (emacs).  Here we describe some
program-level interfaces to the same information.

 - Command: apropos REGEXP &optional DO-ALL PREDICATE
     This function finds all symbols whose names contain a match for the
     regular expression REGEXP, and returns a list of them.  It also
     displays the symbols in a buffer named `*Help*', each with a
     one-line description.

     If DO-ALL is non-`nil', then `apropos' also shows key bindings for
     the functions that are found.

     If PREDICATE is non-`nil', it should be a function to be called on
     each symbol that has matched REGEXP.  Only symbols for which
     PREDICATE returns a non-`nil' value are listed or displayed.

     In the first of the following examples, `apropos' finds all the
     symbols with names containing `exec'.  In the second example, it
     finds and returns only those symbols that are also commands.  (We
     don't show the output that results in the `*Help*' buffer.)

          (apropos "exec")
               => (Buffer-menu-execute command-execute exec-directory
              exec-path execute-extended-command execute-kbd-macro
              executing-kbd-macro executing-macro)

          (apropos "exec" nil 'commandp)
               => (Buffer-menu-execute execute-extended-command)

     The command `C-h a' (`command-apropos') calls `apropos', but
     specifies a PREDICATE to restrict the output to symbols that are
     commands.  The call to `apropos' looks like this:

          (apropos string t 'commandp)

 - Command: super-apropos REGEXP &optional DO-ALL
     This function differs from `apropos' in that it searches
     documentation strings as well as symbol names for matches for
     REGEXP.  By default, it searches only the documentation strings,
     and only those of functions and variables that are included in
     Emacs when it is dumped.  If DO-ALL is non-`nil', it scans the
     names and documentation strings of all functions and variables.

 - Command: help-command
     This command is not a function, but rather a symbol which is
     equivalent to the keymap called `help-map'.  It is defined in
     `help.el' as follows:

          (define-key global-map "\C-h" 'help-command)
          (fset 'help-command help-map)

 - Variable: help-map
     The value of this variable is a local keymap for characters
     following the Help key, `C-h'.

 - Function: print-help-return-message &optional FUNCTION
     This function builds a string which is a message explaining how to
     restore the previous state of the windows after a help command.
     After building the message, it applies FUNCTION to it if FUNCTION
     is non-`nil'.  Otherwise it calls `message' to display it in the
     echo area.

     This function expects to be called inside a
     `with-output-to-temp-buffer' special form, and expects
     `standard-output' to have the value bound by that special form.
     For an example of its use, see the example in the section
     describing the `documentation' function (see Accessing Documentation.).

     The constructed message will have one of the forms shown below.

          ---------- Echo Area ----------
          Type C-x 1 to remove help window.
          ---------- Echo Area ----------

          ---------- Echo Area ----------
          Type C-x 4 b RET to restore old contents of help window.
          ---------- Echo Area ----------

 - Variable: help-char
     The value of this variable is the character that Emacs recognizes
     as meaning Help.  When Emacs reads this character (which is
     usually 8, the value of `C-h'), Emacs evaluates `(eval
     help-form)', and displays the result if it is a string.  If
     `help-form''s value is `nil', this character is read normally.

 - Variable: help-form
     The value of this variable is a form to execute when the character
     `help-char' is read.  If the form returns a string, that string is
     displayed.  If `help-form' is `nil', then the help character is
     not recognized.

     Entry to the minibuffer binds this variable to the value of
     `minibuffer-help-form'.

 - Variable: prefix-help-command
     This variable holds a command that prints help for a prefix
     character.  The command is run when the user types the help
     character after a prefix character.  The default value of
     `prefix-help-command' is `describe-prefix-bindings'; that command
     uses `this-command-keys' to find what prefix character was used,
     then uses `describe-bindings' to describe it.

   The following two functions are found in the library `helper'.  They
are for modes that want to provide help without relinquishing control,
such as the "electric" modes.  You must load that library with
`(require 'helper)' in order to use them.  Their names begin with
`Helper' to distinguish them from the ordinary help functions.

 - Command: Helper-describe-bindings
     This command pops up a window displaying a help buffer containing a
     listing of all of the key bindings from both the local and global
     keymaps.  It works by calling `describe-bindings'.

 - Command: Helper-help
     This command provides help for the current mode.  It prompts the
     user in the minibuffer with the message `Help (Type ? for further
     options)', and then provides assistance in finding out what the key
     bindings are, and what the mode is intended for.  It returns `nil'.

     This can be customized by changing the map `Helper-help-map'.

Files
*****

   In Emacs, you can find, create, view, save, and otherwise work with
files and file directories.  This chapter describes most of the
file-related functions of Emacs Lisp, but a few others are described in
Buffers, and those related to backups and auto-saving are
described in Backups and Auto-Saving.

Visiting Files
==============

   Visiting a file means reading a file into a buffer.  Once this is
done, we say that the buffer is "visiting" that file, and call the file
"the visited file" of the buffer.

   A file and a buffer are two different things.  A file is information
recorded permanently in the computer (unless you delete it).  A buffer,
on the other hand, is information inside of Emacs that will vanish at
the end of the editing session (or when you kill the buffer).  Usually,
a buffer contains information that you have copied from a file; then we
say the buffer is visiting that file.  The copy in the buffer is what
you modify with editing commands.  Such changes to the buffer do not
change the file; therefore, to make the changes permanent, you must
"save" the buffer, which means copying the altered buffer contents back
into the file.

   In spite of the distinction between files and buffers, people often
refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
"I am editing a file," rather than, "I am editing a buffer which I will
soon save as a file of the same name."  Humans do not usually need to
make the distinction explicit.  When dealing with a computer program,
however, it is good to keep the distinction in mind.

Functions for Visiting Files
----------------------------

   This section describes the functions normally used to visit files.
For historical reasons, these functions have names starting with
`find-' rather than `visit-'.  See Buffer File Name, for functions
and variables that access the visited file name of a buffer or that
find an existing buffer by its visited file name.

 - Command: find-file FILENAME
     This function reads the file FILENAME into a buffer and displays
     that buffer in the selected window so that the user can edit it.

     The body of the `find-file' function is very simple and looks like
     this:

          (switch-to-buffer (find-file-noselect filename))

     (See `switch-to-buffer' in Displaying Buffers.)

     When `find-file' is called interactively, it prompts for FILENAME
     in the minibuffer.

 - Function: find-file-noselect FILENAME &optional NOWARN
     This function is the guts of all the file-visiting functions.  It
     reads a file into a buffer and returns the buffer.  You may then
     make the buffer current or display it in a window if you wish, but
     this function does not do so.

     If no buffer is currently visiting FILENAME, then one is created
     and the file is visited.  If FILENAME does not exist, the buffer
     is left empty, and `find-file-noselect' displays the message `New
     file' in the echo area.

     If a buffer is already visiting FILENAME, then the
     `find-file-noselect' function uses that buffer rather than creating
     a new one.  However, it does verify that the file has not changed
     since it was last visited or saved in that buffer.  If the file
     has changed, then this function asks the user whether to reread
     the changed file.  If the user says `yes', any changes previously
     made in the buffer are lost.

     If NO-WARN is non-`nil', various warnings that Emacs normally
     gives (e.g. if another buffer is already visiting FILENAME but
     FILENAME has been removed from disk since that buffer was created)
     are suppressed.

     The `find-file-noselect' function calls `after-find-file' after
     the file is read in (see Subroutines of Visiting.).  The
     `after-find-file' function sets the buffer major mode, parses local
     variables, warns the user if there exists an auto-save file more
     recent than the file just visited (unless NO-WARN is given), and
     finishes by running the functions in `find-file-hooks'.

     The `find-file-noselect' function returns the buffer that is
     visiting the file FILENAME.

          (find-file-noselect "/etc/fstab")
               => #<buffer fstab>

 - Command: find-alternate-file FILENAME
     This function reads the file FILENAME into a buffer and selects
     it, killing the buffer current at the time the command is run.  It
     is useful if you have visited the wrong file by mistake, so that
     you can get rid of the buffer that you did not want to create, at
     the same time as you visit the file you intended.

     When this function is called interactively, it prompts for
     FILENAME.

 - Command: find-file-other-window FILENAME
     This function visits the file FILENAME and displays its buffer in
     a window other than the selected window.  It may use another
     existing window or split a window; see Displaying Buffers.

     When this function is called interactively, it prompts for
     FILENAME.

 - Command: find-file-read-only FILENAME
     This function visits the file named FILENAME and selects its
     buffer, just like `find-file', but it marks the buffer as
     read-only.  See Read Only Buffers, for related functions and
     variables.

     When this function is called interactively, it prompts for
     FILENAME.

 - Command: view-file FILENAME
     This function views FILENAME in View mode, returning to the
     previous buffer when done.  View mode is a mode that allows you to
     skim rapidly through the file but does not let you modify it.

     After loading the file, `view-file' runs the normal hook
     `view-hook' using `run-hooks'.  See Hooks.

     When this function is called interactively, it prompts for
     FILENAME.

 - Variable: find-file-hooks
     The value of this variable is a list of functions to be called
     after a file is visited.  The file's local-variables specification
     (if any) will have been processed before the hooks are run.  The
     buffer visiting the file is current when the hook functions are
     run.

     This variable could be a normal hook, but we think that renaming it
     would not be advisable.

 - Variable: find-file-not-found-hooks
     The value of this variable is a list of functions to be called when
     `find-file' or `find-file-noselect' is passed a nonexistent
     FILENAME.  These functions are called as soon as the error is
     detected.  `buffer-file-name' is already set up.  The functions are
     called in the order given, until one of them returns non-`nil'.

     This is not a normal hook because the values of the functions are
     used and they may not all be run.

Subroutines of Visiting
-----------------------

   The `find-file-noselect' function uses the `create-file-buffer' and
`after-find-file' functions as subroutines.  Sometimes it is useful to
call them directly.

 - Function: create-file-buffer FILENAME
     This function creates a suitably named buffer for visiting
     FILENAME, and returns it.  The string FILENAME (sans directory) is
     used unchanged if that name is free; otherwise, a string such as
     `<2>' is appended to get an unused name.  See also Creating Buffers.

     *Please note:* `create-file-buffer' does *not* associate the new
     buffer with a file and does not make it the current buffer.

          (create-file-buffer "foo")
               => #<buffer foo>
          (create-file-buffer "foo")
               => #<buffer foo<2>>
          (create-file-buffer "foo")
               => #<buffer foo<3>>

     This function is used by `find-file-noselect'.  It uses
     `generate-new-buffer' (see Creating Buffers.).

 - Function: after-find-file &optional ERROR WARN NOAUTO
     This function is called by `find-file-noselect' and by the default
     revert function (see Reverting.).  It sets the buffer major
     mode, and parses local variables (see Auto Major Mode.).

     If there was an error in opening the file, the calling function
     should pass ERROR a non-`nil' value.  In that case,
     `after-find-file' issues a warning: `(New File)'.  Note that, for
     serious errors, you would not even call `after-find-file'.  Only
     "file not found" errors get here with a non-`nil' ERROR.

     If WARN is non-`nil', then this function issues a warning if an
     auto-save file exists and is more recent than the visited file.

     If NOAUTO is non-`nil', then this function does not turn on
     auto-save mode; otherwise, it does.

     The last thing `after-find-file' does is call all the functions in
     `find-file-hooks'.