X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/ad800164c88de7d29471d1fac5035c23ad82245d..28f94a3454ace838b06d8bcdd86248d2b87ca57b:/lispref/display.texi

diff --git a/lispref/display.texi b/lispref/display.texi
index 186703b13b..17e4bc57ea 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -16,22 +16,28 @@ that Emacs presents to the user.
 * Truncation::          Folding or wrapping long text lines.
 * The Echo Area::       Where messages are displayed.
 * Warnings::            Displaying warning messages for the user.
+* Progress::            Informing user about progress of a long operation.
 * 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.
-* Overlays::		Use overlays to highlight parts of the buffer.
+* Overlays::            Use overlays to highlight parts of the buffer.
 * Width::               How wide a character or string is on the screen.
-* Faces::		A face defines a graphics style for text characters:
+* Line Height::         Controlling the height of lines.
+* Faces::               A face defines a graphics style for text characters:
                           font, colors, etc.
 * Fringes::             Controlling window fringes.
+* Fringe Bitmaps::      Displaying bitmaps in the window fringes.
+* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
 * Scroll Bars::         Controlling vertical scroll bars.
+* Pointer Shape::       Controlling the mouse pointer shape.
 * Display Property::    Enabling special display features.
 * Images::              Displaying images in Emacs buffers.
+* Buttons::             Adding clickable buttons to Emacs buffers.
 * 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.
+* 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
@@ -53,6 +59,17 @@ Even more powerful is @code{redraw-display}:
 This function clears and redisplays all visible frames.
 @end deffn
 
+  This function forces certain windows to be redisplayed
+but does not clear them.
+
+@defun force-window-update object
+This function forces redisplay of some or all windows.  If
+@var{object} is a window, it forces redisplay of that window.  If
+@var{object} is a buffer or buffer name, it forces redisplay of all
+windows displaying that buffer.  If @var{object} is @code{nil}, it
+forces redisplay of all windows.
+@end defun
+
   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
@@ -433,7 +450,7 @@ Normally you should not change the value of this variable.
 @end defvar
 
 @defvar warning-prefix-function
-If non-@code{nil}, te value is a function to generate prefix text for
+If non-@code{nil}, the value is a function to generate prefix text for
 warnings.  Programs can bind the variable to a suitable function.
 @code{display-warning} calls this function with the warnings buffer
 current, and the function can insert text in it.  That text becomes
@@ -442,7 +459,7 @@ the beginning of the warning message.
 The function is called with two arguments, the severity level and its
 entry in @code{warning-levels}.  It should return a list to use as the
 entry (this value need not be an actual member of
-@code{warning-levels}).  By constructing this value, the function to
+@code{warning-levels}).  By constructing this value, the function can
 change the severity of the warning, or specify different handling for
 a given severity level.
 
@@ -454,7 +471,7 @@ to call.
 Programs can bind this variable to @code{t} to say that the next
 warning should begin a series.  When several warnings form a series,
 that means to leave point on the first warning of the series, rather
-than keep move it for each warning so that it appears on the last one.
+than keep moving it for each warning so that it appears on the last one.
 The series ends when the local binding is unbound and
 @code{warning-series} becomes @code{nil} again.
 
@@ -517,6 +534,105 @@ warnings buffer.  Each element of the list should be a list of
 symbols.  If it matches the first few elements in a warning type, then
 that warning is not logged.
 @end defopt
+
+@node Progress
+@section Reporting Operation Progress
+@cindex progress reporting
+
+When an operation can take a while to finish, you should inform the
+user about the progress it makes.  This way the user can estimate
+remaining time and clearly see that Emacs is busy working, not hung.
+
+Functions listed in this section provide simple and efficient way of
+reporting operation progress.  Here is a working example that does
+nothing useful:
+
+@example
+(let ((progress-reporter
+       (make-progress-reporter "Collecting some mana for Emacs..."
+                               0  500)))
+  (dotimes (k 500)
+    (sit-for 0.01)
+    (progress-reporter-update progress-reporter k))
+  (progress-reporter-done progress-reporter))
+@end example
+
+@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
+This function creates a progress reporter---the object you will use as
+an argument for all other functions listed here.  The idea is to
+precompute as much data as possible to make progress reporting very
+fast.
+
+The @var{message} will be displayed in the echo area, followed by
+progress percentage.  @var{message} is treated as a simple string.  If
+you need it to depend on a filename, for instance, use @code{format}
+before calling this function.
+
+@var{min-value} and @var{max-value} arguments stand for starting and
+final states of your operation.  For instance, if you scan a buffer,
+they should be the results of @code{point-min} and @code{point-max}
+correspondingly.  It is required that @var{max-value} is greater than
+@var{min-value}.  If you create progress reporter when some part of
+the operation has already been completed, then specify
+@var{current-value} argument.  But normally you should omit it or set
+it to @code{nil}---it will default to @var{min-value} then.
+
+Remaining arguments control the rate of echo area updates.  Progress
+reporter will wait for at least @var{min-change} more percents of the
+operation to be completed before printing next message.
+@var{min-time} specifies the minimum time in seconds to pass between
+successive prints.  It can be fractional.  Depending on Emacs and
+system capabilities, progress reporter may or may not respect this
+last argument or do it with varying precision.  Default value for
+@var{min-change} is 1 (one percent), for @var{min-time}---0.2
+(seconds.)
+
+This function calls @code{progress-reporter-update}, so the first
+message is printed immediately.
+@end defun
+
+@defun progress-reporter-update reporter value
+This function does the main work of reporting progress of your
+operation.  It print the message of @var{reporter} followed by
+progress percentage determined by @var{value}.  If percentage is zero,
+then it is not printed at all.
+
+@var{reporter} must be the result of a call to
+@code{make-progress-reporter}.  @var{value} specifies the current
+state of your operation and must be between @var{min-value} and
+@var{max-value} (inclusive) as passed to
+@code{make-progress-reporter}.  For instance, if you scan a buffer,
+then @var{value} should be the result of a call to @code{point}.
+
+This function respects @var{min-change} and @var{min-time} as passed
+to @code{make-progress-reporter} and so does not output new messages
+on every invocation.  It is thus very fast and normally you should not
+try to reduce the number of calls to it: resulting overhead will most
+likely negate your effort.
+@end defun
+
+@defun progress-reporter-force-update reporter value &optional new-message
+This function is similar to @code{progress-reporter-update} except
+that it prints a message in the echo area unconditionally.
+
+The first two arguments have the same meaning as for
+@code{progress-reporter-update}.  Optional @var{new-message} allows
+you to change the message of the @var{reporter}.  Since this functions
+always updates the echo area, such a change will be immediately
+presented to the user.
+@end defun
+
+@defun progress-reporter-done reporter
+This function should be called when the operation is finished.  It
+prints the message of @var{reporter} followed by word ``done'' in the
+echo area.
+
+You should always call this function and not hope for
+@code{progress-reporter-update} to print ``100%.''  Firstly, it may
+never print it, there are many good reasons for this not to happen.
+Secondly, ``done'' is more explicit.
+@end defun
+
 @node Invisible Text
 @section Invisible Text
 
@@ -549,7 +665,8 @@ 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.
+actually make a character invisible.  Setting this variable makes it
+buffer-local.
 
 @table @asis
 @item @code{t}
@@ -587,7 +704,7 @@ is @code{t} remains invisible.
 @end defun
 
 @defun remove-from-invisibility-spec element
