Initial revision

1 files changed, 1249 insertions, 0 deletions

diff --git a/lispref/display.texi b/lispref/display.texi
new file mode 100644
index 00000000000..ac8875a5901
--- /dev/null
+++ b/lispref/display.texi
@@ -0,0 +1,1249 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/display
+@node Display, Calendar, System Interface, Top
+@chapter Emacs Display
+
+  This chapter describes a number of features related to the display
+that Emacs presents to the user.
+
+@menu
+* Refresh Screen::      Clearing the screen and redrawing everything on it.
+* Screen Size::         How big is the Emacs screen.
+* Truncation::          Folding or wrapping long text lines.
+* The Echo Area::       Where messages are displayed.
+* Selective Display::   Hiding part of the buffer text.
+* Overlay Arrow::       Display of an arrow to indicate position.
+* Temporary Displays::  Displays that go away automatically.
+* Overlays::            Use overlays to highlight parts of the buffer.
+* Faces::               A face defines a graphics appearance: font, color, etc.
+* Blinking::            How Emacs shows the matching open parenthesis.
+* Inverse Video::       Specifying how the screen looks.
+* Usual Display::       The usual conventions for displaying nonprinting chars.
+* Display Tables::      How to specify other conventions.
+* Beeping::             Audible signal to the user.
+* Window Systems::      Which window system is being used.
+@end menu
+
+@node Refresh Screen
+@section Refreshing the Screen
+
+The function @code{redraw-frame} redisplays the entire contents of a
+given frame.  @xref{Frames}.
+
+@c Emacs 19 feature
+@defun redraw-frame frame
+This function clears and redisplays frame @var{frame}.
+@end defun
+
+Even more powerful is @code{redraw-display}:
+
+@deffn Command redraw-display
+This function clears and redisplays all visible frames.
+@end deffn
+
+  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.  @xref{Suspending Emacs}.
+
+@defvar no-redraw-on-reenter
+@cindex suspend (cf. @code{no-redraw-on-reenter})
+@cindex resume (cf. @code{no-redraw-on-reenter})
+This variable controls whether Emacs redraws the entire screen after it
+has been suspended and resumed.  Non-@code{nil} means yes, @code{nil}
+means no.
+@end defvar
+
+  Processing user input takes absolute priority over redisplay.  If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually---after all the
+input has been processed.
+
+@node Screen Size
+@section Screen Size
+@cindex size of screen
+@cindex screen size
+@cindex display lines
+@cindex display columns
+@cindex resize redisplay
+
+  The screen size functions report or tell Emacs the height or width of
+the terminal.  When you are using multiple frames, they apply to the
+selected frame (@pxref{Frames}).
+
+@defun screen-height
+This function returns the number of lines on the screen that are
+available for display.
+
+@example
+@group
+(screen-height)
+     @result{} 50
+@end group
+@end example
+@end defun
+
+@defun screen-width
+This function returns the number of columns on the screen that are
+available for display.
+
+@example
+@group
+(screen-width)
+     @result{} 80
+@end group
+@end example
+@end defun
+
+@defun set-screen-height lines &optional not-actual-size
+This function declares that the terminal can display @var{lines} lines.
+The sizes of existing windows are altered proportionally to fit.
+
+If @var{not-actual-size} is non-@code{nil}, then Emacs displays
+@var{lines} lines of output, but does not change its value for the
+actual height of the screen.  (Knowing the correct actual size may be
+necessary for correct cursor positioning.)  Using a smaller height than
+the terminal actually implements may be useful to reproduce behavior
+observed on a smaller screen, or if the terminal malfunctions when using
+its whole screen.
+
+If @var{lines} is different from what it was previously, then the
+entire screen is cleared and redisplayed using the new size.
+
+This function returns @code{nil}.
+@end defun
+
+@defun set-screen-width columns &optional not-actual-size
+This function declares that the terminal can display @var{columns}
+columns.  The details are as in @code{set-screen-height}.
+@end defun
+
+@node Truncation
+@section Truncation
+@cindex line wrapping
+@cindex continuation lines
+@cindex @samp{$} in display
+@cindex @samp{\} in display
+
+  When a line of text extends beyond the right edge of a window, the
+line can either be continued on the next screen line, or truncated to
+one screen line.  The additional screen lines used to display a long
+text line are called @dfn{continuation} lines.  Normally, a @samp{$} in
+the rightmost column of the window indicates truncation; a @samp{\} on
+the rightmost column indicates a line that ``wraps'' or is continued
+onto the next line.  (The display table can specify alternative
+indicators; see @ref{Display Table}.)
+
+  Note that continuation is different from filling; continuation happens
+on the screen only, not in the buffer contents, and it breaks a line
+precisely at the right margin, not at a word boundary.  @xref{Filling}.
+
+@defopt truncate-lines
+This buffer-local variable controls how Emacs displays lines that extend
+beyond the right edge of the window.  The default is @code{nil}, which
+specifies continuation.  If the value is non-@code{nil}, then these
+lines are truncated.
+
+If the variable @code{truncate-partial-width-windows} is non-@code{nil},
+then truncation is always used for side-by-side windows (within one
+frame) regardless of the value of @code{truncate-lines}.
+@end defopt
+
+@defvar default-truncate-lines
+This variable is the default value for @code{truncate-lines}, for
+buffers that do not have local values for it.
+@end defvar
+
+@defopt truncate-partial-width-windows
+This variable controls display of lines that extend beyond the right
+edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
+If it is non-@code{nil}, these lines are truncated; otherwise,
+@code{truncate-lines} says what to do with them.
+@end defopt
+
+  You can override the images that indicate continuation or truncation
+with the display table; see @ref{Display Tables}.
+
+@node The Echo Area
+@section The Echo Area
+@cindex error display
+@cindex echo area
+
+  The @dfn{echo area} is used for displaying messages made with the
+@code{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
+@cite{GNU Emacs Manual} specifies the rules for resolving conflicts
+between the echo area and the minibuffer for use of that screen space
+(@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}).
+Error messages appear in the echo area; see @ref{Errors}.
+
+You can write output in the echo area by using the Lisp printing
+functions with @code{t} as the stream (@pxref{Output Functions}), or as
+follows:
+
+@defun message string &rest arguments
+This function prints a one-line message in the echo area.  The
+argument @var{string} is similar to a C language @code{printf} control
+string.  See @code{format} in @ref{String Conversion}, for the details
+on the conversion specifications.  @code{message} returns the
+constructed string.
+
+@c Emacs 19 feature
+If @var{string} is @code{nil}, @code{message} clears the echo area.  If
+the minibuffer is active, this brings the minibuffer contents back onto
+the screen immediately.
+@example
+@group
+(message "Minibuffer depth is %d."
+         (minibuffer-depth))
+ @print{} Minibuffer depth is 0.
+@result{} "Minibuffer depth is 0."
+@end group
+
+@group
+---------- Echo Area ----------
+Minibuffer depth is 0.
+---------- Echo Area ----------
+@end group
+@end example
+@end defun
+
+@defvar cursor-in-echo-area
+This variable controls where the cursor appears when a message is
+displayed in the echo area.  If it is non-@code{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 @code{nil}; Lisp programs bind it to @code{t}
+for brief periods of time.
+@end defvar
+
+@node Selective Display
+@section Selective Display
+@cindex selective display
+
+  @dfn{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 carriage return (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, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
+invisible text.  However, the replacement of newline characters with
+carriage return characters affects some editing commands.  For example,
+@code{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 that make parts of the text
+visible or invisible.
+
+  When you write a selectively displayed buffer into a file, all the
+control-m's are output as 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.
+
+@defvar selective-display
+This buffer-local variable enables selective display.  This means that
+lines, or portions of lines, may be made invisible.  
+
+@itemize @bullet
+@item
+If the value of @code{selective-display} is @code{t}, then any portion
+of a line that follows a control-m is not displayed.
+
+@item
+If the value of @code{selective-display} is a positive integer, then
+lines that start with more than that many columns of indentation are not
+displayed.
+@end itemize
+
+When some portion of a buffer is invisible, the vertical movement
+commands operate as if that portion did not exist, allowing a single
+@code{next-line} command to skip any number of invisible lines.
+However, character movement commands (such as @code{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, we show the @emph{display appearance} of the
+buffer @code{foo}, which changes with the value of
+@code{selective-display}.  The @emph{contents} of the buffer do not
+change.
+
+@example
+@group
+(setq selective-display nil)
+     @result{} 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 ----------
+@end group
+
+@group
+(setq selective-display 2)
+     @result{} 2
+
+---------- Buffer: foo ----------
+1 on this column
+ 2on this column
+ 2on this column
+1 on this column
+---------- Buffer: foo ----------
+@end group
+@end example
+@end defvar
+
+@defvar selective-display-ellipses
+If this buffer-local variable is non-@code{nil}, then Emacs displays
+@samp{@dots{}} at the end of a line that is followed by invisible text.
+This example is a continuation of the previous one.
+
+@example
+@group
+(setq selective-display-ellipses t)
+     @result{} t
+
+---------- Buffer: foo ----------
+1 on this column
+ 2on this column ...
+ 2on this column
+1 on this column
+---------- Buffer: foo ----------
+@end group
+@end example
+
+You can use a display table to substitute other text for the ellipsis
+(@samp{@dots{}}).  @xref{Display Tables}.
+@end defvar
+
+@node Overlay Arrow
+@section The Overlay Arrow
+@cindex overlay arrow
+
+  The @dfn{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.
+
+@defvar overlay-arrow-string
+This variable holds the string to display as an arrow, or @code{nil} if
+the arrow feature is not in use.
+@end defvar
+
+@defvar 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 appears 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.
+@c !!! overlay-arrow-position: but the overlay string may remain in the display
+@c of some other buffer until an update is required.  This should be fixed
+@c now.  Is it?
+@end defvar
+
+@node Temporary Displays
+@section 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.
+
+@defspec with-output-to-temp-buffer buffer-name forms@dots{}
+This function executes @var{forms} while arranging to insert any
+output they print into the buffer named @var{buffer-name}.  The buffer
+is then shown in some window for viewing, displayed but not selected.
+
+The string @var{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 @code{with-output-to-temp-buffer} exits.
+
+@code{with-output-to-temp-buffer} binds @code{standard-output} to the
+temporary buffer, then it evaluates the forms in @var{forms}.  Output
+using the Lisp output functions within @var{forms} goes by default to
+that buffer (but screen display and messages in the echo area, although
+they are ``output'' in the general sense of the word, are not affected).
+@xref{Output Functions}.
+
+The value of the last form in @var{forms} is returned.
+
+@example
+@group
+---------- Buffer: foo ----------
+ This is the contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(with-output-to-temp-buffer "foo"
+    (print 20)
+    (print standard-output))
+@result{} #<buffer foo>
+
+---------- Buffer: foo ----------
+20
+
+#<buffer foo>
+
+---------- Buffer: foo ----------
+@end group
+@end example
+@end defspec
+
+@defvar temp-buffer-show-function
+If this variable, if non-@code{nil}, @code{with-output-to-temp-buffer}
+calls it as a function to do the job of displaying a help buffer.  The
+function gets one argument, which is the buffer it should display.
+
+In Emacs versions 18 and earlier, this variable was called
+@code{temp-buffer-show-hook}.
+@end defvar
+
+@defun momentary-string-display string position &optional char message
+This function momentarily displays @var{string} in the current buffer at
+@var{position}.  It has no effect on the undo list or on the buffer's
+modification status.
+
+The momentary display remains until the next input event.  If the next
+input event is @var{char}, @code{momentary-string-display} ignores it
+and returns.  Otherwise, that event remains buffered for subsequent use
+as input.  Thus, typing @var{char} will simply remove the string from
+the display, while typing (say) @kbd{C-f} will remove the string from
+the display and later (presumably) move point forward.  The argument
+@var{char} is a space by default.
+
+The return value of @code{momentary-string-display} is not meaningful.
+
+If @var{message} is non-@code{nil}, it is displayed in the echo area
+while @var{string} is displayed in the buffer.  If it is @code{nil}, a
+default message says to type @var{char} to continue.
+
+In this example, point is initially located at the beginning of the
+second line:
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the contents of foo.
+@point{}Second line.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(momentary-string-display
+  "**** Important Message! ****"
+  (point) ?\r
+  "Type RET when done reading")
+@result{} t
+@end group
+
+@group
+---------- Buffer: foo ----------
+This is the contents of foo.
+**** Important Message! ****Second line.
+---------- Buffer: foo ----------
+
+---------- Echo Area ----------
+Type RET when done reading
+---------- Echo Area ----------
+@end group
+@end example
+@end defun
+
+@node Overlays
+@section Overlays
+@cindex overlays
+
+You can use @dfn{overlays} to alter the appearance of a buffer's text on
+the screen.  An overlay is an object which belongs to a particular
+buffer, and has a specified beginning and end.  It also has properties
+that you can examine and set; these affect the display of the text
+within the overlay.
+
+@menu
+* Overlay Properties::  How to read and set properties.
+                        What properties do to the screen display.
+* Managing Overlays::   Creating, moving, finding overlays.
+@end menu
+
+@node Overlay Properties
+@subsection Overlay Properties
+
+Overlay properties are like text properties in some respects, but the
+differences are more important than the similarities.  Text properties
+are considered a part of the text; overlays are specifically considered
+not to be part of the text.  Thus, copying text between various buffers
+and strings preserves text properties, but does not try to preserve
+overlays.  Changing a buffer's text properties marks the buffer as
+modified, while moving an overlay or changing its properties does not.
+Unlike text propery changes, overlay changes are not recorded in the
+buffer's undo list.
+
+@table @code
+@item priority
+@kindex priority @r{(overlay property)}
+This property's value (which should be a nonnegative number) determines
+the priority of the overlay.  The priority matters when two or more
+overlays cover the same character and both specify a face for display;
+the one whose @code{priority} value is larger takes priority over the
+other, and its face attributes override the face attributes of the lower
+priority overlay.
+
+Currently, all overlays take priority over text properties.  Please
+avoid using negative priority values, as we have not yet decided just
+what they should mean.
+
+@item window
+@kindex window @r{(overlay property)}
+If the @code{window} property is non-@code{nil}, then the overlay
+applies only on that window.
+
+@item face
+@kindex face @r{(overlay property)}
+This property controls the font and color of text.  @xref{Faces}, for
+more information.  This feature is temporary; in the future, we may
+replace it with other ways of specifying how to display text.
+
+@item mouse-face
+@kindex mouse-face @r{(overlay property)}
+This property is used instead of @code{face} when the mouse is within
+the range of the overlay.  This feature may be temporary, like
+@code{face}.
+
+@item modification-hooks
+@kindex modification-hooks @r{(overlay property)}
+This property's value is a list of functions to be called if any
+character within the overlay is changed or if text is inserted strictly
+within the overlay.  Each function receives two arguments: the beginning
+and end of the part of the buffer being modified.
+
+@item insert-in-front-hooks
+@kindex insert-in-front-hooks @r{(overlay property)}
+This property's value is a list of functions to be called
+if text is inserted right at the beginning of the overlay.
+
+@item insert-behind-hooks
+@kindex insert-behind-hooks @r{(overlay property)}
+This property's value is a list of functions to be called if text is
+inserted right at the end of the overlay.
+
+@item invisible
+@kindex invisible @r{(overlay property)}
+A non-@code{nil} @code{invisible} property means that the text in the
+overlay does not appear on the screen.  This works much like selective
+display.  Details of this feature are likely to change in future
+versions, so check the @file{etc/NEWS} file in the version you are
+using.
+
+@item before-string
+@kindex before-string @r{(overlay property)}
+This property's value is a string to add to the display at the beginning
+of the overlay.  The string does not appear in the buffer in any
+sense---only on the screen.  This is not yet implemented, but will be.
+
+@item after-string
+@kindex after-string @r{(overlay property)}
+This property's value is a string to add to the display at the end of
+the overlay.  The string does not appear in the buffer in any
+sense---only on the screen.  This is not yet implemented, but will be.
+@end table
+
+  These are the functions for reading and writing the properties of an
+overlay.
+
+@defun overlay-get overlay prop
+This function returns the value of property @var{prop} recorded in
+@var{overlay}.  If @var{overlay} does not record any value for that
+property, then the value is @code{nil}.
+@end defun
+
+@defun overlay-put overlay prop value
+This function sets the value of property @var{prop} recorded in
+@var{overlay} to @var{value}.  It returns @var{value}.
+@end defun
+
+  See also the function @code{get-char-property} which checks both
+overlay properties and text properties for a given character.
+@xref{Examining Properties}.
+
+@node Managing Overlays
+@subsection Managing Overlays
+
+  This section describes the functions to create, delete and move
+overlays, and to examine their contents.
+
+@defun make-overlay start end &optional buffer
+This function creates and returns an overlay which belongs to
+@var{buffer} and ranges from @var{start} to @var{end}.  Both @var{start}
+and @var{end} must specify buffer positions; they may be integers or
+markers.  If @var{buffer} is omitted, the overlay is created in the
+current buffer.
+@end defun
+
+@defun overlay-start overlay
+This function returns the position at which @var{overlay} starts.
+@end defun
+
+@defun overlay-end overlay
+This function returns the position at which @var{overlay} ends.
+@end defun
+
+@defun overlay-buffer overlay
+This function returns the buffer that @var{overlay} belongs to.
+@end defun
+
+@defun delete-overlay overlay
+This function deletes @var{overlay}.  The overlay continues to exist as
+a Lisp object, but ceases to be part of the buffer it belonged to, and
+ceases to have any effect on display.
+@end defun
+
+@defun move-overlay overlay start end &optional buffer
+This function moves @var{overlay} to @var{buffer}, and places its bounds
+at @var{start} and @var{end}.  Both arguments @var{start} and @var{end}
+must specify buffer positions; they may be integers or markers.  If
+@var{buffer} is omitted, the overlay stays in the same buffer.
+
+The return value is @var{overlay}.
+
+This is the only valid way to change the endpoints of an overlay.  Do
+not try modifying the markers in the overlay by hand, as that fails to
+update other vital data structures and can cause some overlays to be
+``lost''.
+@end defun
+
+@defun overlays-at pos
+This function returns a list of all the overlays that contain position
+@var{pos} in the current buffer.  The list is in no particular order.
+An overlay contains position @var{pos} if it begins at or before
+@var{pos}, and ends after @var{pos}.
+@end defun
+
+@defun next-overlay-change pos
+This function returns the buffer position of the next beginning or end
+of an overlay, after @var{pos}.
+@end defun
+
+@node Faces
+@section Faces
+@cindex face
+
+A @dfn{face} is a named collection of graphical attributes: font,
+foreground color, background color and optional underlining.  Faces
+control the display of text on the screen.
+
+@cindex face id
+Each face has its own @dfn{face id number} which distinguishes faces at
+low levels within Emacs.  However, for most purposes, you can refer to
+faces in Lisp programs by their names.
+
+Each face name is meaningful for all frames, and by default it has the
+same meaning in all frames.  But you can arrange to give a particular
+face name a special meaning in one frame if you wish.
+
+@menu
+* Standard Faces::      The faces Emacs normally comes with.
+* Merging Faces::       How Emacs decides which face to use for a character.
+* Face Functions::      How to define and examine faces.
+@end menu
+
+@node Standard Faces
+@subsection Standard Faces
+
+  This table lists all the standard faces and their uses.
+
+@table @code
+@item default
+@kindex default @r{(face name)}
+This face is used for ordinary text.
+
+@item modeline
+@kindex modeline @r{(face name)}
+This face is used for mode lines and menu bars.
+
+@item region
+@kindex region @r{(face name)}
+This face is used for highlighting the region in Transient Mark mode.
+
+@item secondary-selection
+@kindex secondary-selection @r{(face name)}
+This face is used to show any secondary selection you have made.
+
+@item highlight
+@kindex highlight @r{(face name)}
+This face is meant to be used for highlighting for various purposes.
+
+@item underline
+@kindex underline @r{(face name)}
+This face underlines text.
+
+@item bold
+@kindex bold @r{(face name)}
+This face uses a bold font, if possible.  It uses the bold variant of
+the frame's font, if it has one.  It's up to you to choose a default
+font that has a bold variant, if you want to use one.
+
+@item italic
+@kindex italic @r{(face name)}
+This face uses the italic variant of the frame's font, if it has one.
+
+@item bold-italic
+@kindex bold-italic @r{(face name)}
+This face uses the bold italic variant of the frame's font, if it has
+one.
+@end table
+
+@node Merging Faces
+@subsection Merging Faces for Display
+
+  Here are all the ways to specify which face to use for display of text:
+
+@itemize @bullet
+@item
+With defaults.  Each frame has a @dfn{default face}, whose id number is
+zero, which is used for all text that doesn't somehow specify another
+face.
+
+@item
+With text properties.  A character may have a @code{face} property; if so,
+it's displayed with that face.  @xref{Special Properties}.
+
+If the character has a @code{mouse-face} property, that is used instead
+of the @code{face} property when the mouse is ``near enough'' to the
+character.
+
+@item
+With overlays.  An overlay may have @code{face} and @code{mouse-face}
+properties too; they apply to all the text covered by the overlay.
+
+@item
+With special glyphs.  Each glyph can specify a particular face id
+number.  @xref{Glyphs}.
+@end itemize
+
+  If these various sources together specify more than one face for a
+particular character, Emacs merges the attributes of the various faces
+specified.  The attributes of the faces of special glyphs come first;
+then come attributes of faces from overlays, followed by those from text
+properties, and last the default face.
+
+  When multiple overlays cover one character, an overlay with higher
+priority overrides those with lower priority.  @xref{Overlays}.
+
+  If an attribute such as the font or a color is not specified in any of
+the above ways, the frame's own font or color is used.
+
+@node Face Functions
+@subsection Functions for Working with Faces
+
+  The attributes a face can specify include the font, the foreground
+color, the background color, and underlining.  The face can also leave
+these unspecified by giving the value @code{nil} for them.
+
+  Here are the primitives for creating and changing faces.
+
+@defun make-face name
+This function defines a new face named @var{name}, initially with all
+attributes @code{nil}.  It does nothing if there is already a face named
+@var{name}.
+@end defun
+
+@defun face-list
+This function returns a list of all defined face names.
+@end defun
+
+@defun copy-face old-face new-name &optional frame new-frame
+This function defines the face @var{new-name} as a copy of the existing
+face named @var{old-face}.  It creates the face @var{new-name} if that
+doesn't already exist.
+
+If the optional argument @var{frame} is given, this function applies
+only to that frame.  Otherwise it applies to each frame individually,
+copying attributes from @var{old-face} in each frame to @var{new-face}
+in the same frame.
+
+If the optional argument @var{new-frame} is given, then @code{copy-face}
+copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
+in @var{new-frame}.
+@end defun
+
+  You can modify the attributes of an existing face with the following
+functions.  If you specify @var{frame}, they affect just that frame;
+otherwise, they affect all frames as well as the defaults that apply to
+new frames.
+
+@defun set-face-foreground face color &optional frame
+@defunx set-face-background face color &optional frame
+These functions set the foreground (respectively, background) color of
+face @var{face} to @var{color}.  The argument @var{color} should be a
+string, the name of a color.
+@end defun
+
+@defun set-face-font face font &optional frame
+This function sets the font of face @var{face}.  The argument @var{font}
+should be a string.
+@end defun
+
+@defun set-face-underline-p face underline-p &optional frame
+This function sets the underline attribute of face @var{face}.
+Non-@code{nil} means do underline; @code{nil} means don't.
+@end defun
+
+@defun invert-face face &optional frame
+Swap the foreground and background colors of face @var{face}.  If the
+face doesn't specify both foreground and background, then its foreground
+and background are set to the default background and foreground.
+@end defun
+
+  These functions examine the attributes of a face.  If you don't
+specify @var{frame}, they refer to the default data for new frames.
+
+@defun face-foreground face &optional frame
+@defunx face-background face &optional frame
+These functions return the foreground (respectively, background) color
+of face @var{face}, as a string.
+@end defun
+
+@defun face-font face &optional frame
+This function returns the name of the font of face @var{face}.
+@end defun
+
+@defun face-underline-p face &optional frame
+This function returns the underline attribute of face @var{face}.
+@end defun
+
+@defun face-id-number face
+This function returns the face id number of face @var{face}.
+@end defun
+
+@defun face-equal face1 face2 &optional frame
+This returns @code{t} if the faces @var{face1} and @var{face2} have the
+same attributes for display.
+@end defun
+
+@defun face-differs-from-default-p face &optional frame
+This returns @code{t} if the face @var{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
+@code{nil} (meaning to inherit from the default).
+@end defun
+
+@defvar region-face
+This variable's value specifies the face id to use to display characters
+in the region when it is active (in Transient Mark mode only).  The face
+thus specified takes precedence over all faces that come from text
+properties and overlays, for characters in the region.  @xref{The Mark},
+for more information about Transient Mark mode.
+
+Normally, the value is the id number of the face named @code{region}.
+@end defvar
+
+@node Blinking
+@section Blinking Parentheses
+@cindex parenthesis matching
+@cindex blinking
+@cindex balancing parentheses
+@cindex close parenthesis
+
+  This section describes the mechanism by which Emacs shows a matching
+open parenthesis when the user inserts a close parenthesis.
+
+@vindex blink-paren-hook
+@defvar blink-paren-function
+The value of this variable should be a function (of no arguments) to
+be called whenever a character with close parenthesis syntax is inserted.
+The value of @code{blink-paren-function} may be @code{nil}, in which
+case nothing is done.
+
+@quotation
+@strong{Please note:} this variable was named @code{blink-paren-hook} in
+older Emacs versions, but since it is not called with the standard
+convention for hooks, it was renamed to @code{blink-paren-function} in
+version 19.
+@end quotation
+@end defvar
+
+@defvar blink-matching-paren
+If this variable is @code{nil}, then @code{blink-matching-open} does
+nothing.
+@end defvar
+
+@defvar blink-matching-paren-distance
+This variable specifies the maximum distance to scan for a matching
+parenthesis before giving up.
+@end defvar
+
+@defun blink-matching-open
+This function is the default value of @code{blink-paren-function}.  It
+assumes that point follows a character with close parenthesis syntax and
+moves the cursor momentarily to the matching opening character.  If that
+character is not already on the screen, it displays the character's
+context in the echo area.  To avoid long delays, this function does not
+search farther than @code{blink-matching-paren-distance} characters.
+
+Here is an example of calling this function explicitly.
+
+@smallexample
+@group
+(defun interactive-blink-matching-open ()
+@c Do not break this line! -- rms.
+@c The first line of a doc string
+@c must stand alone.
+  "Indicate momentarily the start of sexp before point."
+  (interactive)
+@end group
+@group
+  (let ((blink-matching-paren-distance
+         (buffer-size))
+        (blink-matching-paren t))
+    (blink-matching-open)))
+@end group
+@end smallexample
+@end defun
+
+@node Inverse Video
+@section Inverse Video
+@cindex Inverse Video
+
+@defopt inverse-video
+@cindex highlighting
+This variable controls whether Emacs uses inverse video for all text
+on the screen.  Non-@code{nil} means yes, @code{nil} means no.  The
+default is @code{nil}.
+@end defopt
+
+@defopt mode-line-inverse-video
+This variable controls the use of inverse video for mode lines.  If it
+is non-@code{nil}, then mode lines are displayed in inverse video (under
+X, this uses the face named @code{modeline}, which you can set as you
+wish).  Otherwise, mode lines are displayed normally, just like text.
+The default is @code{t}.
+@end defopt
+
+@node Usual Display
+@section Usual Display Conventions
+
+  The usual display conventions define how to display each character
+code.  You can override these conventions by setting up a display table
+(@pxref{Display Tables}).  Here are the usual display conventions:
+
+@itemize @bullet
+@item
+Character codes 32 through 126 map to glyph codes 32 through 126.
+Normally this means they display as themselves.
+
+@item
+Character code 9 is a horizontal tab.  It displays as whitespace
+up to a position determined by @code{tab-width}.
+
+@item
+Character code 10 is a newline.
+
+@item
+All other codes in the range 0 through 31, and code 127, display in one
+of two ways according to the value of @code{ctl-arrow}.  If it is is
+non-@code{nil}, these codes map to sequences of two glyphs, where the
+first glyph is the @sc{ASCII} code for @samp{^}.  (A display table can
+specify a glyph to use instead of @samp{^}.)  Otherwise, these codes map
+just like the codes in the range 128 to 255.
+
+@item
+Character codes 128 through 255 map to sequences of four glyphs, where
+the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
+digit characters representing the code in octal.  (A display table can
+specify a glyph to use instead of @samp{\}.)
+@end itemize
+
+  The usual display conventions apply even when there is a display
+table, for any character whose entry in the active display table is
+@code{nil}.  Thus, when you set up a display table, you need only
+specify the the characters for which you want unusual behavior.
+
+  These variables affect the way certain characters are displayed on the
+screen.  Since they change the number of columns the characters occupy,
+they also affect the indentation functions.
+
+@defopt ctl-arrow
+@cindex control characters in display
+This buffer-local variable controls how control characters are
+displayed.  If it is non-@code{nil}, they are displayed as a caret
+followed by the character: @samp{^A}.  If it is @code{nil}, they are
+displayed as a backslash followed by three octal digits: @samp{\001}.
+@end defopt
+
+@c Following may have overfull hbox.
+@defvar default-ctl-arrow
+The value of this variable is the default value for @code{ctl-arrow} in
+buffers that do not override it.  @xref{Default Value}.
+@end defvar
+
+@defopt tab-width
+The value of this variable is the spacing between tab stops used for
+displaying tab characters in Emacs buffers.  The default is 8.  Note
+that this feature is completely independent from the user-settable tab
+stops used by the command @code{tab-to-tab-stop}.  @xref{Indent Tabs}.
+@end defopt
+
+@node Display Tables
+@section Display Tables
+
+@cindex display table
+You can use the @dfn{display table} feature to control how all 256
+possible character codes display on the screen.  This is useful for
+displaying European languages that have letters not in the @sc{ASCII}
+character set.
+
+The display table maps each character code into a sequence of
+@dfn{glyphs}, each glyph being an image that takes up one character
+position on the screen.  You can also define how to display each glyph
+on your terminal, using the @dfn{glyph table}.
+
+@menu
+* Display Table Format::        What a display table consists of.
+* Active Display Table::        How Emacs selects a display table to use.
+* Glyphs::                      How to define a glyph, and what glyphs mean.
+* ISO Latin 1::                 How to use display tables
+                                  to support the ISO Latin 1 character set.
+@end menu
+
+@node Display Table Format
+@subsection Display Table Format
+
+  A display table is actually an array of 261 elements.
+
+@defun make-display-table
+This creates and returns a display table.  The table initially has
+@code{nil} in all elements.
+@end defun
+
+  The first 256 elements correspond to character codes; the @var{n}th
+element says how to display the character code @var{n}.  The value
+should be @code{nil} or a vector of glyph values (@pxref{Glyphs}).  If
+an element is @code{nil}, it says to display that character according to
+the usual display conventions (@pxref{Usual Display}).
+
+  The remaining five elements of a display table serve special purposes,
+and @code{nil} means use the default stated below.
+
+@table @asis
+@item 256
+The glyph for the end of a truncated screen line (the default for this
+is @samp{$}).  @xref{Glyphs}.
+@item 257
+The glyph for the end of a continued line (the default is @samp{\}).
+@item 258
+The glyph for indicating a character displayed as an octal character
+code (the default is @samp{\}).
+@item 259
+The glyph for indicating a control character (the default is @samp{^}).
+@item 260
+A vector of glyphs for indicating the presence of invisible lines (the
+default is @samp{...}).  @xref{Selective Display}.
+@end table
+
+  For example, here is how to construct a display table that mimics the
+effect of setting @code{ctl-arrow} to a non-@code{nil} value:
+
+@example
+(setq disptab (make-display-table))
+(let ((i 0))
+  (while (< i 32)
+    (or (= i ?\t) (= i ?\n)
+        (aset disptab i (vector ?^ (+ i 64))))
+    (setq i (1+ i)))
+  (aset disptab 127 (vector ?^ ??)))
+@end example
+
+@node Active Display Table
+@subsection Active Display Table
+@cindex active display table
+
+  Each window can specify a display table, and so can each buffer.  When
+a buffer @var{b} is displayed in window @var{w}, display uses the
+display table for window @var{w} if it has one; otherwise, the display
+table for buffer @var{b} if it has one; otherwise, the standard display
+table if any.  The display table chosen is called the @dfn{active}
+display table.
+
+@defun window-display-table window
+This function returns @var{window}'s display table, or @code{nil}
+if @var{window} does not have an assigned display table.
+@end defun
+
+@defun set-window-display-table window table
+This function sets the display table of @var{window} to @var{table}.
+The argument @var{table} should be either a display table or
+@code{nil}.
+@end defun
+
+@defvar buffer-display-table
+This variable is automatically local in all buffers; its value in a
+particular buffer is the display table for that buffer, or @code{nil} if
+the buffer does not have an assigned display table.
+@end defvar
+
+@defvar standard-display-table
+This variable's value is the default display table, used whenever a
+window has no display table and neither does the buffer displayed in
+that window.  This variable is @code{nil} by default.
+@end defvar
+
+  If there is no display table to use for a particular window---that is,
+if the window has none, its buffer has none, and
+@code{standard-display-table} has none---then Emacs uses the usual
+display conventions for all character codes in that window.  @xref{Usual
+Display}.
+
+@node Glyphs
+@subsection Glyphs
+
+@cindex glyph
+  A @dfn{glyph} is a generalization of a character; it stands for an
+image that takes up a single character position on the screen.  Glyphs
+are represented in Lisp as integers, just as characters are.
+
+@cindex glyph table
+  The meaning of each integer, as a glyph, is defined by the glyph
+table, which is the value of the variable @code{glyph-table}.
+
+@defvar glyph-table
+The value of this variable is the current glyph table.  It should be a
+vector; the @var{g}th element defines glyph code @var{g}.  If the value
+is @code{nil} instead of a vector, then all glyphs are simple (see
+below).
+@end defvar
+
+  Here are the possible types of elements in the glyph table:
+
+@table @var
+@item string
+Send the characters in @var{string} to the terminal to output
+this glyph.  This alternative is available on character terminals,
+but not under X.
+
+@item integer
+Define this glyph code as an alias for code @var{integer}.  You can use
+an alias to specify a face code for the glyph; see below.
+
+@item @code{nil}
+This glyph is simple.  On an ordinary terminal, the glyph code mod 256
+is the character to output.  With X, the glyph code mod 256 is the
+character to output, and the glyph code divided by 256 specifies the
+@dfn{face id number} to use while outputting it.  @xref{Faces}.
+@end table
+
+  If a glyph code is greater than or equal to the length of the glyph
+table, that code is automatically simple.
+
+@node ISO Latin 1
+@subsection ISO Latin 1
+
+If you have a terminal that can handle the entire ISO Latin 1 character
+set, you can arrange to use that character set as follows:
+
+@example
+(require 'disp-table)
+;; @r{Set char codes 160--255 to display as themselves.}
+;; @r{(Codes 128--159 are the additional control characters.)}
+(standard-display-8bit 160 255)
+@end example
+
+If you are editing buffers written in the ISO Latin 1 character set and
+your terminal doesn't handle anything but @sc{ASCII}, you can load the file
+@file{iso-ascii} to set up a display table which makes the other ISO
+characters display as sequences of @sc{ASCII} characters.  For example, the
+character ``o with umlaut'' displays as @samp{@{"o@}}.
+
+Some European countries have terminals that don't support ISO Latin 1
+but do support the special characters for that country's language.  You
+can define a display table to work one language using such terminals.
+For an example, see @file{lisp/iso-swed.el}, which handles certain
+Swedish terminals.
+
+You can load the appropriate display table for your terminal
+automatically by writing a terminal-specific Lisp file for the terminal
+type.
+
+@node Beeping
+@section Beeping
+@cindex beeping
+@cindex bell
+
+  You can make Emacs ring a bell (or blink the screen) to attract the
+user's attention.  Be conservative about how often you do this; frequent
+bells can become irritating.  Also be careful not to use beeping alone
+when signaling an error is appropriate.  (@xref{Errors}.)
+
+@defun ding &optional dont-terminate
+@cindex keyboard macro termination
+This function beeps, or flashes the screen (see @code{visible-bell} below).
+It also terminates any keyboard macro currently executing unless
+@var{dont-terminate} is non-@code{nil}.
+@end defun
+
+@defun beep &optional dont-terminate
+This is a synonym for @code{ding}.
+@end defun
+
+@defvar visible-bell
+This variable determines whether Emacs should flash the screen to
+represent a bell.  Non-@code{nil} means yes, @code{nil} means no.  This
+is effective only if the Termcap entry for the terminal in use has the
+visible bell flag (@samp{vb}) set.
+@end defvar
+
+@node Window Systems
+@section Window Systems
+
+  Emacs works with several window systems, most notably the X Window
+System.  Both Emacs and X use the term ``window'', but use it
+differently.  An Emacs frame is a single window as far as X is
+concerned; the individual Emacs windows are not known to X at all.
+
+@defvar window-system
+@cindex X Window System
+This variable tells Lisp programs what window system Emacs is running
+under.  Its value should be a symbol such as @code{x} (if Emacs is
+running under X) or @code{nil} (if Emacs is running on an ordinary
+terminal).
+@end defvar
+
+@defvar window-system-version
+This variable distinguishes between different versions of the X Window
+System.  Its value is 10 or 11 when using X; @code{nil} otherwise.
+@end defvar
+
+@defvar window-setup-hook
+This variable is a normal hook which Emacs runs after loading your
+@file{.emacs} file and the default initialization file (if any), after
+loading terminal-specific Lisp code, and after running the hook
+@code{term-setup-hook}.
+
+This hook is used for internal purposes: setting up communication with
+the window system, and creating the initial window.  Users should not
+interfere with it.
+@end defvar