* 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:
+* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
+* Scroll Bars:: Controlling vertical scroll bars.
* 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
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
@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
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.
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.
symbols. If it matches the first few elements in a warning type, then
that warning is not logged.
@end defopt
+
@node Invisible Text
@section Invisible Text
@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}
@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
@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}
created if necessary, and put into Help mode. Finally, the buffer is
displayed in some window, but not selected.
-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
+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.
+end, and also scans it for function and variable names to make them
+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.
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.
@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
@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
-if it ever becomes empty (i.e., if it spans no characters).
+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)
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}
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
* 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.
+* Merging 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.
@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
@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)
@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
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
font choice, but not all. Part of the choice depends on what character
it is.
- For multibyte characters, typically each font covers only one
-character set. So each character set (@pxref{Character Sets}) specifies
-a registry and encoding to use, with the character set's
-@code{x-charset-registry} property. Its value is a string containing
-the registry and the encoding, with a dash between them:
-
-@example
-(plist-get (charset-plist 'latin-iso8859-1)
- 'x-charset-registry)
- @result{} "ISO8859-1"
-@end example
-
- Unibyte text does not have character sets, so displaying a unibyte
-character takes the registry and encoding from the variable
-@code{face-default-registry}.
-
-@defvar face-default-registry
-This variable specifies which registry and encoding to use in choosing
-fonts for unibyte characters. The value is initialized at Emacs startup
-time from the font the user specified for Emacs.
-@end defvar
-
If the face specifies a fontset name, that fontset determines a
pattern for fonts of the given charset. If the face specifies a font
family, a font pattern is constructed.
@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
For the remaining character sets, those that you don't specify
explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
@samp{fontset-@var{alias}} with a value that names one character set.
-For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced
+For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
with @samp{ISO8859-1}.
In addition, when several consecutive fields are wildcards, Emacs
@end example
@noindent
-the font specification for @sc{ascii} characters would be this:
+the font specification for @acronym{ASCII} characters would be this:
@example
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.
+@defun set-fontset-font name character fontname &optional frame
+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, 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
+@var{fontname} for all characters in the range @var{from} and @var{to}
+(inclusive).
+
+@var{character} may be a charset. In that case, use
+@var{fontname} for all character in the charsets.
+
+@var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
+where @var{family} is a family name of a font (possibly including a
+foundry name at the head), @var{registry} is a registry name of a font
+(possibly including an encoding name at the tail).
+
+For instance, this changes the default fontset to use a font of which
+registry name is @samp{JISX0208.1983} for all characters belonging to
+the charset @code{japanese-jisx0208}.
+
+@example
+(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
+@end example
+
+@end defun
+
+@defun char-displayable-p char
+This function returns @code{t} if Emacs ought to be able to display
+@var{char}. More precisely, if the selected frame's fontset has a
+font to display the character set that @var{char} belongs to.
+
+Fontsets can specify a font on a per-character basis; when the fontset
+does that, this function's value may not be accurate.
+@end defun
+
@node Fringes
@section Fringes
@cindex Fringes
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
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
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
+@node Scroll Bars
+@section Scroll Bars
+
+Normally the frame parameter @code{vertical-scroll-bars} controls
+whether the windows in the frame have vertical scroll bars. A
+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
+@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}, the selected window is used.
+@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.
+
+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.
+@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}, 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
+bar actually occupies.
+
+@var{horizontal-type} is not actually meaningful.
+@end defun
+
+If you don't specify these values for a window with
+@code{set-window-scroll-bars}, the buffer-local variables
+@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
+displayed control the window's vertical scroll bars. The function
+@code{set-window-buffer} examines these variables. If you change them
+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.
+
@node Display Property
@section The @code{display} Property
@cindex display specification
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.
+* 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
@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 posible 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),
@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.
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.
@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
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} 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 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}
+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
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
+first glyph is the @acronym{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.
On MS-DOS terminals, Emacs arranges by default for the character code
127 to be mapped to the glyph code 127, which normally displays as an
-empty polygon. This glyph is used to display non-@sc{ascii} characters
+empty polygon. This glyph is used to display non-@acronym{ASCII} characters
that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
emacs, The GNU Emacs Manual}.
@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
+the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
digit characters representing the character code in octal. (A display
table can specify a glyph to use instead of @samp{\}.)
@cindex display table
You can use the @dfn{display table} feature to control how all possible
character codes display on the screen. This is useful for displaying
-European languages that have letters not in the @sc{ascii} character
+European languages that have letters not in the @acronym{ASCII} character
set.
The display table maps each character code into a sequence of
@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