-This removeds the element @var{element} from
+This removes the element @var{element} from
 @code{buffer-invisibility-spec}.  This does nothing if @var{element}
 is not in the list.
 @end defun
@@ -613,12 +730,22 @@ major mode should use the mode's own name as an element of
 @end example
 
 @vindex line-move-ignore-invisible
-  Ordinarily, commands that operate on text or move point do not care
+  Ordinarily, functions that operate on text or move point do not care
 whether the text is invisible.  The user-level line motion commands
 explicitly ignore invisible newlines if
 @code{line-move-ignore-invisible} is non-@code{nil}, but only because
 they are explicitly programmed to do so.
 
+  However, if a command ends with point inside or immediately after
+invisible text, the main editing loop moves point further forward or
+further backward (in the same direction that the command already moved
+it) until that condition is no longer true.  Thus, if the command
+moved point back into an invisible range, Emacs moves point back to
+the beginning of that range, following the previous visible character.
+If the command moved point forward into an invisible range, Emacs
+moves point forward past the first visible character that follows the
+invisible text.
+
   Incremental search can make invisible overlays visible temporarily
 and/or permanently when a match includes invisible text.  To enable
 this, the overlay should have a non-@code{nil}
@@ -805,8 +932,9 @@ If the @var{forms} do not change the major mode in the output buffer,
 so that it is still Help mode at the end of their execution, then
 @code{with-output-to-temp-buffer} makes this buffer read-only at the
 end, and also scans it for function and variable names to make them
-into clickable cross-references.  @xref{Documentation Tips, , Tips for
-Documentation Strings}.
+into clickable cross-references.  @xref{Docstring hyperlinks, , Tips
+for Documentation Strings}, in particular the item on hyperlinks in
+documentation strings, for more details.
 
 The string @var{buffer-name} specifies the temporary buffer, which
 need not already exist.  The argument must be a string, not a buffer.
@@ -942,8 +1070,14 @@ object that 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.
 
+An overlays uses markers to record its beginning and end; thus,
+editing the text of the buffer adjusts the beginning and end of each
+overlay so that it stays with the text.  When you create the overlay,
+you can specify whether text inserted at the beginning should be
+inside the overlay or outside, and likewise for the end of the overlay.
+
 @menu
-* Overlay Properties::	How to read and set properties.
+* Overlay Properties::  How to read and set properties.
 			What properties do to the screen display.
 * Managing Overlays::   Creating and moving overlays.
 * Finding Overlays::    Searching for overlays.
@@ -977,6 +1111,10 @@ is @code{nil}.
 @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
+
+@defun overlay-properties overlay
+This returns a copy of the property list of @var{overlay}.
 @end defun
 
   See also the function @code{get-char-property} which checks both
@@ -1130,9 +1268,9 @@ sense---only on the screen.
 @item evaporate
 @kindex evaporate @r{(overlay property)}
 If this property is non-@code{nil}, the overlay is deleted automatically
-if it becomes empty (i.e., if its length becomes zero).  However,
-if the overlay is @emph{already} empty, @code{evaporate} does not
-delete it.
+if it becomes empty (i.e., if its length becomes zero).  If you give
+an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
+it immediately.
 
 @item local-map
 @cindex keymap of character (and overlays)
@@ -1154,6 +1292,10 @@ property) rather than replacing it.
   This section describes the functions to create, delete and move
 overlays, and to examine their contents.
 
+@defun overlayp object
+This function returns @code{t} if @var{object} is an overlay.
+@end defun
+
 @defun make-overlay start end &optional buffer front-advance rear-advance
 This function creates and returns an overlay that belongs to
 @var{buffer} and ranges from @var{start} to @var{end}.  Both @var{start}
@@ -1163,7 +1305,11 @@ current buffer.
 
 The arguments @var{front-advance} and @var{rear-advance} specify the
 insertion type for the start of the overlay and for the end of the
-overlay, respectively.  @xref{Marker Insertion Types}.
+overlay, respectively.  @xref{Marker Insertion Types}.  If
+@var{front-advance} is non-@code{nil}, text inserted at the beginning
+of the overlay is excluded from the overlay.  If @var{read-advance} is
+non-@code{nil}, text inserted at the beginning of the overlay is
+included in the overlay.
 @end defun
 
 @defun overlay-start overlay
@@ -1365,6 +1511,102 @@ the beginning of the result if one multi-column character in
 @end example
 @end defun
 
