   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.

Syntax Table Functions
======================

   In this section we describe functions for creating, accessing and
altering syntax tables.

 - Function: make-syntax-table &optional TABLE
     This function constructs a copy of TABLE and returns it.  If TABLE
     is not supplied (or is `nil'), it returns a copy of the current
     syntax table.  Otherwise, an error is signaled if TABLE is not a
     syntax table.

 - Function: copy-syntax-table &optional TABLE
     This function is identical to `make-syntax-table'.

 - Command: modify-syntax-entry CHAR SYNTAX-DESCRIPTOR &optional TABLE
     This function sets the syntax entry for CHAR according to
     SYNTAX-DESCRIPTOR.  The syntax is changed only for TABLE, which
     defaults to the current buffer's syntax table, and not in any
     other syntax table.  The argument SYNTAX-DESCRIPTOR specifies the
     desired syntax; this is a string beginning with a class designator
     character, and optionally containing a matching character and
     flags as well.  See Syntax Descriptors.

     This function always returns `nil'.  The old syntax information in
     the table for this character is discarded.

     An error is signaled if the first character of the syntax
     descriptor is not one of the twelve syntax class designator
     characters.  An error is also signaled if CHAR is not a character.

     Examples:

          ;; Put the space character in class whitespace.
          (modify-syntax-entry ?\  " ")
               => nil

          ;; Make `$' an open parenthesis character,
          ;;   with `^' as its matching close.
          (modify-syntax-entry ?$ "(^")
               => nil

          ;; Make `^' a close parenthesis character,
          ;;   with `$' as its matching open.
          (modify-syntax-entry ?^ ")$")
               => nil

          ;; Make `/' a punctuation character,
          ;;   the first character of a start-comment sequence,
          ;;   and the second character of an end-comment sequence.
          ;;   This is used in C mode.
          (modify-syntax-entry ?/ ".13")
               => nil

 - Function: char-syntax CHARACTER
     This function returns the syntax class of CHARACTER, represented
     by its mnemonic designator character.  This *only* returns the
     class, not any matching parenthesis or flags.

     An error is signaled if CHAR is not a character.

     The first example shows that the syntax class of space is
     whitespace (represented by a space).  The second example shows
     that the syntax of `/' is punctuation in C-mode.  This does not
     show the fact that it is also a comment sequence character.  The
     third example shows that open parenthesis is in the class of open
     parentheses.  This does not show the fact that it has a matching
     character, `)'.

          (char-to-string (char-syntax ?\ ))
               => " "

          (char-to-string (char-syntax ?/))
               => "."

          (char-to-string (char-syntax ?\())
               => "("

 - Function: set-syntax-table TABLE
     This function makes TABLE the syntax table for the current buffer.
     It returns TABLE.

 - Function: syntax-table
     This function returns the current syntax table, which is the table
     for the current buffer.

Motion and Syntax
=================

   This section describes functions for moving across characters in
certain syntax classes.  None of these functions exists in Emacs
version 18 or earlier.

 - Function: skip-syntax-forward SYNTAXES &optional LIMIT
     This function moves point forward across characters whose syntax
     classes are mentioned in SYNTAXES.  It stops when it encounters
     the end of the buffer, or position LIM (if specified), or a
     character it is not supposed to skip.

     The return value is the distance traveled, which is a nonnegative
     integer.

 - Function: skip-syntax-backward SYNTAXES &optional LIMIT
     This function moves point backward across characters whose syntax
     classes are mentioned in SYNTAXES.  It stops when it encounters
     the beginning of the buffer, or position LIM (if specified), or a
     character it is not supposed to skip.

     The return value indicates the distance traveled.  It is an
     integer that is zero or less.

 - Function: backward-prefix-chars
     This function moves point backward over any number of chars with
     expression prefix syntax.  This includes both characters in the
     expression prefix syntax class, and characters with the `p' flag.

Parsing Balanced Expressions
============================

   Here are several functions for parsing and scanning balanced
expressions.  The syntax table controls the interpretation of
characters, so these functions can be used for Lisp expressions when in
Lisp mode and for C expressions when in C mode.  See List Motion,
for convenient higher-level functions for moving over balanced
expressions.

 - Function: parse-partial-sexp START LIMIT &optional TARGET-DEPTH
          STOP-BEFORE STATE STOP-COMMENT
     This function parses an expression in the current buffer starting
     at START, not scanning past LIMIT.  Parsing stops at LIMIT or when
     certain criteria described below are met; point is set to the
     location where parsing stops.  The value returned is a description
     of the status of the parse at the point where it stops.

     Normally, START is assumed to be the top level of an expression to
     be parsed, such as the beginning of a function definition.
     Alternatively, you might wish to resume parsing in the middle of an
     expression.  To do this, you must provide a STATE argument that
     describes the initial status of parsing.  If STATE is omitted (or
     `nil'), parsing assumes that START is the beginning of a new parse
     at level 0.

     If the third argument TARGET-DEPTH is non-`nil', parsing stops if
     the depth in parentheses becomes equal to TARGET-DEPTH.  The depth
     starts at 0, or at whatever is given in STATE.

     If the fourth argument STOP-BEFORE is non-`nil', parsing stops
     when it comes to any character that starts a sexp.  If
     STOP-COMMENT is non-`nil', parsing stops when it comes to the
     start of a comment.

     The fifth argument STATE is a seven-element list of the same form
     as the value of this function, described below.  The return value
     of one call may be used to initialize the state of the parse on
     another call to `parse-partial-sexp'.

     The result is a list of seven elements describing the final state
     of the parse:

       0. The depth in parentheses, starting at 0.

       1. The character position of the start of the innermost
          containing parenthetical grouping; `nil' if none.

       2. The character position of the start of the last complete
          subexpression terminated; `nil' if none.

       3. Non-`nil' if inside a string.  (It is the character that will
          terminate the string.)

       4. `t' if inside a comment.

       5. `t' if point is just after a quote character.

       6. The minimum parenthesis depth encountered during this scan.

     Elements 1, 4, 5, and 6 are significant in the argument STATE.

     This function is used to determine how to indent lines in programs
     written in languages that have nested parentheses.

 - Function: scan-lists FROM COUNT DEPTH
     This function scans forward COUNT balanced parenthetical groupings
     from character number FROM.  It returns the character number of
     the position thus found.

     If DEPTH is nonzero, parenthesis depth counting begins from that
     value.  The only candidates for stopping are places where the
     depth in parentheses becomes zero; `scan-lists' counts COUNT such
     places and then stops.  Thus, a positive value for DEPTH means go
     out levels of parenthesis.

     Comments are ignored if `parse-sexp-ignore-comments' is non-`nil'.

     If the beginning or end of the buffer (or its accessible portion)
     is reached and the depth is not zero, an error is signaled.  If
     the depth is zero but the count is not used up, `nil' is returned.

 - Function: scan-sexps FROM COUNT
     Scan from character number FROM by COUNT balanced expressions.  It
     returns the character number of the position thus found.

     Comments are ignored if `parse-sexp-ignore-comments' is non-`nil'.

     If the beginning or end of (the accessible part of) the buffer is
     reached in the middle of a parenthetical grouping, an error is
     signaled.  If the beginning or end is reached between groupings but
     before count is used up, `nil' is returned.

 - Variable: parse-sexp-ignore-comments
     If the value is non-`nil', then comments are treated as whitespace
     by the functions in this section and by `forward-sexp'.

     In older Emacs versions, this feature worked only when the comment
     terminator is something like `*/', and appears only to end a
     comment.  In languages where newlines terminate comments, it was
     necessary make this variable `nil', since not every newline is the
     end of a comment.  This limitation no longer exists.

   You can use `forward-comment' to move forward or backward over one
comment or several comments.

 - Function: forward-comment COUNT
     This function moves point forward across COUNT comments (backward,
     if COUNT is negative).  If it finds anything other than a comment
     or whitespace, it stops, leaving point at the place where it
     stopped.  It also stops after satisfying COUNT.

   To move forward over all comments and whitespace following point, use
`(forward-comment (buffer-size))'.  `(buffer-size)' is a good argument
to use, because the number of comments to skip cannot exceed that many.

Some Standard Syntax Tables
===========================

   Each of the major modes in Emacs has its own syntax table.  Here are
several of them:

 - Function: standard-syntax-table
     This function returns the standard syntax table, which is the
     syntax table used in Fundamental mode.

 - Variable: text-mode-syntax-table
     The value of this variable is the syntax table used in Text mode.

 - Variable: c-mode-syntax-table
     The value of this variable is the syntax table in use in C-mode
     buffers.

 - Variable: emacs-lisp-mode-syntax-table
     The value of this variable is the syntax table used in Emacs Lisp
     mode by editing commands.  (It has no effect on the Lisp `read'
     function.)

Syntax Table Internals
======================

   Each element of a syntax table is an integer that translates into the
full meaning of the entry: class, possible matching character, and
flags.  However, it is not common for a programmer to work with the
entries directly in this form since the Lisp-level syntax table
functions usually work with syntax descriptors (see Syntax Descriptors.).

   The low 8 bits of each element of a syntax table indicates the
syntax class.

Integer
     Class

0
     whitespace

1
     punctuation

2
     word

3
     symbol

4
     open parenthesis

5
     close parenthesis

6
     expression prefix

7
     string quote

8
     paired delimiter

9
     escape

10
     character quote

11
     comment-start

12
     comment-end

   The next 8 bits are the matching opposite parenthesis (if the
character has parenthesis syntax); otherwise, they are not meaningful.
The next 6 bits are the flags.

Abbrevs And Abbrev Expansion
****************************

   An abbreviation or "abbrev" is a string of characters that may be
expanded to a longer string.  The user can insert the abbrev string and
find it replaced automatically with the expansion of the abbrev.  This
saves typing.

   The set of abbrevs currently in effect is recorded in an "abbrev
table".  Each buffer has a local abbrev table, but normally all buffers
in the same major mode share one abbrev table.  There is also a global
abbrev table.  Normally both are used.

   An abbrev table is represented as an obarray containing a symbol for
each abbreviation.  The symbol's name is the abbreviation.  Its value is
the expansion; its function definition is the hook; its property list
cell contains the use count, the number of times the abbreviation has
been expanded.  Because these symbols are not interned in the usual
obarray, they will never appear as the result of reading a Lisp
expression; in fact, they will never be used except by the code that
handles abbrevs.  Therefore, it is safe to use them in an extremely
nonstandard way.  See Creating Symbols.

   For the user-level commands for abbrevs, see Abbrev Mode (emacs).

Setting Up Abbrev Mode
======================

   Abbrev mode is a minor mode controlled by the value of the variable
`abbrev-mode'.

 - Variable: abbrev-mode
     A non-`nil' value of this variable turns on the automatic expansion
     of abbrevs when their abbreviations are inserted into a buffer.
     If the value is `nil', abbrevs may be defined, but they are not
     expanded automatically.

     This variable automatically becomes local when set in any fashion.

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

Abbrev Tables
=============

   This section describes how to create and manipulate abbrev tables.

 - Function: make-abbrev-table
     This function creates and returns a new, empty abbrev table--an
     obarray containing no symbols.  It is a vector filled with `nil's.

 - Function: clear-abbrev-table TABLE
     This function undefines all the abbrevs in abbrev table TABLE,
     leaving it empty.  The function returns `nil'.

 - Function: define-abbrev-table TABNAME DEFINITIONS
     This function defines TABNAME (a symbol) as an abbrev table name,
     i.e., as a variable whose value is an abbrev table.  It defines
     abbrevs in the table according to DEFINITIONS, a list of elements
     of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'.  The value is
     always `nil'.

 - Variable: abbrev-table-name-list
     This is a list of symbols whose values are abbrev tables.
     `define-abbrev-table' adds the new abbrev table name to this list.

 - Function: insert-abbrev-table-description NAME &optional HUMAN
     This function inserts before point a description of the abbrev
     table named NAME.  The argument NAME is a symbol whose value is an
     abbrev table.  The value is always `nil'.

     If HUMAN is non-`nil', a human-oriented description is inserted.
     Otherwise the description is a Lisp expression--a call to
     `define-abbrev-table' which would define NAME exactly as it is
     currently defined.

Defining Abbrevs
================

   These functions define an abbrev in a specified abbrev table.
`define-abbrev' is the low-level basic function, while `add-abbrev' is
used by commands that ask for information from the user.

 - Function: add-abbrev TABLE TYPE ARG
     This function adds an abbreviation to abbrev table TABLE.  The
     argument TYPE is a string describing in English the kind of abbrev
     this will be (typically, `"global"' or `"mode-specific"'); this is
     used in prompting the user.  The argument ARG is the number of
     words in the expansion.

     The return value is the symbol which internally represents the new
     abbrev, or `nil' if the user declines to redefine an existing
     abbrev.

 - Function: define-abbrev TABLE NAME EXPANSION HOOK
     This function defines an abbrev in TABLE named NAME, to expand to
     EXPANSION, and call HOOK.  The return value is an uninterned
     symbol which represents the abbrev inside Emacs; its name is NAME.

     The argument NAME should be a string.  The argument EXPANSION
     should be a string, or `nil', to undefine the abbrev.

     The argument HOOK is a function or `nil'.  If HOOK is non-`nil',
     then it is called with no arguments after the abbrev is replaced
     with EXPANSION; point is located at the end of EXPANSION.

     The use count of the abbrev is initialized to zero.

 - User Option: only-global-abbrevs
     If this variable is non-`nil', it means that the user plans to use
     global abbrevs only.  This tells the commands that define
     mode-specific abbrevs to define global ones instead.  This
     variable does not alter the functioning of the functions in this
     section; it is examined by their callers.

Saving Abbrevs in Files
=======================

   A file of saved abbrev definitions is actually a file of Lisp code.
The abbrevs are saved in the form of a Lisp program to define the same
abbrev tables with the same contents.  Therefore, you can load the file
with `load' (see How Programs Do Loading.).  However, the function
`quietly-read-abbrev-file' is provided as a more convenient interface.

   User-level facilities such as `save-some-buffers' can save abbrevs
in a file automatically, under the control of variables described here.

 - User Option: abbrev-file-name
     This is the default file name for reading and saving abbrevs.

 - Function: quietly-read-abbrev-file FILENAME
     This function reads abbrev definitions from a file named FILENAME,
     previously written with `write-abbrev-file'.  If FILENAME is
     `nil', the file specified in `abbrev-file-name' is used.
     `save-abbrevs' is set to `t' so that changes will be saved.

     This function does not display any messages.  It returns `nil'.

 - User Option: save-abbrevs
     A non-`nil' value for `save-abbrev' means that Emacs should save
     abbrevs when files are saved.  `abbrev-file-name' specifies the
     file to save the abbrevs in.

 - Variable: abbrevs-changed
     This variable is set non-`nil' by defining or altering any
     abbrevs.  This serves as a flag for various Emacs commands to
     offer to save your abbrevs.

 - Command: write-abbrev-file FILENAME
     Save all abbrev definitions, in all abbrev tables, in the file
     FILENAME, in the form of a Lisp program which when loaded will
     define the same abbrevs.  This function returns `nil'.

Looking Up and Expanding Abbreviations
======================================

   Abbrevs are usually expanded by commands for interactive use,
including `self-insert-command'.  This section describes the
subroutines used in writing such functions, as well as the variables
they use for communication.

 - Function: abbrev-symbol ABBREV &optional TABLE
     This function returns the symbol representing the abbrev named
     ABBREV.  The value returned is `nil' if that abbrev is not
     defined.  The optional second argument TABLE is the abbrev table
     to look it up in.  By default, this function tries first the
     current buffer's local abbrev table, and second the global abbrev
     table.

 - User Option: abbrev-all-caps
     When this is set non-`nil', an abbrev entered entirely in upper
     case is expanded using all upper case.  Otherwise, an abbrev
     entered entirely in upper case is expanded by capitalizing each
     word of the expansion.

 - Function: abbrev-expansion ABBREV &optional TABLE
     This function returns the string that ABBREV would expand into (as
     defined by the abbrev tables used for the current buffer).  The
     optional argument TABLE specifies the abbrev table to use; if it is
     specified, the abbrev is looked up in that table only.

 - Variable: abbrev-start-location
     This is the buffer position for `expand-abbrev' to use as the start
     of the next abbrev to be expanded.  (`nil' means use the word
     before point instead.)  `abbrev-start-location' is set to `nil'
     each time `expand-abbrev' is called.  This variable is also set by
     `abbrev-prefix-mark'.

 - Variable: abbrev-start-location-buffer
     The value of this variable is the buffer for which
     `abbrev-start-location' has been set.  Trying to expand an abbrev
     in any other buffer clears `abbrev-start-location'.  This variable
     is set by `abbrev-prefix-mark'.

 - Variable: last-abbrev
     This is the `abbrev-symbol' of the last abbrev expanded.  This
     information is left by `expand-abbrev' for the sake of the
     `unexpand-abbrev' command.

 - Variable: last-abbrev-location
     This is the location of the last abbrev expanded.  This contains
     information left by `expand-abbrev' for the sake of the
     `unexpand-abbrev' command.

 - Variable: last-abbrev-text
     This is the exact expansion  text of the last abbrev expanded, as
     results from case conversion.  Its value is `nil' if the abbrev
     has already been unexpanded.  This contains information left by
     `expand-abbrev' for the sake of the `unexpand-abbrev' command.

 - Variable: pre-abbrev-expand-hook
     This is a normal hook whose functions are executed, in sequence,
     just before any expansion of an abbrev.  See Hooks.  Since it
     is a normal hook, the hook functions receive no arguments.
     However, they can find the abbrev to be expanded by looking in the
     buffer before point.

   The following sample code shows a simple use of
`pre-abbrev-expand-hook'.  If the user terminates an abbrev with a
punctuation character, the function issues a prompt.  Thus, this hook
allows the user to decide whether the abbrev should be expanded, and to
abort expansion if it is not desired.

     (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)

     ;; This is the function invoked by `pre-abbrev-expand-hook'.

     ;; If the user terminated the abbrev with a space, the function does
     ;; nothing (that is, it returns so that the abbrev can expand).  If the
     ;; user entered some other character, this function asks whether
     ;; expansion should continue.

     ;; If the user enters the prompt with `y', the function returns
     ;; `nil' (because of the `not' function), but that is
     ;; acceptable; the return value has no effect on expansion.

     (defun query-if-not-space ()
       (if (/= ?\  (preceding-char))
           (if (not (y-or-n-p "Do you want to expand this abbrev? "))
               (error "Not expanding this abbrev"))))

Standard Abbrev Tables
======================

   Here we list the variables that hold the abbrev tables for the
preloaded major modes of Emacs.

 - Variable: global-abbrev-table
     This is the abbrev table for mode-independent abbrevs.  The abbrevs
     defined in it apply to all buffers.  Each buffer may also have a
     local abbrev table, whose abbrev definitions take precedence over
     those in the global table.

 - Variable: local-abbrev-table
     The value of this buffer-local variable is the (mode-specific)
     abbreviation table of the current buffer.

 - Variable: fundamental-mode-abbrev-table
     This is the local abbrev table used in Fundamental mode.  It is the
     local abbrev table in all buffers in Fundamental mode.

 - Variable: text-mode-abbrev-table
     This is the local abbrev table used in Text mode.

 - Variable: c-mode-abbrev-table
     This is the local abbrev table used in C mode.

 - Variable: lisp-mode-abbrev-table
     This is the local abbrev table used in Lisp mode and Emacs Lisp
     mode.

Emacs Display
*************

   This chapter describes a number of features related to the display
that Emacs presents to the user.

Refreshing the Screen
=====================

   The function `redraw-screen' redisplays the entire contents of a
given screen.  See Screens.

 - Function: redraw-screen SCREEN
     This function clears and redisplays screen SCREEN.

   Even more powerful is `redraw-display'.

 - Command: redraw-display
     This function clears and redisplays all visible screens.

   Normally, suspending and resuming Emacs also refreshes the screen.
Some terminal emulators record separate contents for display-oriented
programs such as Emacs and for ordinary sequential display.  If you are
using such a terminal, you might want to inhibit the redisplay on
resumption.  See Suspending Emacs.

 - Variable: no-redraw-on-reenter
     This variable controls whether Emacs redraws the entire screen
     after it has been suspended and resumed.  Non-`nil' means yes,
     `nil' means no.

   The above functions do not actually cause the display to be updated;
rather, they clear out the internal display records that Emacs
maintains, so that the next time the display is updated it will be
redrawn from scratch.  Normally this occurs the next time that
`next-event' or `sit-for' is called; however, a display update will not
occur if there is input pending.  See Input Events.

 - Command: force-redisplay
     This function causes an immediate update of the display in all
     circumstances, whether or not input is pending.

Truncation
==========

   When a line of text extends beyond the right edge of a window, the
line can either be truncated or continued on the next line.  When a line
is truncated, this is shown with a `\' in the rightmost column of the
window.  When a line is continued or "wrapped" onto the next line, this
is shown with a curved arrow in the rightmost column of the window.
The additional screen lines used to display a long text line are called
"continuation" lines.  (Note that wrapped lines are not filled; filling
has nothing to do with continuation and truncation.  See Filling.)

 - User Option: truncate-lines
     This buffer-local variable controls how Emacs displays lines that
     extend beyond the right edge of the window.  If it is non-`nil',
     then Emacs does not display continuation lines; rather each line of
     text occupies exactly one screen line, and a backslash appears at
     the edge of any line that extends to or beyond the edge of the
     window.  The default is `nil'.

     If the variable `truncate-partial-width-windows' is non-`nil',
     then truncation is used for windows that are not the full width of
     the screen, regardless of the value of `truncate-lines'.

 - Variable: default-truncate-lines
     This variable is the default value for `truncate-lines' in buffers
     that do not have local values for it.

 - User Option: truncate-partial-width-windows
     This variable determines how lines that are too wide to fit on the
     screen are displayed in side-by-side windows (see Splitting Windows.).
     If it is non-`nil', then wide lines are truncated
     (with a `\' at the end of the line); otherwise they wrap to the
     next screen line (with a curved arrow at the end of the line).

   You can override the images that indicate continuation or truncation
with the display table; see Display Tables.

The Echo Area
=============

   The "echo area" is used for displaying messages made with the
`message' primitive, and for echoing keystrokes.  It is not the same as
the minibuffer, despite the fact that the minibuffer appears (when
active) in the same place on the screen as the echo area.  The `GNU
Emacs Manual' specifies the rules for resolving conflicts between the
echo area and the minibuffer for use of that screen space (see The Minibuffer (emacs)).
Error messages appear in the echo
area; see Errors.

   You can write output in the echo area by using the Lisp printing
functions with `t' as the stream (see Output Functions.), or as
follows:

 - Function: message STRING &rest ARGUMENTS
     This function prints a one-line message in the echo area.  The
     argument STRING is similar to a C language `printf' control
     string.  See `format' in String Conversion, for the details
     on the conversion specifications.  `message' returns the
     constructed string.

     If STRING is `nil', `message' clears the echo area.  If the
     minibuffer is active, this brings the minibuffer contents back onto
     the screen immediately.
          (message
           "Minibuffer depth is %d."
           (minibuffer-depth))
          => "Minibuffer depth is 0."

          ---------- Echo Area ----------
          Minibuffer depth is 0.
          ---------- Echo Area ----------

 - Variable: cursor-in-echo-area
     This variable controls where the cursor appears when a message is
     displayed in the echo area.  If it is non-`nil', then the cursor
     appears at the end of the message.  Otherwise, the cursor appears
     at point--not in the echo area at all.

     The value is normally `nil'; Lisp programs bind it to `t' for
     brief periods of time.

Selective Display
=================

   "Selective display" is a class of minor modes in which specially
marked lines do not appear on the screen, or in which highly indented
lines do not appear.

   The first variant, explicit selective display, is designed for use in
a Lisp program.  The program controls which lines are hidden by altering
the text.  Outline mode uses this variant.  In the second variant, the
choice of lines to hide is made automatically based on indentation.
This variant is designed as a user-level feature.

   The way you control explicit selective display is by replacing a
newline (control-j) with a control-m.  The text which was formerly a
line following that newline is now invisible.  Strictly speaking, it is
temporarily no longer a line at all, since only newlines can separate
lines; it is now part of the previous line.

   Selective display does not directly affect editing commands.  For
example, `C-f' (`forward-char') moves point unhesitatingly into
invisible space.  However, the replacement of newline characters with
carriage return characters affects some editing commands.  For example,
`next-line' skips invisible lines, since it searches only for newlines.
Modes that use selective display can also define commands that take
account of the newlines, or which make parts of the text visible or
invisible.

   When you write a selectively displayed buffer into a file, all the
control-m's are replaced by their original newlines.  This means that
when you next read in the file, it looks OK, with nothing invisible.
The selective display effect is seen only within Emacs.

 - Variable: selective-display
     This buffer-local variable enables selective display.  This means
     that lines, or portions of lines, may be made invisible.

        * If the value of `selective-display' is `t', then any portion
          of a line that follows a control-m is not displayed.

        * If the value of `selective-display' is a positive integer,
          then lines that start with more than `selective-display'
          columns of indentation are not displayed.

     When some portion of a buffer is invisible, the vertical movement
     commands operate as if that portion did not exist, allowing a
     single `next-line' command to skip any number of invisible lines.
     However, character movement commands (such as `forward-char') do
     not skip the invisible portion, and it is possible (if tricky) to
     insert or delete text in an invisible portion.

     In the examples below, what is shown is the *display* of the buffer
     `foo', which changes with the value of `selective-display'.  The
     *contents* of the buffer do not change.

          (setq selective-display nil)
               => nil

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
            3n this column
            3n this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

          (setq selective-display 2)
               => 2

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

 - Variable: selective-display-ellipses
     If this buffer-local variable is non-`nil', then Emacs displays
     `...' at the end of a line that is followed by invisible text.
     This example is a continuation of the previous one.

          (setq selective-display-ellipses t)
               => t

          ---------- Buffer: foo ----------
          1 on this column
           2on this column ...
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

     You can use a display table to substitute other text for the
     ellipsis (`...').  See Display Tables.

Overlay Arrow
=============

   The "overlay arrow" is useful for directing the user's attention to
a particular line in a buffer.  For example, in the modes used for
interface to debuggers, the overlay arrow indicates the line of code
about to be executed.

 - Variable: overlay-arrow-string
     This variable holds the string to display as an arrow, or `nil' if
     the arrow feature is not in use.

 - Variable: overlay-arrow-position
     This variable holds a marker which indicates where to display the
     arrow.  It should point at the beginning of a line.  The arrow
     text is displayed at the beginning of that line, overlaying any
     text that would otherwise appear.  Since the arrow is usually
     short, and the line usually begins with indentation, normally
     nothing significant is overwritten.

     The overlay string is displayed only in the buffer which this
     marker points into.  Thus, only one buffer can have an overlay
     arrow at any given time.

Temporary Displays
==================

   Temporary displays are used by commands to put output into a buffer
and then present it to the user for perusal rather than for editing.
Many of the help commands use this feature.

 - Special Form: with-output-to-temp-buffer BUFFER-NAME FORMS...
     This function executes FORMS while arranging to insert any output
     they print into the buffer named BUFFER-NAME.  The buffer is then
     shown in some window for viewing, displayed but not selected.

     The string BUFFER-NAME specifies the temporary buffer, which need
     not already exist.  The argument must be a string, not a buffer.
     The buffer is erased initially (with no questions asked), and it is
     marked as unmodified after `with-output-to-temp-buffer' exits.

     `with-output-to-temp-buffer' binds `standard-output' to the
     temporary buffer, then it evaluates the forms in FORMS.  Output
     using the Lisp output functions within FORMS goes by default to
     that buffer (but screen display and messages in the echo area,
     although output in the general sense of the word, are not
     affected).  See Output Functions.

     The value of the last form in FORMS is returned.

          ---------- Buffer: foo ----------
           This is the contents of foo.
          ---------- Buffer: foo ----------

          (with-output-to-temp-buffer "foo"
              (print 20)
              (print standard-output))
          => #<buffer foo>

          ---------- Buffer: foo ----------
          20

          #<buffer foo>

          ---------- Buffer: foo ----------

 - Variable: temp-buffer-show-function
     The value of this variable, if non-`nil', is called as a function
     to display a help buffer.  This variable is used by
     `with-output-to-temp-buffer'.

     In Emacs versions 18 and earlier, this variable was called
     `temp-buffer-show-hook'.

 - Function: momentary-string-display STRING POSITION &optional CHAR
          MESSAGE
     This function momentarily displays STRING in the current buffer at
     POSITION (which is a character offset from the beginning of the
     buffer).  The display remains until the next character is typed.

     If the next character the user types is CHAR, Emacs ignores it.
     Otherwise, that character remains buffered for subsequent use as
     input.  Thus, typing CHAR will simply remove the string from the
     display, while typing (say) `C-f' will remove the string from the
     display and later (presumably) move point forward.  The argument
     CHAR is a space by default.

     The return value of `momentary-string-display' is not meaningful.

     If MESSAGE is non-`nil', it is displayed in the echo area while
     STRING is displayed in the buffer.  If it is `nil', then
     instructions to type CHAR are displayed there, e.g., `Type RET to
     continue editing'.

     In this example, point is initially located at the beginning of the
     second line:

          ---------- Buffer: foo ----------
          This is the contents of foo.
          -!-Second line.
          ---------- Buffer: foo ----------

          (momentary-string-display
             "**** Important Message! ****" (point) ?\r
             "Type RET when done reading")
          => t

          ---------- Buffer: foo ----------
          This is the contents of foo.
          **** Important Message! ****Second line.
          ---------- Buffer: foo ----------

          ---------- Echo Area ----------
          Type RET when done reading
          ---------- Echo Area ----------

     This function works by actually changing the text in the buffer.
     As a result, if you later undo in this buffer, you will see the
     message come and go.

Faces
=====

   A "face" is a named collection of graphical attributes: font,
foreground color, background color, background pixmap, and optional
underlining.  Faces control the display of text on the screen.  Every
face has a name, which is a symbol such as `default' or `modeline'.

   Each face name is meaningful for all screens, and by default it has
the same meaning in all screens.  But you can arrange to give a
particular face name a special meaning in one screen if you wish. (This
is implemented by having, for each face name, a separate face object of
that name associated with each screen.) Each face also has a global,
non-screen version whose attributes you can set; this version determines
the default attributes that the face will have on new screens.

   The face named `default' is used for ordinary text.  The face named
`modeline' is used for displaying the mode line.  The face named
`highlight' is used for highlighted extents (see Extents.).  The
faces named `left-margin' and `right-margin' are used for the left and
right margin areas, respectively (see Annotations.).

Merging Faces for Display
-------------------------

   Here are all the ways to specify which face to use for display of
text:

   * With defaults.  Each screen has a "default face", which is used for
     all text that doesn't somehow specify another face.  The face named
     `default' applies to the text area, while the faces `left-margin'
     and `right-margin' apply to the left and right margin areas.

   * With text properties.  A character may have a `face' property; if
     so, it's displayed with that face. (Text properties are actually
     implemented in terms of extents.) See Text Properties.

   * With extents.  An extent may have a `face' property, which applies
     to all the text covered by the extent; in addition, if the
     `highlight' property is set, the `highlight' property applies when
     the mouse moves over the extent or if the extent is explicitly
     highlighted.  See Extents.

   * With annotations.  Annotations that are inserted into a buffer can
     specify their own face. (Annotations are actually implemented in
     terms of extents.) See Annotations.

   If these various sources together specify more than one face for a
particular character, Emacs merges the attributes of the various faces
specified.  Extents, text properties, and annotations all use the same
underlying representation (as extents).  When multiple extents cover one
character, an extent with higher priority overrides those with lower
priority.  See Extents.  If no extent covers a particular character,
the default face for the screen is used.

   If a background pixmap is specified, it determines what will be
displayed in the background of text characters.  If background pixmap
is actually a pixmap, with its colors specified, those colors are used;
if it is a bitmap, the face's foreground and background colors are used
to color it.

Functions for Working with Faces
--------------------------------

   The attributes a face can specify include the font, the foreground
color, the background color, the background pixmap, and underlining.
The face can also leave these unspecified by giving the value `nil' for
them.  (However, you cannot set the font, foreground color, or
background color of the built-in faces `default', `modeline',
`left-margin', or `right-margin' to `nil').

   Here are the primitives for creating and changing faces.

 - Function: make-face NAME
     This function defines a new face named NAME on all screens,
     initially with all attributes `nil'.  It does nothing if there is
     already a face named NAME.

 - Function: list-faces
     This function returns a list of all defined face names. (This
     function is known as `face-list' in FSF Emacs.)

 - Function: facep OBJECT
     This function returns whether the given object is a face.

 - Function: face-screen FACE
     This function returns the screen of the given face, or `t' if this
     is a global, non-screen face.

   In the following functions, if you specify SCREEN, they affect just
that screen; otherwise, they affect all screens as well as the defaults
that apply to new screens (i.e. the global, non-screen faces).  If you
specify SCREEN as `t', they affect only the global, non-screen faces.

 - Function: copy-face OLD-FACE NEW-NAME &optional SCREEN
     This function defines a new face named NEW-NAME which is a copy of
     the existing face named OLD-FACE.  If there is already a face
     named NEW-NAME, then it alters the face to have the same
     attributes as OLD-FACE.

   You can modify the attributes of an existing face with the following
