--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/lispref/display.texi	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,981 @@
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/display.info
+@node Display, Hash Tables, Annotations, Top
+@chapter Emacs Display
+
+  This chapter describes a number of other features related to the display
+that XEmacs presents to the user.
+
+@menu
+* Refresh Screen::      Clearing the screen and redrawing everything on it.
+* Truncation::          Folding or wrapping long text lines.
+* The Echo Area::       Where messages are displayed.
+* Invisible Text::      Hiding part of the buffer text.
+* Selective Display::   Hiding part of the buffer text (the old way).
+* Overlay Arrow::       Display of an arrow to indicate position.
+* Temporary Displays::  Displays that go away automatically.
+* Blinking::            How XEmacs shows the matching open parenthesis.
+* Usual Display::	The usual conventions for displaying nonprinting chars.
+* Display Tables::	How to specify other conventions.
+* Beeping::             Audible signal to the user.
+@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 &optional device
+This function redraws all frames on @var{device} marked as having their
+image garbled.  @var{device} defaults to the selected device.  If
+@var{device} is @code{t}, all devices will have their frames checked.
+@end deffn
+
+  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.
+
+  Normally, suspending and resuming XEmacs also refreshes the screen.
+Some terminal emulators record separate contents for display-oriented
+programs such as XEmacs and for ordinary sequential display.  If you are
+using such a terminal, you might want to inhibit the redisplay on
+resumption.  @xref{Suspending XEmacs}.
+
+@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 XEmacs redraws the entire screen after it
+has been suspended and resumed.  Non-@code{nil} means yes, @code{nil}
+means no.
+@end defvar
+
+@cindex display update
+@cindex update display
+@cindex refresh display
+  The above functions do not actually cause the display to be updated;
+rather, they clear out the internal display records that XEmacs
+maintains, so that the next time the display is updated it will be
+redrawn from scratch.  Normally this occurs the next time that
+@code{next-event} or @code{sit-for} is called; however, a display update
+will not occur if there is input pending.  @xref{Command Loop}.
+
+@deffn Command force-redisplay
+@cindex force redisplay
+This function causes an immediate update of the display in all
+circumstances, whether or not input is pending. (This function does
+not exist in FSF Emacs.)
+@end deffn
+
+@defun force-cursor-redisplay
+This function causes an immediate update of the cursor on the selected
+frame. (This function does not exist in FSF Emacs.)
+@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 truncated or continued on the next line.  When a line
+is truncated, this is normally shown with a @samp{\} in the rightmost
+column of the window on X displays, and with a @samp{$} on TTY devices.
+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 (or with
+a @samp{\} on TTY devices).  The additional screen lines used to display
+a long text line are called @dfn{continuation} lines.
+
+  Normally, whenever line truncation is in effect for a particular
+window, a horizontal scrollbar is displayed in that window if the
+device supports scrollbars.  @xref{Scrollbars}.
+
+  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 XEmacs displays lines that
+extend beyond the right edge of the window.  If it is non-@code{nil},
+then XEmacs 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 @code{nil}.
+
+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
+
+@defopt default-truncate-lines
+This variable is the default value for @code{truncate-lines}, for
+buffers that do not have local values for it.
+@end defopt
+
+@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
+
+  The backslash and curved arrow used to indicate truncated or continued
+lines are only defaults, and can be changed.  These images are actually
+glyphs (@pxref{Glyphs}).  XEmacs provides a great deal of flexibility
+in how glyphs can be controlled. (This differs from FSF Emacs, which
+uses display tables to control these images.)
+
+  For details, @ref{Redisplay Glyphs}.
+
+@ignore Not yet in XEmacs
+  If your buffer contains @strong{very} long lines, and you use
+continuation to display them, just thinking about them can make Emacs
+redisplay slow.  The column computation and indentation functions also
+become slow.  Then you might find it advisable to set
+@code{cache-long-line-scans} to @code{t}.
+
+@defvar cache-long-line-scans
+If this variable is non-@code{nil}, various indentation and motion
+functions, and Emacs redisplay, cache the results of scanning the
+buffer, and consult the cache to avoid rescanning regions of the buffer
+unless they are modified.
+
+Turning on the cache slows down processing of short lines somewhat.
+
+This variable is automatically local in every buffer.
+@end defvar
+@end ignore
+
+@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{XEmacs Reference 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 XEmacs Reference 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 displays 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.
+
+In batch mode, @code{message} prints the message text on the standard
+error stream, followed by a newline.
+
+@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
+
+Almost all the messages displayed in the echo area are also recorded
+in the @samp{*Messages*} buffer.
+
+@defopt message-log-max
+This variable specifies how many lines to keep in the @samp{*Messages*}
+buffer.  The value @code{t} means there is no limit on how many lines to
+keep.  The value @code{nil} disables message logging entirely.  Here's
+how to display a message and prevent it from being logged:
+
+@example
+(let (message-log-max)
+  (message @dots{}))
+@end example
+@end defopt
+
+@defvar echo-keystrokes
+This variable determines how much time should elapse before command
+characters echo.  Its value must be an integer, which specifies the
+number of seconds to wait before echoing.  If the user types a prefix
+key (such as @kbd{C-x}) and then delays this many seconds before
+continuing, the prefix key is echoed in the echo area.  Any subsequent
+characters in the same command will be echoed as well.
+
+If the value is zero, then command input is not echoed.
+@end defvar
+
+@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 Invisible Text
+@section Invisible Text
+
+@cindex invisible text
+You can make characters @dfn{invisible}, so that they do not appear on
+the screen, with the @code{invisible} property.  This can be either a
+text property or a property of an overlay.
+
+In the simplest case, any non-@code{nil} @code{invisible} property makes
+a character invisible.  This is the default case---if you don't alter
+the default value of @code{buffer-invisibility-spec}, this is how the
+@code{invisibility} property works.  This feature is much like selective
+display (@pxref{Selective Display}), but more general and cleaner.
+
+More generally, you can use the variable @code{buffer-invisibility-spec}
+to control which values of the @code{invisible} property make text
+invisible.  This permits you to classify the text into different subsets
+in advance, by giving them different @code{invisible} values, and
+subsequently make various subsets visible or invisible by changing the
+value of @code{buffer-invisibility-spec}.
+
+Controlling visibility with @code{buffer-invisibility-spec} is
+especially useful in a program to display the list of entries in a data
+base.  It permits the implementation of convenient filtering commands to
+view just a part of the entries in the data base.  Setting this variable
+is very fast, much faster than scanning all the text in the buffer
+looking for properties to change.
+
+@defvar buffer-invisibility-spec
+This variable specifies which kinds of @code{invisible} properties
+actually make a character invisible.
+
+@table @asis
+@item @code{t}
+A character is invisible if its @code{invisible} property is
+non-@code{nil}.  This is the default.
+
+@item a list
+Each element of the list makes certain characters invisible.
+Ultimately, a character is invisible if any of the elements of this list
+applies to it.  The list can have two kinds of elements:
+
+@table @code
+@item @var{atom}
+A character is invisible if its @code{invisible} propery value
+is @var{atom} or if it is a list with @var{atom} as a member.
+
+@item (@var{atom} . t)
+A character is invisible if its @code{invisible} propery value
+is @var{atom} or if it is a list with @var{atom} as a member.
+Moreover, if this character is at the end of a line and is followed
+by a visible newline, it displays an ellipsis.
+@end table
+@end table
+@end defvar
+
+  Ordinarily, commands that operate on text or move point do not care
+whether the text is invisible.  However, the user-level line motion
+commands explicitly ignore invisible newlines.
+
+@node Selective Display
+@section Selective Display
+@cindex selective display
+
+  @dfn{Selective display} is a pair of features that hide certain
+lines on the screen.
+
+  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 has traditionally used this variant.  It has
+been partially replaced by the invisible text feature (@pxref{Invisible
+Text}); there is a new version of Outline mode which uses that instead.
+
+  In the second variant, the choice of lines to hide is made
+automatically based on indentation.  This variant is designed to be 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 that
+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 XEmacs.
+
+@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 XEmacs 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 to call attention to a
+particular line, or @code{nil} if the arrow feature is not in use.
+Despite its name, the value of this variable can be either a string
+or a glyph (@pxref{Glyphs}).
+@end defvar
+
+@defvar overlay-arrow-position
+This variable holds a marker that indicates where to display the overlay
+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 that 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
+
+  You can do the same job by creating an extent with a
+@code{begin-glyph} property.  @xref{Extent Properties}.
+
+@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 is 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.
+
+You can do the same job in a more general way by creating an extent
+with a begin-glyph property.  @xref{Extent Properties}.
+
+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
+
+  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.
+@end defun
+
+@node Blinking
+@section Blinking Parentheses
+@cindex parenthesis matching
+@cindex blinking
+@cindex balancing parentheses
+@cindex close parenthesis
+
+  This section describes the mechanism by which XEmacs 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
+
+@defvar blink-matching-paren-delay
+This variable specifies the number of seconds for the cursor to remain
+at the matching parenthesis.  A fraction of a second often gives
+good results, but the default is 1, which works on all systems.
+@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 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
+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 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{runes}, each rune being an image that takes up one character
+position on the screen.  You can also define how to display each rune
+on your terminal, using the @dfn{rune table}.
+
+@menu
+* Display Table Format::	What a display table consists of.
+* Active Display Table::	How XEmacs selects a display table to use.
+* Character Descriptors::	Format of an individual element of a
+				  display table.
+@end menu
+
+@ignore Not yet working in XEmacs?
+* ISO Latin 1::			How to use display tables
+				  to support the ISO Latin 1 character set.
+@end ignore
+
+@node Display Table Format
+@subsection Display Table Format
+
+  A display table is an array of 256 elements. (In FSF Emacs, a display
+table is 262 elements.  The six extra elements specify the truncation
+and continuation glyphs, etc.  This method is very kludgey, and in
+XEmacs the variables @code{truncation-glyph}, @code{continuation-glyph},
+etc. are used.  @xref{Truncation}.)
+
+@defun make-display-table
+This creates and returns a display table.  The table initially has
+@code{nil} in all elements.
+@end defun
+
+  The 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}, a string, a glyph, or a vector of strings and
+glyphs (@pxref{Character Descriptors}).  If an element is @code{nil},
+it says to display that character according to the usual display
+conventions (@pxref{Usual Display}).
+
+  If you use the display table to change the display of newline
+characters, the whole buffer will be displayed as one long ``line.''
+
+  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 (concat "^" (char-to-string (+ i 64)))))
+    (setq i (1+ i)))
+  (aset disptab 127 "^?"))
+@end example
+
+@node Active Display Table
+@subsection Active Display Table
+@cindex active display table
+
+  The active display table is controlled by the variable
+@code{current-display-table}.  This is a specifier, which means
+that you can specify separate values for it in individual buffers,
+windows, frames, and devices, as well as a global value.  It also
+means that you cannot set this variable using @code{setq}; use
+@code{set-specifier} instead.  @xref{Specifiers}. (FSF Emacs
+uses @code{window-display-table}, @code{buffer-display-table},
+@code{standard-display-table}, etc. to control the display table.
+However, specifiers are a cleaner and more powerful way of doing
+the same thing.  FSF Emacs also uses a different format for
+the contents of a display table, using additional indirection
+to a ``glyph table'' and such.  Note that ``glyph'' has a different
+meaning in XEmacs.)
+
+  Individual faces can also specify an overriding display table;
+this is set using @code{set-face-display-table}.  @xref{Faces}.
+
+  If no display table can be determined for a particular window,
+then XEmacs uses the usual display conventions.  @xref{Usual Display}.
+
+@node Character Descriptors
+@subsection Character Descriptors
+
+@cindex character descriptor
+  Each element of the display-table vector describes how to display
+a particular character and is called a @dfn{character descriptor}.
+A character descriptor can be:
+
+@table @asis
+@item a string
+Display this particular string wherever the character is to be displayed.
+
+@item a glyph
+Display this particular glyph wherever the character is to be displayed.
+
+@item a vector
+The vector may contain strings and/or glyphs.  Display the elements of
+the vector one after another wherever the character is to be displayed.
+
+@item @code{nil}
+Display according to the standard interpretation (@pxref{Usual Display}).
+@end table
+
+@ignore Not yet working in XEmacs?
+@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 that displays the other
+ISO characters as explanatory 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.
+@end ignore
+
+@node Beeping
+@section Beeping
+@cindex beeping
+@cindex bell
+@cindex sound
+
+  You can make XEmacs ring a bell, play a sound, 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 sound device
+@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}.  If @var{sound} is
+specified, it should be a symbol specifying which sound to make.  This
+sound will be played if @code{visible-bell} is @code{nil}. (This only
+works if sound support was compiled into the executable and you are
+running on the console of a Sun SparcStation, SGI, or HP9000s700.
+Otherwise you just get a beep.) The optional third argument specifies
+what device to make the sound on, and defaults to the selected device.
+@end defun
+
+@defun beep &optional dont-terminate sound device
+This is a synonym for @code{ding}.
+@end defun
+
+@defopt visible-bell
+This variable determines whether XEmacs should flash the screen to
+represent a bell.  Non-@code{nil} means yes, @code{nil} means no.  On
+TTY devices, this is effective only if the Termcap entry for the
+terminal type has the visible bell flag (@samp{vb}) set.
+@end defopt
+
+@defvar sound-alist
+  This variable holds an alist associating names with sounds.  When
+@code{beep} or @code{ding} is called with one of the name symbols, the
+associated sound will be generated instead of the standard beep.
+
+  Each element of @code{sound-alist} is a list describing a sound.  The
+first element of the list is the name of the sound being defined.
+Subsequent elements of the list are alternating keyword/value pairs:
+
+@table @code
+@item sound
+A string of raw sound data, or the name of another sound to play.  The
+symbol @code{t} here means use the default X beep.
+@item volume
+An integer from 0-100, defaulting to @code{bell-volume}.
+@item pitch
+If using the default X beep, the pitch (Hz) to generate.
+@item duration
+If using the default X beep, the duration (milliseconds).
+@end table
+
+For compatibility, elements of `sound-alist' may also be:
+
+@itemize @bullet
+@item
+@code{( sound-name . <sound> )}
+@item
+@code{( sound-name <volume> <sound> )}
+@end itemize
+
+You should probably add things to this list by calling the function
+@code{load-sound-file}.
+
+Caveats:
+
+@itemize @minus
+@item
+You can only play audio data if running on the console screen of a Sun
+SparcStation, SGI, or HP9000s700.
+
+@item
+The pitch, duration, and volume options are available everywhere, but
+many X servers ignore the `pitch' option.
+@end itemize
+
+The following beep-types are used by XEmacs itself:
+
+@table @code
+@item auto-save-error
+when an auto-save does not succeed
+@item command-error
+when the XEmacs command loop catches an error
+@item undefined-key
+when you type a key that is undefined
+@item undefined-click
+when you use an undefined mouse-click combination
+@item no-completion
+during completing-read
+@item y-or-n-p
+when you type something other than 'y' or 'n'
+@item yes-or-no-p
+when you type something other than 'yes' or 'no'
+@item default
+used when nothing else is appropriate.
+@end table
+
+Other lisp packages may use other beep types, but these are the ones that
+the C kernel of XEmacs uses.
+@end defvar
+
+@defopt bell-volume
+This variable specifies the default volume for sounds, from 0 to 100.
+@end defopt
+
+@deffn Command load-default-sounds
+This function loads and installs some sound files as beep-types.
+@end deffn
+
+@deffn Command load-sound-file filename sound-name &optional volume
+This function reads in an audio file and adds it to @code{sound-alist}.
+The sound file must be in the Sun/NeXT U-LAW format.  @var{sound-name}
+should be a symbol, specifying the name of the sound.  If @var{volume}
+is specified, the sound will be played at that volume; otherwise, the
+value of @var{bell-volume} will be used.
+@end deffn
+
+@defun play-sound sound &optional volume device
+This function plays sound @var{sound}, which should be a symbol
+mentioned in @code{sound-alist}.  If @var{volume} is specified, it
+overrides the value (if any) specified in @code{sound-alist}.
+@var{device} specifies the device to play the sound on, and defaults
+to the selected device.
+@end defun
+
+@deffn Command play-sound-file file &optional volume device
+This function plays the named sound file at volume @var{volume}, which
+defaults to @code{bell-volume}.  @var{device} specifies the device to
+play the sound on, and defaults to the selected device.
+@end deffn