+@node Line Height
+@section Line Height
+@cindex line height
+
+  The total height of each display line consists of the height of the
+contents of the line, and additional vertical line spacing below the
+display row.
+
+  The height of the line contents is normally determined from the
+maximum height of any character or image on that display line,
+including the final newline if there is one.  (A line that is
+continued doesn't include a final newline.)  In the most common case,
+the line height equals the height of the default frame font.
+
+  There are several ways to explicitly control or change the line
+height, either by specifying an absolute height for the display line,
+or by adding additional vertical space below one or all lines.
+
+@kindex line-height @r{(text property)}
+  A newline can have a @code{line-height} text or overlay property
+that controls the total height of the display line ending in that
+newline.
+
+  If the property value is a list @code{(@var{height} @var{total})},
+then @var{height} is used as the actual property value for the
+@code{line-height}, and @var{total} specifies the total displayed
+height of the line, so the line spacing added below the line equals
+the @var{total} height minus the actual line height.  In this case,
+the other ways to specify the line spacing are ignored.
+
+  If the property value is @code{t}, the displayed height of the
+line is exactly what its contents demand; no line-spacing is added.
+This case is useful for tiling small images or image slices without
+adding blank areas between the images.
+
+  If the property value is not @code{t}, it is a height spec.  A height
+spec stands for a numeric height value; this heigh spec specifies the
+actual line height, @var{line-height}.  There are several ways to
+write a height spec; here's how each of them translates into a numeric
+height:
+
+@table @code
+@item @var{integer}
+If the height spec is a positive integer, the height value is that integer.
+@item @var{float}
+If the height spec is a float, @var{float}, the numeric height value
+is @var{float} times the frame's default line height.
+@item (@var{face} . @var{ratio})
+If the height spec is a cons of the format shown, the numeric height
+is @var{ratio} times the height of face @var{face}.  @var{ratio} can
+be any type of number, or @code{nil} which means a ratio of 1.
+If @var{face} is @code{t}, it refers to the current face.
+@item (@code{nil} . @var{ratio})
+If the height spec is a cons of the format shown, the numeric height
+is @var{ratio} times the height of the contents of the line.
+@end table
+
+  Thus, any valid non-@code{t} property value specifies a height in pixels,
+@var{line-height}, one way or another.  If the line contents' height
+is less than @var{line-height}, Emacs adds extra vertical space above
+the line to achieve the total height @var{line-height}.  Otherwise,
+@var{line-height} has no effect.
+
+  If you don't specify the @code{line-height} propery, the line's
+height consists of the contents' height plus the line spacing.
+There are several ways to specify the line spacing for different
+parts of Emacs text.
+
+@vindex default-line-spacing
+  You can specify the line spacing for all lines in a frame with the
+@code{line-spacing} frame parameter, @xref{Window Frame Parameters}.
+However, if the variable @code{default-line-spacing} is
+non-@code{nil}, it overrides the frame's @code{line-spacing}
+parameter.  An integer value specifies the number of pixels put below
+lines on window systems.  A floating point number specifies the
+spacing relative to the frame's default line height.
+
+@vindex line-spacing
+  You can specify the line spacing for all lines in a buffer via the
+buffer-local @code{line-spacing} variable.  An integer value specifies
+the number of pixels put below lines on window systems.  A floating
+point number specifies the spacing relative to the default frame line
+height.  This overrides line spacings specified for the frame.
+
+@kindex line-spacing @r{(text property)}
+  Finally, a newline can have a @code{line-spacing} text or overlay
+property that controls the height of the display line ending with that
+newline.  The property value overrides the default frame line spacing
+and the buffer local @code{line-spacing} variable.
+
+  One way or another, these mechanisms specify a Lisp value for the
+spacing of each line.  The value is a height spec, and it translates
+into a Lisp value as described above.  However, in this case the
+numeric height value specifies the line spacing, rather than the line
+height.
+
 @node Faces
 @section Faces
 @cindex faces
@@ -1393,10 +1635,10 @@ face name a special meaning in one frame if you wish.
 * Standard Faces::      The faces Emacs normally comes with.
 * Defining Faces::      How to define a face with @code{defface}.
 * Face Attributes::     What is in a face?
-* Attribute Functions:: Functions to examine and set face attributes.
-* Merging Faces::	How Emacs combines the faces specified for a character.
+* Attribute Functions::  Functions to examine and set face attributes.
+* Displaying Faces::     How Emacs combines the faces specified for a character.
 * Font Selection::      Finding the best available font for a face.
-* Face Functions::	How to define and examine faces.
+* Face Functions::      How to define and examine faces.
 * Auto Faces::          Hook for automatic face assignment.
 * Font Lookup::         Looking up the names of available fonts
                           and information about them.
@@ -1443,7 +1685,7 @@ font.  (This works only on certain systems.)
 
 @item fringe
 @kindex fringe @r{(face name)}
-This face controls the colors of window fringes, the thin areas on
+This face controls the default colors of window fringes, the thin areas on
 either side that are used to display continuation and truncation glyphs.
 
 @item minibuffer-prompt
@@ -1581,6 +1823,10 @@ What kinds of colors the frame supports---either @code{color},
 @item background
 The kind of background---either @code{light} or @code{dark}.
 
+@item min-colors
+An integer that represents the minimum number of colors the frame should
+support, it is compared with the result of @code{display-color-cells}.
+
 @item supports
 Whether or not the frame can display the face attributes given in
 @var{value}@dots{} (@pxref{Face Attributes}).  See the documentation
@@ -1602,17 +1848,20 @@ frame must match one of the @var{value}s specified for it in
 
 @example
 @group
-(defface region
-  `((((type tty) (class color))
-     (:background "blue" :foreground "white"))
+  '((((class color) (min-colors 88) (background dark))
+     :background "blue3")
 @end group
+    (((class color) (min-colors 88) (background light))
+     :background "lightgoldenrod2")
+    (((class color) (min-colors 16) (background dark))
+     :background "blue3")
+    (((class color) (min-colors 16) (background light))
+     :background "lightgoldenrod2")
+    (((class color) (min-colors 8))
+     :background "blue" :foreground "white")
     (((type tty) (class mono))
-     (:inverse-video t))
-    (((class color) (background dark))
-     (:background "blue"))
-    (((class color) (background light))
-     (:background "lightblue"))
-    (t (:background "gray")))
+     :inverse-video t)
+    (t :background "gray"))
 @group
   "Basic face for highlighting the region."
   :group 'basic-faces)
@@ -1641,7 +1890,7 @@ as if they had a light background.
 attributes}.  This table lists all the face attributes, and what they
 mean.  Note that in general, more than one face can be specified for a
 given piece of text; when that happens, the attributes of all the faces
-are merged to specify how to display the text.  @xref{Merging Faces}.
+are merged to specify how to display the text.  @xref{Displaying Faces}.
 
   In Emacs 21, any attribute in a face can have the value
 @code{unspecified}.  This means the face doesn't specify that attribute.
@@ -1692,10 +1941,14 @@ On a text-only terminal, slanted text is displayed as half-bright, if
 the terminal supports the feature.
 
 @item :foreground
-Foreground color, a string.
+Foreground color, a string.  The value can be a system-defined color
+name, or a hexadecimal color specification of the form
+@samp{#@var{rr}@var{gg}@var{bb}}.  (@samp{#000000} is black,
+@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
+blue, and @samp{#ffffff} is white.)
 
 @item :background
-Background color, a string.
+Background color, a string, like the foreground color.
 
 @item :inverse-video
 Whether or not characters should be displayed in inverse video.  The
@@ -1891,7 +2144,7 @@ and examine the face attributes which existed in those versions.
 
 @tindex face-attribute-relative-p
 @defun face-attribute-relative-p attribute value
-This function returns non-@code{nil} if @var{value}, when used as a
+This function returns non-@code{nil} if @var{value}, when used as
 the value of the face attribute @var{attribute}, is relative (that is,
 if it modifies an underlying or inherited value of @var{attribute}).
 @end defun
@@ -1973,8 +2226,8 @@ value for that attribute.
 These functions return the foreground color (or background color,
 respectively) of face @var{face}, as a string.
 
-If @var{inherit} is nil, only a color directly defined by the face is
-returned.  If @var{inherit} is non-nil, any faces specified by its
+If @var{inherit} is @code{nil}, only a color directly defined by the face is
+returned.  If @var{inherit} is non-@code{nil}, any faces specified by its
 @code{:inherit} attribute are considered as well, and if @var{inherit}
 is a face or a list of faces, then they are also considered, until a
 specified color is found.  To ensure that the return value is always
@@ -2016,8 +2269,8 @@ This function returns the @code{:underline} attribute of face @var{face}.
 This function returns the @code{:inverse-video} attribute of face @var{face}.
 @end defun
 
-@node Merging Faces
-@subsection Merging Faces for Display
+@node Displaying Faces
+@subsection Displaying Faces
 
   Here are the ways to specify which faces to use for display of text:
 
@@ -2239,10 +2492,8 @@ 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
-default face if each attribute is either the same as that of the default
-face, or unspecified (meaning to inherit from the default).
+This returns non-@code{nil} if the face @var{face} displays
+differently from the default face.
 @end defun
 
 @node Auto Faces
@@ -2464,7 +2715,7 @@ This function modifies the existing fontset @var{name} to
 use the font name @var{fontname} for the character @var{character}.
 
 If @var{name} is @code{nil}, this function modifies the default
-fontset of which short name is @samp{fontset-default}.
+fontset, whose short name is @samp{fontset-default}.
 
 @var{character} may be a cons; @code{(@var{from} . @var{to})}, where
 @var{from} and @var{to} are non-generic characters.  In that case, use
@@ -2504,7 +2755,7 @@ does that, this function's value may not be accurate.
 
   The @dfn{fringes} of a window are thin vertical strips down the
 sides that are used for displaying bitmaps that indicate truncation,
-continuation, and horizontal scrolling, the overlay arrow.  The
+continuation, horizontal scrolling, and the overlay arrow.  The
 fringes normally appear between the display margins and the window
 text, but you can put them outside the display margins for a specific
 buffer by setting @code{fringes-outside-margins} buffer-locally to a
@@ -2512,7 +2763,7 @@ non-@code{nil} value.
 
 @defvar fringes-outside-margins
 If the value is non-@code{nil}, the frames appear outside
-the display margins. 
+the display margins.
 @end defvar
 
 @defvar left-fringe-width
@@ -2527,11 +2778,12 @@ fringe in pixels.
 
   The values of these variables take effect when you display the
 buffer in a window.  If you change them while the buffer is visible,
-you can call @code{set-buffer-window} to display it in a window again.
+you can call @code{set-window-buffer} to display it once again in the
+same window, to make the changes take effect.
 
 @defun set-window-fringes window left &optional right outside-margins
-This function sets the fringe widthes of window @var{window}.
-If window is @code{nil}, that stands for the selected window.
+This function sets the fringe widths of window @var{window}.
+If @var{window} is @code{nil}, the selected window is used.
 
 The argument @var{left} specifies the width in pixels of the left
 fringe, and likewise @var{right} for the right fringe.  A value of
@@ -2540,12 +2792,132 @@ fringe, and likewise @var{right} for the right fringe.  A value of
 should appear outside of the display margins.
 @end defun
 
-@defun window-fringes window
+@defun window-fringes &optional window
 This function returns information about the fringes of a window
-@var{window}.  The value has the form @code{(@var{left-width}
+@var{window}.  If @var{window} is omitted or @code{nil}, the selected
+window is used.  The value has the form @code{(@var{left-width}
 @var{right-width} @var{frames-outside-margins})}.
 @end defun
 
+@defvar overflow-newline-into-fringe
+If this is non-@code{nil}, lines exactly as wide as the window (not
+counting the final newline character) are not continued.  Instead,
+when point is at the end of the line, the cursor appears in the right
+fringe.
+@end defvar
+
+@node Fringe Bitmaps
+@section Fringe Bitmaps
+@cindex fringe bitmaps
+@cindex bitmaps, fringe
+
+  The @dfn{fringe bitmaps} are tiny icons Emacs displays in the window
+fringe (on a graphic display) to indicate truncated or continued
+lines, buffer boundaries, overlay arrow, etc.  The fringe bitmaps are
+shared by all frames and windows.  You can redefine the built-in
+fringe bitmaps, and you can define new fringe bitmaps.
+
+  The way to display a bitmap in the left or right fringes for a given
+line in a window is by specifying the @code{display} property for one
+of the characters that appears in it.  Use a display specification of
+the form @code{(left-fringe @var{bitmap} [@var{face}])} or
+@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
+Property}).  Here, @var{bitmap} is a symbol identifying the bitmap
+you want, and @var{face} (which is optional) is the name of the face
+whose colors should be used for displaying the bitmap.
+
+  These are the symbols identify the standard fringe bitmaps.
+Evaluate @code{(require 'fringe)} to define them.  Fringe bitmap
+symbols have their own name space.
+
+@table @asis
+@item Truncation and continuation line bitmaps:
+@code{left-truncation}, @code{right-truncation},
+@code{continued-line}, @code{continuation-line}.
+
+@item Buffer indication bitmaps:
+@code{up-arrow}, @code{down-arrow},
+@code{top-left-angle}, @code{top-right-angle},
+@code{bottom-left-angle}, @code{bottom-right-angle},
+@code{left-bracket}, @code{right-bracket}.
+
+@item Empty line indication bitmap:
+@code{empty-line}.
+
+@item Overlay arrow bitmap:
+@code{overlay-arrow}.
+
+@item Bitmaps for displaying the cursor in right fringe:
+@code{filled-box-cursor}, @code{hollow-box-cursor}, @code{hollow-square},
+@code{bar-cursor}, @code{hbar-cursor}.
+@end table
+
+@defun fringe-bitmaps-at-pos &optional pos window
+This function returns the fringe bitmaps of the display line
+containing position @var{pos} in window @var{window}.  The return
+value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
+is the symbol for the fringe bitmap in the left fringe (or @code{nil}
+if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
+is non-@code{nil} if there is an overlay arrow in the left fringe.
+
+The value is @code{nil} if @var{pos} is not visible in @var{window}.
+If @var{window} is @code{nil}, that stands for the selected window.
+If @var{pos} is @code{nil}, that stands for the value of point in
+@var{window}.
+@end defun
+
+@node Customizing Bitmaps
+@section Customizing Fringe Bitmaps
+
+@defun define-fringe-bitmap bitmap bits &optional height width align
+This function defines the symbol @var{bitmap} as a new fringe bitmap,
+or replaces an existing bitmap with that name.
+
+The argument @var{bits} specifies the image to use.  It should be
+either a string or a vector of integers, where each element (an
+integer) corresponds to one row of the bitmap.  Each bit of an integer
+corresponds to one pixel of the bitmap, where the low bit corresponds
+to the rightmost pixel of the bitmap.
+
+The height is normally the length of @var{bits}.  However, you
+can specify a different height with non-@code{nil} @var{height}.  The width
+is normally 8, but you can specify a different width with non-@code{nil}
+@var{width}.  The width must be an integer between 1 and 16.
+
+The argument @var{align} specifies the positioning of the bitmap
+relative to the range of rows where it is used; the default is to
+center the bitmap.  The allowed values are @code{top}, @code{center},
+or @code{bottom}.
+
+The @var{align} argument may also be a list @code{(@var{align}
+@var{periodic})} where @var{align} is interpreted as described above.
+If @var{periodic} is non-@code{nil}, it specifies that the rows in
+@code{bits} should be repeated enough times to reach the specified
+height.
+
+The return value on success is an integer identifying the new bitmap.
+You should save that integer in a variable so it can be used to select
+this bitmap.
+
+This function signals an error if there are no more free bitmap slots.
+@end defun
+
+@defun destroy-fringe-bitmap bitmap
+This function destroy the fringe bitmap identified by @var{bitmap}.
+If @var{bitmap} identifies a standard fringe bitmap, it actually
+restores the standard definition of that bitmap, instead of
+eliminating it entirely.
+@end defun
+
+@defun set-fringe-bitmap-face bitmap &optional face
+This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
+If @var{face} is @code{nil}, it selects the @code{fringe} face.  The
+bitmap's face controls the color to draw it in.
+
+The face you use here should be derived from @code{fringe}, and should
+specify only the foreground color.
+@end defun
+
 @node Scroll Bars
 @section Scroll Bars
 
@@ -2555,28 +2927,36 @@ non-@code{nil} parameter value means they do.  The frame parameter
 @code{scroll-bar-width} specifies how wide they are (@code{nil}
 meaning the default).  @xref{Window Frame Parameters}.
 
-You can also control this for individual windows.  Call the function
+@vindex vertical-scroll-bar
+  You can enable or disable scroll bars for a particular buffer,
+by setting the variable @code{vertical-scroll-bar}.  This variable
+automatically becomes buffer-local when set.  The possible values are
+@code{left}, @code{right}, @code{t}, which means to use the
+frame's default, and @code{nil} for no scroll bar.
+
+  You can also control this for individual windows.  Call the function
 @code{set-window-scroll-bars} to specify what to do for a specific window:
 
 @defun set-window-scroll-bars window width &optional vertical-type horizontal-type
-Set width and type of scroll bars of window @var{window}.  (If
-@var{window} is @code{nil}, this applies to the selected window.)
+This function sets the width and type of scroll bars for window
+@var{window}.
+
 @var{width} specifies the scroll bar width in pixels (@code{nil} means
-use whatever is specified for width for the frame).
-@var{vertical-type} specifies whether to have a vertical scroll bar
-and, if so, where.  The possible values are @code{left}, @code{right}
-and @code{nil}, just like the values of the
-@code{vertical-scroll-bars} frame parameter.
+use the width specified for the frame).  @var{vertical-type} specifies
+whether to have a vertical scroll bar and, if so, where.  The possible
+values are @code{left}, @code{right} and @code{nil}, just like the
+values of the @code{vertical-scroll-bars} frame parameter.
 
 The argument @var{horizontal-type} is meant to specify whether and
 where to have horizontal scroll bars, but since they are not
-implemented, it has no effect.
+implemented, it has no effect.  If @var{window} is @code{nil}, the
+selected window is used.
 @end defun
 
 @defun window-scroll-bars &optional window
 Report the width and type of scroll bars specified for @var{window}.
-If @var{window} is omitted or @code{nil}, it defaults to the currently
-selected window.  The value is a list of the form @code{(@var{width}
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a list of the form @code{(@var{width}
 @var{cols} @var{vertical-type} @var{horizontal-type})}.  The value
 @var{width} is the value that was specified for the width (which may
 be @code{nil}); @var{cols} is the number of columns that the scroll
@@ -2594,6 +2974,39 @@ in a buffer that is already visible in a window, you can make the
 window take note of the new values by calling @code{set-window-buffer}
 specifying the same buffer that is already displayed.
 
+@defvar scroll-bar-mode
+This variable, always local in all buffers, controls whether and where
+to put scroll bars in windows displaying the buffer.  The possible values
+are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
+the left, and @code{right} to put a scroll bar on the right.
+@end defvar
+
+@defvar scroll-bar-width
+This variable, always local in all buffers, specifies the width of the
+buffer's scroll bars, measured in pixels.  A value of @code{nil} means
+to use the value specified by the frame.
+@end defvar
+
+@node Pointer Shape
+@section Pointer Shape
+
+  Normally, the mouse pointer has the @code{text} shape over text and
+the @code{arrow} shape over window areas which do not correspond to
+any buffer text.  You can specify the mouse pointer shape over text or
+images via the @code{pointer} text property, and for images with the
+@code{:pointer} and @code{:map} image properties.
+
+  The available pointer shapes are: @code{text} (or @code{nil}),
+@code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},
+@code{modeline}, and @code{hourglass}.
+
+@defvar void-text-area-pointer
+@tindex void-text-area-pointer
+This variable specifies the mouse pointer shape in void text areas,
+i.e. the areas after the end of a line or below the last line in the
+buffer.  The default is to use the @code{arrow} (non-text) pointer.
+@end defvar
+
 @node Display Property
 @section The @code{display} Property
 @cindex display specification
@@ -2608,12 +3021,13 @@ this section describes several kinds of display specifications and what
 they mean.
 
 @menu
-* Specified Space::     Displaying one space with a specified width.
-* Other Display Specs:: Displaying an image; magnifying text; moving it
+* Specified Space::      Displaying one space with a specified width.
+* Pixel Specification::  Specifying space width or height in pixels.
+* Other Display Specs::  Displaying an image; magnifying text; moving it
                           up or down on the page; adjusting the width
                           of spaces within text.
 * Display Margins::     Displaying text or images to the side of the main text.
-* Conditional Display:: Making any of the above features conditional
+* Conditional Display::  Making any of the above features conditional
                           depending on some Lisp expression.
 @end menu
 
@@ -2633,9 +3047,10 @@ can use in @var{props} to specify the weight of the space:
 
 @table @code
 @item :width @var{width}
-Specifies that the space width should be @var{width} times the normal
-character width.  @var{width} can be an integer or floating point
-number.
+If @var{width} is an integer or floating point number, it specifies
+that the space width should be @var{width} times the normal character
+width.  @var{width} can also be a @dfn{pixel width} specification
+(@pxref{Pixel Specification}).
 
 @item :relative-width @var{factor}
 Specifies that the width of the stretch should be computed from the
@@ -2644,41 +3059,131 @@ same @code{display} property.  The space width is the width of that
 character, multiplied by @var{factor}.
 
 @item :align-to @var{hpos}
-Specifies that the space should be wide enough to reach @var{hpos}.  The
-value @var{hpos} is measured in units of the normal character width.  It
-may be an integer or a floating point number.
+Specifies that the space should be wide enough to reach @var{hpos}.
+If @var{hpos} is a number, it is measured in units of the normal
+character width.  @var{hpos} can also be a @dfn{pixel width}
+specification (@pxref{Pixel Specification}).
 @end table
 
   You should use one and only one of the above properties.  You can
-also specify the height of the space, with other properties:
+also specify the height of the space, with these properties:
 
 @table @code
 @item :height @var{height}
-Specifies the height of the space, as @var{height},
-measured in terms of the normal line height.
+Specifies the height of the space.
+If @var{height} is an integer or floating point number, it specifies
+that the space height should be @var{height} times the normal character
+height.  The @var{height} may also be a @dfn{pixel height} specification
+(@pxref{Pixel Specification}).
 
 @item :relative-height @var{factor}
 Specifies the height of the space, multiplying the ordinary height
 of the text having this display specification by @var{factor}.
 
 @item :ascent @var{ascent}
-Specifies that @var{ascent} percent of the height of the space should be
-considered as the ascent of the space---that is, the part above the
-baseline.  The value of @var{ascent} must be a non-negative number no
-greater than 100.
+If the value of @var{ascent} is a non-negative number no greater than
+100, it specifies that @var{ascent} percent of the height of the space
+should be considered as the ascent of the space---that is, the part
+above the baseline.  The ascent may also be specified in pixel units
+with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
+
 @end table
 
   Don't use both @code{:height} and @code{:relative-height} together.
 
+  The @code{:height} and @code{:align-to} properties are supported on
+non-graphic terminals, but the other space properties in this section
+are not.
+
+@node Pixel Specification
+@subsection Pixel Specification for Spaces
+@cindex spaces, pixel specification
+
+  The value of the @code{:width}, @code{:align-to}, @code{:height},
+and @code{:ascent} properties can be a special kind of expression that
+is evaluated during redisplay.  The result of the evaluation is used
+as an absolute number of pixels.
+
+  The following expressions are supported:
+
+@example
+@group
+  @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
+  @var{num}  ::= @var{integer} | @var{float} | @var{symbol}
+  @var{unit} ::= in | mm | cm | width | height
+  @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
+        |  scroll-bar | text
+  @var{pos}  ::= left | center | right
+  @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
+  @var{op}   ::= + | -
+@end group
+@end example
+
+  The form @var{num} specifies a fraction of the default frame font
+height or width.  The form @code{(@var{num})} specifies an absolute
+number of pixels.  If @var{num} is a symbol, @var{symbol}, its
+buffer-local variable binding is used.
+
+  The @code{in}, @code{mm}, and @code{cm} units specify the number of
+pixels per inch, millimeter, and centimeter, respectively.  The
+@code{width} and @code{height} units correspond to the default width
+and height of the current face.  An image specification @code{image}
+corresponds to the width or height of the image.
+
+  The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
+@code{right-margin}, @code{scroll-bar}, and @code{text} elements
+specify to the width of the corresponding area of the window.
+
+  The @code{left}, @code{center}, and @code{right} positions can be
+used with @code{:align-to} to specify a position relative to the left
+edge, center, or right edge of the text area.
+
+  Any of the above window elements (except @code{text}) can also be
+used with @code{:align-to} to specify that the position is relative to
+the left edge of the given area.  Once the base offset for a relative
+position has been set (by the first occurrence of one of these
+symbols), further occurrences of these symbols are interpreted as the
+width of the specified area.  For example, to align to the center of
+the left-margin, use
+
+@example
+:align-to (+ left-margin (0.5 . left-margin))
+@end example
+
+  If no specific base offset is set for alignment, it is always relative
+to the left edge of the text area.  For example, @samp{:align-to 0} in a
+header-line aligns with the first text column in the text area.
+
+  A value of the form @code{(@var{num} . @var{expr})} stands
+multiplying the values of @var{num} and @var{expr}.  For example,
+@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
+@var{image})} specifies half the width (or height) of the specified image.
+
+  The form @code{(+ @var{expr} ...)} adds up the value of the
+expressions.  The form @code{(- @var{expr} ...)} negates or subtracts
+the value of the expressions.
+
 @node Other Display Specs
 @subsection Other Display Specifications
 
+  Here are the other sorts of display specifications that you can use
+in the @code{display} text property.
+
 @table @code
 @item (image . @var{image-props})
 This is in fact an image descriptor (@pxref{Images}).  When used as a
 display specification, it means to display the image instead of the text
 that has the display specification.
 
+@item (slice @var{x} @var{y} @var{width} @var{height})
+This specification together with @code{image} specifies a @dfn{slice}
+(a partial area) of the image to display.  The elements @var{y} and
+@var{x} specify the top left corner of the slice, within the image;
+@var{width} and @var{height} specify the width and height of the
+slice.  Integer values are numbers of pixels.  A floating point number
+in the range 0.0--1.0 stands for that fraction of the width or height
+of the entire image.
+
 @item ((margin nil) @var{string})
 @itemx @var{string}
 A display specification of this form means to display @var{string}
@@ -2826,8 +3331,13 @@ property of text that is displayed (@pxref{Display Property}).  Like the
 @code{display} property, this feature is available starting in Emacs 21.
 
   Emacs can display a number of different image formats; some of them
-are supported only if particular support libraries are installed on your
-machine.  The supported image formats include XBM, XPM (needing the
+are supported only if particular support libraries are installed on
+your machine.  In some environments, Emacs allows loading image
+libraries on demand; if so, the variable @code{image-library-alist}
+can be used to modify the set of known names for these dynamic
+libraries (though it is not possible to add new image formats).
+
+  The supported image formats include XBM, XPM (needing the
 libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
 @code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
 @code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
@@ -2839,9 +3349,46 @@ type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
 
 @defvar image-types
 This variable contains a list of those image type symbols that are
-supported in the current configuration.
+potentially supported in the current configuration.
+@emph{Potentially} here means that Emacs knows about the image types,
+not necessarily that they can be loaded (they could depend on
+unavailable dynamic libraries, for example).
+
+To know which image types are really available, use
+@code{image-type-available-p}.
+@end defvar
+
+@defvar image-library-alist
+This in an alist of image types vs external libraries needed to
+display them.
+
+Each element is a list @code{(@var{image-type} @var{library}...)},
+where the car is a supported image format from @code{image-types}, and
+the rest are strings giving alternate filenames for the corresponding
+external libraries to load.
+
+Emacs tries to load the libraries in the order they appear on the
+list; if none is loaded, the running session of Emacs won't support
+the image type.  @code{pbm} and @code{xbm} don't need to be listed;
+they're always supported.
+
+This variable is ignored if the image libraries are statically linked
+into Emacs.
 @end defvar
 
+@defun  image-type-available-p type
+@findex image-type-available-p
+
+This function returns non-@code{nil} if image type @var{type} is
+available, i.e., if images of this type can be loaded and displayed in
+Emacs.  @var{type} should be one of the types contained in
+@code{image-types}.
+
+For image types whose support libraries are statically linked, this
+function always returns @code{t}; for other image types, it returns
+@code{t} if the dynamic library could be loaded, @code{nil} otherwise.
+@end defun
+
 @menu
 * Image Descriptors::   How to specify an image for use in @code{:display}.
 * XBM Images::          Special features for XBM format.
@@ -3013,6 +3560,43 @@ specifying the color to assume for the background of the image.
 If @var{mask} is @code{nil}, remove a mask from the image, if it has
 one.  Images in some formats include a mask which can be removed by
 specifying @code{:mask nil}.
+
+@item :pointer @var{shape}
+This specifies the pointer shape when the mouse pointer is over this
+image.  @xref{Pointer Shape}, for available pointer shapes.
+
+@item :map @var{map}
+This associates an image map of @dfn{hot spots} with this image.
+
+An image map is an alist where each element has the format
+@code{(@var{area} @var{id} @var{plist})}.  An @var{area} is specified
+as either a rectangle, a circle, or a polygon.
+
+A rectangle is a cons
+@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
+which specifies the pixel coordinates of the upper left and bottom right
+corners of the rectangle area.
+
+A circle is a cons
+@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
+which specifies the center and the radius of the circle; @var{r} may
+be a float or integer.
+
+A polygon is a cons
+@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
+where each pair in the vector describes one corner in the polygon.
+
+When the mouse pointer is above a hot-spot area of an image, the
+@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
+property it defines a tool-tip for the hot-spot, and if it contains
+a @code{pointer} property, it defines the shape of the mouse cursor when
+it is over the hot-spot.
+@xref{Pointer Shape}, for available pointer shapes.
+
+When you click the mouse when the mouse pointer is over a hot-spot, an
+event is composed by combining the @var{id} of the hot-spot with the
+mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
+@var{id} is @code{area4}.
 @end table
 
 @defun image-mask-p spec &optional frame
@@ -3105,7 +3689,7 @@ specifies the actual color to use for displaying that name.
   For GIF images, specify image type @code{gif}.  Because of the patents
 in the US covering the LZW algorithm, the continued use of GIF format is
 a problem for the whole Internet; to end this problem, it is a good idea
-for everyone, even outside the US, to stop using GIFS right away
+for everyone, even outside the US, to stop using GIFs right away
 (@uref{http://www.burnallgifs.org/}).  But if you still want to use
 them, Emacs can display them.
 
@@ -3113,8 +3697,8 @@ them, Emacs can display them.
 @item :index @var{index}
 You can use @code{:index} to specify one image from a GIF file that
 contains more than one image.  This property specifies use of image
-number @var{index} from the file.  An error is signaled if the GIF file
-doesn't contain an image with index @var{index}.
+number @var{index} from the file.  If the GIF file doesn't contain an
+image with index @var{index}, the image displays as a hollow box.
 @end table
 
 @ignore
@@ -3280,7 +3864,7 @@ The image is looked for first on @code{load-path} and then in
 property yourself, but it is easier to use the functions in this
 section.
 
-@defun insert-image image &optional string area
+@defun insert-image image &optional string area slice
 This function inserts @var{image} in the current buffer at point.  The
 value @var{image} should be an image descriptor; it could be a value
 returned by @code{create-image}, or the value of a symbol defined with
@@ -3293,11 +3877,26 @@ If it is @code{left-margin}, the image appears in the left margin;
 @code{nil} or omitted, the image is displayed at point within the
 buffer's text.
 
+The argument @var{slice} specifies a slice of the image to insert.  If
+@var{slice} is @code{nil} or omitted the whole image is inserted.
+Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
+@var{height})} which specifies the @var{x} and @var{y} positions and
+@var{width} and @var{height} of the image area to insert.  Integer
+values are in units of pixels.  A floating point number in the range
+0.0--1.0 stands for that fraction of the width or height of the entire
+image.
+
 Internally, this function inserts @var{string} in the buffer, and gives
 it a @code{display} property which specifies @var{image}.  @xref{Display
 Property}.
 @end defun
 
+@defun insert-sliced-image image &optional string area rows cols
+This function inserts @var{image} in the current buffer at point, like
+@code{insert-image}, but splits the image into @var{rows}x@var{cols}
+equally sized slices.
+@end defun
+
 @defun put-image image pos &optional string area
 This function puts image @var{image} in front of @var{pos} in the
 current buffer.  The argument @var{pos} should be an integer or a
@@ -3370,6 +3969,354 @@ only the cache for that frame is cleared.  Otherwise all frames' caches
 are cleared.
 @end defun
 
+@node Buttons
+@section Buttons
+@cindex buttons
+@cindex buttons in buffers
+@cindex clickable buttons in buffers
+
+  The @emph{button} package defines functions for inserting and
+manipulating clickable (with the mouse, or via keyboard commands)
+buttons in Emacs buffers, such as might be used for help hyper-links,
+etc.  Emacs uses buttons for the hyper-links in help text and the like.
+
+A button is essentially a set of properties attached (via text
+properties or overlays) to a region of text in an Emacs buffer, which
+are called its button properties.  @xref{Button Properties}.
+
+One of the these properties (@code{action}) is a function, which will
+be called when the user invokes it using the keyboard or the mouse.
+The invoked function may then examine the button and use its other
+properties as desired.
+
+In some ways the Emacs button package duplicates functionality offered
+by the widget package (@pxref{Top, , Introduction, widget, The Emacs
+Widget Library}), but the button package has the advantage that it is
+much faster, much smaller, and much simpler to use (for elisp
+programmers---for users, the result is about the same).  The extra
+speed and space savings are useful mainly if you need to create many
+buttons in a buffer (for instance an @code{*Apropos*} buffer uses
+buttons to make entries clickable, and may contain many thousands of
+entries).
+
+@menu
+* Button Properties::      Button properties with special meanings.
+* Button Types::           Defining common properties for classes of buttons.
+* Making Buttons::         Adding buttons to Emacs buffers.
+* Manipulating Buttons::   Getting and setting properties of buttons.
+* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
+* Manipulating Button Types::
+@end menu
+
+@node Button Properties
+@subsection Button Properties
+@cindex button properties
+
+  Buttons have an associated list of properties defining their
+appearance and behavior, and other arbitrary properties may be used
+for application specific purposes.
+
+Some properties that have special meaning to the button package
+include:
+
+@table @code
+
+@item action
+@kindex action @r{(button property)}
+The function to call when the user invokes the button, which is passed
+the single argument @var{button}.  By default this is @code{ignore},
+which does nothing.
+
+@item mouse-action
+@kindex mouse-action @r{(button property)}
+This is similar to @code{action}, and when present, will be used
+instead of @code{action} for button invocations resulting from
+mouse-clicks (instead of the user hitting @key{RET}).  If not
+present, mouse-clicks use @code{action} instead.
+
+@item face
+@kindex face @r{(button property)}
+This is an Emacs face controlling how buttons of this type are
+displayed; by default this is the @code{button} face.
+
+@item mouse-face
+@kindex mouse-face @r{(button property)}
+This is an additional face which controls appearance during
+mouse-overs (merged with the usual button face); by default this is
+the usual Emacs @code{highlight} face.
+
+@item keymap
+@kindex keymap @r{(button property)}
+The button's keymap, defining bindings active within the button
+region.  By default this is the usual button region keymap, stored
+in the variable @code{button-map}, which defines @key{RET},
+@key{mouse-1} (if @var{mouse-1-click-follows-link} is set),
+and @key{mouse-2} to invoke the button.
+
+@item type
+@kindex type @r{(button property)}
+The button-type of the button.  When creating a button, this is
+usually specified using the @code{:type} keyword argument.
+@xref{Button Types}.
+
+@item help-echo
+@kindex help-index @r{(button property)}
+A string displayed by the Emacs tool-tip help system; by default,
+@code{"mouse-2, RET: Push this button"}.
+
+@item follow-link
+@kindex follow-link @r{(button property)}
+The follow-link property, defining how a @key{mouse-1} click behaves
+on this button, @xref{Enabling Mouse-1 to Follow Links}.
+@item button
+@kindex button @r{(button property)}
+All buttons have a non-@code{nil} @code{button} property, which may be useful
+in finding regions of text that comprise buttons (which is what the
+standard button functions do).
+@end table
+
+There are other properties defined for the regions of text in a
+button, but these are not generally interesting for typical uses.
+
+@node Button Types
+@subsection Button Types
+@cindex button types
+
+  Every button has a button @emph{type}, which defines default values
+for the button's properties.  Button types are arranged in a
+hierarchy, with specialized types inheriting from more general types,
+so that it's easy to define special-purpose types of buttons for
+specific tasks.
+
+@defun define-button-type name &rest properties
+@tindex define-button-type
+Define a `button type' called @var{name}.  The remaining arguments
+form a sequence of @var{property value} pairs, specifying default
+property values for buttons with this type (a button's type may be set
+by giving it a @code{type} property when creating the button, using
+the @code{:type} keyword argument).
+
+In addition, the keyword argument @code{:supertype} may be used to
+specify a button-type from which @var{name} inherits its default
+property values.  Note that this inheritance happens only when
+@var{name} is defined; subsequent changes to a supertype are not
+reflected in its subtypes.
+@end defun
+
+Using @code{define-button-type} to define default properties for
+buttons is not necessary---buttons without any specified type use the
+built-in button-type @code{button}---but it is is encouraged, since
+doing so usually makes the resulting code clearer and more efficient.
+
+@node Making Buttons
+@subsection Making Buttons
+@cindex making buttons
+
+  Buttons are associated with a region of text, using an overlay or
+text-properties to hold button-specific information, all of which are
+initialized from the button's type (which defaults to the built-in
+button type @code{button}).  Like all Emacs text, the appearance of
+the button is governed by the @code{face} property; by default (via
+the @code{face} property inherited from the @code{button} button-type)
+this is a simple underline, like a typical web-page link.
+
+For convenience, there are two sorts of button-creation functions,
+those that add button properties to an existing region of a buffer,
+called @code{make-...button}, and those also insert the button text,
+called @code{insert-...button}.
+
+The button-creation functions all take the @code{&rest} argument
+@var{properties}, which should be a sequence of @var{property value}
+pairs, specifying properties to add to the button; see @ref{Button
+Properties}.  In addition, the keyword argument @code{:type} may be
+used to specify a button-type from which to inherit other properties;
+see @ref{Button Types}.  Any properties not explicitly specified
+during creation will be inherited from the button's type (if the type
+defines such a property).
+
+The following functions add a button using an overlay
+(@pxref{Overlays}) to hold the button properties:
+
+@defun make-button beg end &rest properties
+@tindex make-button
+Make a button from @var{beg} to @var{end} in the current buffer.
+@end defun
+
+@defun insert-button label &rest properties
+@tindex insert-button
+Insert a button with the label @var{label}.
+@end defun
+
+The following functions are similar, but use Emacs text-properties
+(@pxref{Text Properties}) to hold the button properties, making the
+button actually part of the text instead of being a property of the
+buffer (using text-properties is usually faster than using overlays,
+so this may be preferable when creating large numbers of buttons):
+
+@defun make-text-button beg end &rest properties
+@tindex make-text-button
+Make a button from @var{beg} to @var{end} in the current buffer, using
+text-properties.
+@end defun
+
+@defun insert-text-button label &rest properties
+@tindex insert-text-button
+Insert a button with the label @var{label}, using text-properties.
+@end defun
+
+Buttons using text-properties retain no markers into the buffer are
+retained, which is important for speed in cases where there are
+extremely large numbers of buttons.
+
+@node Manipulating Buttons
+@subsection Manipulating Buttons
+@cindex manipulating buttons
+
+These are functions for getting and setting properties of buttons.
+Often these are used by a button's invocation function to determine
+what to do.
+
+Where a @var{button} parameter is specified, it means an object
+referring to a specific button, either an overlay (for overlay
+buttons), or a buffer-position or marker (for text property buttons).
+Such an object is passed as the first argument to a button's
+invocation function when it is invoked.
+
+@defun button-start button
+@tindex button-start
+Return the position at which @var{button} starts.
+@end defun
+
+@defun button-end button
+@tindex button-end
+Return the position at which @var{button} ends.
+@end defun
+
+@defun button-get button prop
+@tindex button-get
+Get the property of button @var{button} named @var{prop}.
+@end defun
+
+@defun button-put button prop val
+@tindex button-put
+Set @var{button}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-activate button &optional use-mouse-action
+@tindex button-activate
+Call @var{button}'s @code{action} property (i.e., invoke it).  If
+@var{use-mouse-action} is non-@code{nil}, try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@end defun
+
+@defun button-label button
+@tindex button-label
+Return @var{button}'s text label.
+@end defun
+
+@defun button-type button
+@tindex button-type
+Return @var{button}'s button-type.
+@end defun
+
+@defun button-has-type-p button type
+@tindex button-has-type-p
+Return @code{t} if @var{button} has button-type @var{type}, or one of
+@var{type}'s subtypes.
+@end defun
+
+@defun button-at pos
+@tindex button-at
+Return the button at position @var{pos} in the current buffer, or @code{nil}.
+@end defun
+
+@node Button Buffer Commands
+@subsection Button Buffer Commands
+@cindex button buffer commands
+
+These are commands and functions for locating and operating on
+buttons in an Emacs buffer.
+
+@code{push-button} is the command that a user uses to actually `push'
+a button, and is bound by default in the button itself to @key{RET},
+to @key{mouse-1} (if @var{mouse-1-click-follows-link} is set),
+and to @key{mouse-2} using a region-specific keymap.  Commands
+that are useful outside the buttons itself, such as
+@code{forward-button} and @code{backward-button} are additionally
+available in the keymap stored in @code{button-buffer-map}; a mode
+which uses buttons may want to use @code{button-buffer-map} as a
+parent keymap for its keymap.
+
+@deffn Command push-button &optional pos use-mouse-action
+@tindex push-button
+Perform the action specified by a button at location @var{pos}.
+@var{pos} may be either a buffer position or a mouse-event.  If
+@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
+mouse-event (@pxref{Mouse Events}), try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@var{pos} defaults to point, except when @code{push-button} is invoked
+interactively as the result of a mouse-event, in which case, the mouse
+event's position is used.  If there's no button at @var{pos}, do
+nothing and return @code{nil}, otherwise return @code{t}.
+@end deffn
+
+@deffn Command forward-button n &optional wrap display-message
+@tindex forward-button
+Move to the @var{n}th next button, or @var{n}th previous button if
+@var{n} is negative.  If @var{n} is zero, move to the start of any
+button at point.  If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end.  If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed.  Any button with a non-@code{nil} @code{skip} property
+is skipped over.  Returns the button found.
+@end deffn
+
+@deffn Command backward-button n &optional wrap display-message
+@tindex backward-button
+Move to the @var{n}th previous button, or @var{n}th next button if
+@var{n} is negative.  If @var{n} is zero, move to the start of any
+button at point.  If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end.  If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed.  Any button with a non-@code{nil} @code{skip} property
+is skipped over.  Returns the button found.
+@end deffn
+
+@defun next-button pos &optional count-current
+@tindex next-button
+Return the next button after position @var{pos} in the current buffer.
+If @var{count-current} is non-@code{nil}, count any button at
+@var{pos} in the search, instead of starting at the next button.
+@end defun
+
+@defun previous-button pos &optional count-current
+@tindex previous-button
+Return the @var{n}th button before position @var{pos} in the current
+buffer.  If @var{count-current} is non-@code{nil}, count any button at
+@var{pos} in the search, instead of starting at the next button.
+@end defun
+
+@node Manipulating Button Types
+@subsection Manipulating Button Types
+@cindex manipulating button types
+
+@defun button-type-put type prop val
+@tindex button-type-put
+Set the button-type @var{type}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-type-get type prop
+@tindex button-type-get
+Get the property of button-type @var{type} named @var{prop}.
+@end defun
+
+@defun button-type-subtype-p type supertype
+@tindex button-type-subtype-p
+Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
+@end defun
+
 @node Blinking
 @section Blinking Parentheses
 @cindex parenthesis matching
@@ -3529,6 +4476,14 @@ 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 value is in units of
+columns, and the default is 8.  Note that this feature is completely
+independent of the user-settable tab stops used by the command
+@code{tab-to-tab-stop}.  @xref{Indent Tabs}.
+@end defopt
+
 @defopt indicate-empty-lines
 @tindex indicate-empty-lines
 @cindex fringes, and empty line indication
@@ -3537,13 +4492,42 @@ fringe of each empty line at the end of the buffer, on terminals that
 support it (window systems).  @xref{Fringes}.
 @end defopt
 
-@defopt tab-width
-The value of this variable is the spacing between tab stops used for
-displaying tab characters in Emacs buffers.  The value is in units of
-columns, and the default is 8.  Note that this feature is completely
-independent of the user-settable tab stops used by the command
-@code{tab-to-tab-stop}.  @xref{Indent Tabs}.
-@end defopt
+@defvar indicate-buffer-boundaries
+This buffer-local variable controls how the buffer boundaries and
+window scrolling are indicated in the window fringes.
+
+Emacs can indicate the buffer boundaries---that is, the first and last
+line in the buffer---with angle icons when they appear on the screen.
+In addition, Emacs can display an up-arrow in the fringe to show
+that there is text above the screen, and a down-arrow to show
+there is text below the screen.
+
+There are four kinds of basic values:
+
+@table @asis
+@item @code{nil}
+Don't display the icons.
+@item @code{left}
+Display them in the left fringe.
+@item @code{right}
+Display them in the right fringe.
+@item @var{anything-else}
+Display the icon at the top of the window top in the left fringe, and other
+in the right fringe.
+@end table
+
+If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
+controls the angle icons, and @var{arrows} controls the arrows.  Both
+@var{angles} and @var{arrows} work according to the table above.
+Thus, @code{(t .  right)} places the top angle icon in the left
+fringe, the bottom angle icon in the right fringe, and both arrows in
+the right fringe.
+@end defvar
+
+@defvar default-indicate-buffer-boundaries
+The value of this variable is the default value for
+@code{indicate-buffer-boundaries} in buffers that do not override it.
+@end defvar
 
 @node Display Tables
 @section Display Tables
@@ -3564,9 +4548,9 @@ force redisplay of the mode line using a new display table, call
 @code{force-mode-line-update} (@pxref{Mode Line Format}).
 
 @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.
+* 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.
 @end menu
 
 @node Display Table Format
@@ -3603,7 +4587,7 @@ in these situations.
 @item 1
 The glyph for the end of a continued line (the default is @samp{\}).
 Newer Emacs versions, on some platforms, display curved arrows to
-indicate truncation---the display table has no effect in these
+indicate continuation---the display table has no effect in these
 situations.
 @item 2
 The glyph for indicating a character displayed as an octal character