functions.

 - Function: set-face-foreground FACE COLOR &optional SCREEN
 - Function: set-face-background FACE COLOR &optional SCREEN
     These functions set the foreground (respectively, background)
     color of face FACE to COLOR.  The argument COLOR should be a
     string (the name of a color) or a pixel object as returned by
     `make-pixel' (see Pixels.).

 - Function: set-face-background-pixmap FACE PIXMAP &optional SCREEN
     This function sets the background pixmap of face FACE to PIXMAP.
     The argument PIXMAP should be a string (the name of a bitmap or
     pixmap file; the directories listed in the variable
     `x-bitmap-file-path' will be searched) or a pixmap object as
     returned by `make-pixmap' (see Pixmaps.).  The argument may
     also be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and
     HEIGHT are the size in pixels, and DATA is a string, containing
     the raw bits of the bitmap.

 - Function: set-face-font FACE FONT &optional SCREEN
     This function sets the font of face FACE.  The argument FONT
     should be a string or a font object as returned by `make-font'
     (see Fonts.).

 - Function: set-face-underline-p FACE UNDERLINE-P &optional SCREEN
     This function sets the underline attribute of face FACE.

 - Function: invert-face FACE &optional SCREEN
     Swap the foreground and background colors of face FACE.  If the
     face doesn't specify both foreground and background, then its
     foreground and background are set to the default background and
     foreground.

   These functions examine the attributes of a face.  If you don't
specify SCREEN, they refer to the default data for new screens.

 - Function: face-foreground FACE &optional SCREEN
 - Function: face-background FACE &optional SCREEN
     These functions return the foreground (respectively, background)
     color of face FACE.  The argument returned is a pixel object.
     See Pixels.

 - Function: face-background-pixmap FACE &optional SCREEN
     This function return the background pixmap of face FACE.  The
     argument returned is a pixmap object.  See Pixmaps.

 - Function: face-font FACE &optional SCREEN
     This function returns the font of face FACE.  The argument
     returned is a font object. (Note: This is not the same as the
     function `face-font' in FSF Emacs.) See Fonts.

 - Function: face-font-name FACE &optional SCREEN
     This function returns the name of the font of face FACE, or `nil'
     if it is unspecified.  This is basically equivalent to `(font-name
     (face-font FACE SCREEN))' except that it does not cause an error
     if FACE's font is `nil'. (This function is named `face-font' in
     FSF Emacs.)

 - Function: face-underline-p FACE &optional SCREEN
     This function returns the underline attribute of face FACE.

 - Function: face-equal FACE1 FACE2 &optional SCREEN
     This returns `t' if the faces FACE1 and FACE2 have the same
     attributes for display.

 - Function: face-differs-from-default-p FACE &optional SCREEN
     This returns `t' if the face FACE displays differently from the
     default face.  A face is considered to be "the same" as the normal
     face if each attribute is either the same as that of the default
     face or `nil' (meaning to inherit from the default).

Window System Objects
=====================

Fonts
-----

   This section describes how to create and work with font objects,
which encapsulate fonts in the window system.  A font object can be
used as the argument to functions such as `set-face-font' (see
Faces.).

 - Function: fontp OBJECT
     This predicate returns `t' if OBJECT is a font, and `nil'
     otherwise.

 - Function: set-default-font FONT

 - Variable: x-inhibit-font-complaints