[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r107671: Updates to Display chapter o
|
From: |
Chong Yidong |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r107671: Updates to Display chapter of Lisp manual. |
|
Date: |
Sun, 25 Mar 2012 15:58:59 +0800 |
|
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 107671
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2012-03-25 15:58:59 +0800
message:
Updates to Display chapter of Lisp manual.
* doc/lispref/display.texi (Fringes): Note that fringes are shown on graphical
displays only.
(Fringe Size/Pos, Fringe Bitmaps, Making Buttons): Clarifications.
(Replacing Specs): Clarify example.
(Manipulating Buttons): Note that button-at can return a marker.
(Buttons): Minor rewrite.
(Character Display): New node. Consolidate all character display
related nodes into its subsections.
(Usual Display): Character 127 is also affected by ctl-arrow.
(Display Tables): Improve example.
* lisp/button.el (button-at): Minor addition to docstring.
modified:
doc/lispref/ChangeLog
doc/lispref/display.texi
doc/lispref/elisp.texi
doc/lispref/vol1.texi
doc/lispref/vol2.texi
lisp/ChangeLog
lisp/button.el
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2012-03-22 06:21:28 +0000
+++ b/doc/lispref/ChangeLog 2012-03-25 07:58:59 +0000
@@ -1,3 +1,16 @@
+2012-03-25 Chong Yidong <address@hidden>
+
+ * display.texi (Fringes): Note that fringes are shown on graphical
+ displays only.
+ (Fringe Size/Pos, Fringe Bitmaps, Making Buttons): Clarifications.
+ (Replacing Specs): Clarify example.
+ (Manipulating Buttons): Note that button-at can return a marker.
+ (Buttons): Minor rewrite.
+ (Character Display): New node. Consolidate all character display
+ related nodes into its subsections.
+ (Usual Display): Character 127 is also affected by ctl-arrow.
+ (Display Tables): Improve example.
+
2012-03-22 Glenn Morris <address@hidden>
* strings.texi (Text Comparison): Mention string-prefix-p.
=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi 2012-03-21 07:02:13 +0000
+++ b/doc/lispref/display.texi 2012-03-25 07:58:59 +0000
@@ -30,13 +30,11 @@
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
-* Usual Display:: The usual conventions for displaying nonprinting chars.
-* Display Tables:: How to specify other conventions.
+* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
-* Glyphless Chars:: How glyphless characters are drawn.
@end menu
@node Refresh Screen
@@ -46,7 +44,6 @@
contents of a given frame (@pxref{Frames}). This is useful if the
screen is corrupted.
address@hidden Emacs 19 feature
@defun redraw-frame frame
This function clears and redisplays frame @var{frame}.
@end defun
@@ -3206,9 +3203,9 @@
@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, horizontal scrolling, and the overlay arrow.
+ On graphical displays, Emacs draws @dfn{fringes} next to each
+window: thin vertical strips down the sides which can display bitmaps
+indicating truncation, continuation, horizontal scrolling, and so on.
@menu
* Fringe Size/Pos:: Specifying where to put the window fringes.
@@ -3223,7 +3220,7 @@
@subsection Fringe Size and Position
The following buffer-local variables control the position and width
-of the window fringes.
+of fringes in windows showing that buffer.
@defvar fringes-outside-margins
The fringes normally appear between the display margins and the window
@@ -3243,12 +3240,17 @@
width from the window's frame.
@end defvar
- 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-window-buffer} to display it once again in the
-same window, to make the changes take effect. A buffer that does not
-specify values for these variables will use the default values
-specified for the frame; see @ref{Layout Parameters}.
+ Any buffer which does not specify values for these variables uses
+the values specified by the @code{left-fringe} and @code{right-fringe}
+frame parameters (@pxref{Layout Parameters}).
+
+ The above variables actually take effect via the function
address@hidden (@pxref{Buffers and Windows}), which calls
address@hidden as a subroutine. If you change one of these
+variables, the fringe display is not updated in existing windows
+showing the buffer, unless you call @code{set-window-buffer} again in
+each affected window. You can also use @code{set-window-fringes} to
+control the fringe display in individual windows.
@defun set-window-fringes window left &optional right outside-margins
This function sets the fringe widths of window @var{window}.
@@ -3274,9 +3276,9 @@
@cindex fringe indicators
@cindex indicators, fringe
- The @dfn{fringe indicators} are tiny icons Emacs displays in the
-window fringe (on a graphic display) to indicate truncated or
-continued lines, buffer boundaries, overlay arrow, etc.
+ @dfn{Fringe indicators} are tiny icons displayed in the window
+fringe to indicate truncated or continued lines, buffer boundaries,
+etc.
@defopt indicate-empty-lines
@cindex fringes, and empty line indication
@@ -3448,21 +3450,15 @@
a display specification has the form
@example
-(left-fringe @var{bitmap} address@hidden)
address@hidden example
-
address@hidden
-or
-
address@hidden
-(right-fringe @var{bitmap} address@hidden)
address@hidden example
-
address@hidden
-The symbol @var{bitmap} identifies the bitmap to display. The
-optional @var{face} names a face whose foreground color is used to
-display the bitmap; this face is automatically merged with the
address@hidden face.
+(@var{fringe} @var{bitmap} address@hidden)
address@hidden example
+
address@hidden
address@hidden is either the symbol @code{left-fringe} or
address@hidden @var{bitmap} is a symbol identifying the bitmap
+to display. The optional @var{face} names a face whose foreground
+color is used to display the bitmap; this face is automatically merged
+with the @code{fringe} face.
Here is a list of the standard fringe bitmaps defined in Emacs, and
how they are currently used in Emacs (via
@@ -3710,7 +3706,7 @@
@kindex display @r{(text property)}
The @code{display} text property (or overlay property) is used to
-insert images into text, and also control other aspects of how text
+insert images into text, and to control other aspects of how text
displays. The value of the @code{display} property should be a
display specification, or a list or vector containing several display
specifications. Display specifications in the same @code{display}
@@ -3736,8 +3732,8 @@
@node Replacing Specs
@subsection Display Specs That Replace The Text
- Some kinds of @code{display} specifications specify something to
-display instead of the text that has the property. These are called
+ Some kinds of display specifications specify something to display
+instead of the text that has the property. These are called
@dfn{replacing} display specifications. Emacs does not allow the user
to interactively move point into the middle of buffer text that is
replaced in this way.
@@ -3750,47 +3746,34 @@
For replacing display specifications, ``the text that has the
property'' means all the consecutive characters that have the same
Lisp object as their @code{display} property; these characters are
-replaced as a single unit. By contrast, characters that have similar
-but distinct Lisp objects as their @code{display} properties are
-handled separately. Here's a function that illustrates this point:
-
address@hidden
-(defun foo ()
- (goto-char (point-min))
- (dotimes (i 5)
- (let ((string (concat "A")))
- (put-text-property (point) (1+ (point)) 'display string)
- (forward-char 1)
- (put-text-property (point) (1+ (point)) 'display string)
- (forward-char 1))))
address@hidden smallexample
-
address@hidden
-It gives each of the first ten characters in the buffer string
address@hidden"A"} as the @code{display} property, but they don't all get the
-same string. The first two characters get the same string, so they
-together are replaced with one @samp{A}. The next two characters get
-a second string, so they together are replaced with one @samp{A}.
-Likewise for each following pair of characters. Thus, the ten
-characters appear as five A's. This function would have the same
-results:
-
address@hidden
-(defun foo ()
- (goto-char (point-min))
- (dotimes (i 5)
- (let ((string (concat "A")))
- (put-text-property (point) (+ 2 (point)) 'display string)
- (put-text-property (point) (1+ (point)) 'display string)
- (forward-char 2))))
address@hidden smallexample
-
address@hidden
-This illustrates that what matters is the property value for
-each character. If two consecutive characters have the same
-object as the @code{display} property value, it's irrelevant
-whether they got this property from a single call to
address@hidden or from two different calls.
+replaced as a single unit. If two characters have different Lisp
+objects as their @code{display} properties (i.e.@: objects which are
+not @code{eq}), they are handled separately.
+
+ Here is an example which illustrates this point. A string serves as
+a replacing display specification, which replaces the text that has
+the property with the specified string (@pxref{Other Display Specs}).
+Consider the following function:
+
address@hidden
+(defun foo ()
+ (dotimes (i 5)
+ (let ((string (concat "A"))
+ (start (+ i i (point-min))))
+ (put-text-property start (1+ start) 'display string)
+ (put-text-property start (+ 2 start) 'display string))))
address@hidden smallexample
+
address@hidden
+This function gives each of the first ten characters in the buffer a
address@hidden property which is a string @code{"A"}, but they don't
+all get the same string object. The first two characters get the same
+string object, so they are replaced with one @samp{A}; the fact that
+the display property was assigned in two separate calls to
address@hidden is irrelevant. Similarly, the next two
+characters get a second string (@code{concat} creates a new string
+object), so they are replaced with one @samp{A}; and so on. Thus, the
+ten characters appear as five A's.
@node Specified Space
@subsection Specified Spaces
@@ -4952,29 +4935,24 @@
@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. These
-properties are called @dfn{button properties}.
-
- One of 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).
+ The Button package defines functions for inserting and manipulating
address@hidden that can be activated with the mouse or via keyboard
+commands. These buttons are typically used for various kinds of
+hyperlinks.
+
+ A button is essentially a set of text or overlay properties,
+attached to a stretch of text in a buffer. These properties are
+called @dfn{button properties}. One of these properties, the
address@hidden property}, specifies a function which is called when the
+user invokes the button using the keyboard or the mouse. The action
+function may examine the button and use its other properties as
+desired.
+
+ In some ways, the Button package duplicates the functionality in the
+Widget package. @xref{Top, , Introduction, widget, The Emacs Widget
+Library}. The advantage of the Button package is that it is faster,
+smaller, and simpler to program. From the point of view of the user,
+the interfaces produced by the two packages are very similar.
@menu
* Button Properties:: Button properties with special meanings.
@@ -4988,10 +4966,10 @@
@subsection Button Properties
@cindex button properties
- Buttons have an associated list of properties defining their
+ Each button has an associated list of properties defining its
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:
+for application specific purposes. The following properties have
+special meaning to the Button package:
@table @code
@item action
@@ -5027,9 +5005,7 @@
@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.
address@hidden Types}.
+The button type. @xref{Button Types}.
@item help-echo
@kindex help-index @r{(button property)}
@@ -5055,7 +5031,7 @@
@subsection Button Types
@cindex button types
- Every button has a button @emph{type}, which defines default values
+ Every button has a @dfn{button 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
@@ -5120,18 +5096,17 @@
and returns it.
@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. Buttons using text properties do not create markers into the
-buffer, which is important for speed when you use extremely large
-numbers of buttons. (However, if there is an existing face text
-property at the site of the button, the button face may not be visible.)
-Both functions return the position of the start of the new button:
+ The following functions are similar, but using text properties
+(@pxref{Text Properties}) to hold the button properties. Such buttons
+do not add markers to the buffer, so editing in the buffer does not
+slow down if there is an extremely large numbers of buttons. However,
+if there is an existing face text property on the text (e.g.@: a face
+assigned by Font Lock mode), the button face may not be visible. Both
+of these functions return the starting position of the new button.
@defun make-text-button beg end &rest properties
-This makes a button from @var{beg} to @var{end} in the current buffer, using
-text properties.
+This makes a button from @var{beg} to @var{end} in the current buffer,
+using text properties.
@end defun
@defun insert-text-button label &rest properties
@@ -5190,7 +5165,9 @@
@end defun
@defun button-at pos
-Return the button at position @var{pos} in the current buffer, or @code{nil}.
+Return the button at position @var{pos} in the current buffer, or
address@hidden If the button at @var{pos} is a text property button, the
+return value is a marker pointing to @var{pos}.
@end defun
@defun button-type-put type prop val
@@ -5214,12 +5191,12 @@
@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
address@hidden 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.
+and to @key{mouse-2} using a local keymap in the button's overlay or
+text properties. 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
address@hidden; a mode which uses buttons may want to use
address@hidden as a parent keymap for its keymap.
If the button has a address@hidden @code{follow-link} property, and
@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
@@ -5662,70 +5639,111 @@
@end smallexample
@end deffn
address@hidden Character Display
address@hidden Character Display
+
address@hidden glyph
+This section describes how characters are actually displayed by Emacs.
+Typically, a character is displayed as a @dfn{glyph} (a graphical
+symbol which occupies one character position on the screen), whose
+appearance corresponds to the character itself. For example, the
+character @samp{a} (character code 97) is displayed as @samp{a}. Some
+characters, however, are displayed specially. For example, the
+formfeed character (character code 12) is usually displayed as a
+sequence of two glyphs, @samp{^L}, while the newline character
+(character code 10) starts a new screen line.
+
+ You can modify how each character is displayed by defining a
address@hidden table}, which maps each character code into a sequence of
+glyphs. @xref{Display Tables}. A related feature, called the
address@hidden table}, allows you to control how each character is
+displayed on a text terminal. @xref{Glyphs}.
+
+
address@hidden
+* Usual Display:: The usual conventions for displaying characters.
+* Display Tables:: 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.
+* Glyphless Chars:: How glyphless characters are drawn.
address@hidden menu
+
@node Usual Display
address@hidden Usual Display Conventions
-
- The usual display conventions define how to display each character
-code. You can override these conventions by setting up a display table
-(@pxref{Display Tables}). Here are the usual display conventions:
-
address@hidden Usual Display Conventions
+
+ Here are the usual conventions for display each character code (in
+the absence of a display table, which can override these
address@hidden
+conventions).
address@hidden iftex
address@hidden
+conventions; @pxref{Display Tables}).
address@hidden ifnottex
+
address@hidden printable ASCII characters
@itemize @bullet
@item
-Character codes 32 through 126 map to glyph codes 32 through 126.
-Normally this means they display as themselves, but a display table
-can change that.
-
address@hidden
-Character code 9 is a horizontal tab. It displays as whitespace
-up to a position determined by @code{tab-width}.
-
address@hidden
-Character code 10 is a newline. It is normally invisible on display,
-and has the effect of ending the preceding line and starting a new
-line.
-
address@hidden
-All other codes in the range 0 through 31 display in one of two ways
-according to the value of @code{ctl-arrow}. If it is address@hidden,
-these codes map to sequences of two glyphs, where the 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 raw bytes in the range 128 to 255 (described below).
+The @dfn{printable @acronym{ASCII} characters}, character codes 32
+through 126 (consisting of numerals, English letters, and symbols like
address@hidden) are displayed literally, i.e.@: they map onto glyph codes 32
+through 126.
+
address@hidden
+The tab character (character code 9) displays as whitespace stretching
+up to the next tab stop column. @xref{Text Display,,, emacs, The GNU
+Emacs Manual}. The variable @code{tab-width} controls the number of
+spaces per tab stop (see below).
+
address@hidden
+The newline character (character code 10) has the effect of ending the
+preceding line and starting a new line.
+
address@hidden ASCII control characters
address@hidden
+The non-printable @address@hidden control characters}---character
+codes 0 through 31, as well as the @key{DEL} character (character code
+127)---display in one of two ways according to the variable
address@hidden If this variable is address@hidden (the default),
+these characters are displayed as sequences of two glyphs, where the
+first glyph is @samp{^} (a display table can specify a glyph to use
+instead of @samp{^}); e.g.@: the @key{DEL} character is displayed as
address@hidden
+
+If @code{ctl-arrow} is @code{nil}, these characters are displayed as
+octal escapes (see below).
+
+This rule also applies to carriage return (character code 13), if that
+character appears in the buffer. But carriage returns usually do not
+appear in buffer text; they are eliminated as part of end-of-line
+conversion (@pxref{Coding System Basics}).
@cindex octal escapes
@item
-Raw bytes (@pxref{Text Representations}) with codes 128 through 255,
-and the @acronym{ASCII} control character with code 127, display as
-sequences of four glyphs, where 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{\}.) This is known as the @dfn{octal escape}
-display.
address@hidden bytes} are address@hidden characters with codes 128
+through 255 (@pxref{Text Representations}). These characters display
+as @dfn{octal escapes}: sequences of four glyphs, where 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{\}.)
@item
address@hidden character codes above 127 are displayed as
-themselves, if the terminal and the available fonts support them.
-Characters that are not supported by the terminal, or (on window
-systems) have no fonts available for them, are displayed as a question
-mark or a hex code or an empty box. @xref{Glyphless Chars}, for how
-to control display of the characters not supported by the terminal or
-fonts. Display tables can change how a character is displayed, even
-if it is supported.
+Each address@hidden character with code above 255 is displayed
+literally, if the terminal supports it. If the terminal does not
+support it, the character is said to be @dfn{glyphless}, and it is
+usually displayed using a placeholder glyph. For example, if a
+graphical terminal has no font for a character, Emacs usually displays
+a box containing the character code in hexadecimal. @xref{Glyphless
+Chars}.
@end itemize
- The usual display conventions apply even when there is a display
+ The above display conventions apply even when there is a display
table, for any character whose entry in the active display table is
@code{nil}. Thus, when you set up a display table, you need only
specify the characters for which you want special behavior.
- These display rules apply to carriage return (character code 13), when
-it appears in the buffer. But that character may not appear in the
-buffer where you expect it, if it was eliminated as part of end-of-line
-conversion (@pxref{Coding System Basics}).
-
- These variables affect the way certain characters are displayed on the
-screen. Since they change the number of columns the characters occupy,
-they also affect the indentation functions. These variables also affect
+ The following variables affect how certain characters are displayed
+on the screen. Since they change the number of columns the characters
+occupy, they also affect the indentation functions. They also affect
how the mode line is displayed; if you want to force redisplay of the
mode line using the new values, call the function
@code{force-mode-line-update} (@pxref{Mode Line Format}).
@@ -5748,34 +5766,14 @@
@end defopt
@node Display Tables
address@hidden Display Tables
address@hidden Display Tables
@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 @acronym{ASCII} character
-set.
-
-The display table maps each character code into a sequence of
address@hidden, each glyph being a graphic that takes up one character
-position on the screen. You can also define how to display each glyph
-on your terminal, using the @dfn{glyph table}.
-
-Display tables affect how the mode line is displayed; if you want to
-force redisplay of the mode line using a new display table, call
address@hidden (@pxref{Mode Line Format}).
-
address@hidden
-* 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.
address@hidden menu
-
address@hidden Display Table Format
address@hidden Display Table Format
-
- A display table is actually a char-table (@pxref{Char-Tables}) with
address@hidden as its subtype.
+ A display table is a special-purpose char-table
+(@pxref{Char-Tables}), with @code{display-table} as its subtype, which
+is used to override the usual character display conventions. This
+section describes how to make, inspect, and assign elements to a
+display table object.
@defun make-display-table
This creates and returns a display table. The table initially has
@@ -5784,10 +5782,10 @@
The ordinary elements of the display table are indexed by character
codes; the element at index @var{c} says how to display the character
-code @var{c}. The value should be @code{nil} or a vector of the
-glyphs to be output (@pxref{Glyphs}). @code{nil} says to display the
-character @var{c} according to the usual display conventions
-(@pxref{Usual Display}).
+code @var{c}. The value should be @code{nil} (which means to display
+the character @var{c} according to the usual display conventions;
address@hidden Display}), or a vector of glyph codes (which means to
+display the character @var{c} as those glyphs; @pxref{Glyphs}).
@strong{Warning:} if you use the display table to change the display
of newline characters, the whole buffer will be displayed as one long
@@ -5832,12 +5830,11 @@
@example
(setq disptab (make-display-table))
-(let ((i 0))
- (while (< i 32)
- (or (= i ?\t) (= i ?\n)
- (aset disptab i (vector ?^ (+ i 64))))
- (setq i (1+ i)))
- (aset disptab 127 (vector ?^ ??)))
+(dotimes (i 32)
+ (or (= i ?\t)
+ (= i ?\n)
+ (aset disptab i (vector ?^ (+ i 64)))))
+(aset disptab 127 (vector ?^ ??))
@end example
@defun display-table-slot display-table slot
@@ -5870,17 +5867,19 @@
@subsection Active Display Table
@cindex active display table
- Each window can specify a display table, and so can each buffer. When
-a buffer @var{b} is displayed in window @var{w}, display uses the
-display table for window @var{w} if it has one; otherwise, the display
-table for buffer @var{b} if it has one; otherwise, the standard display
-table if any. The display table chosen is called the @dfn{active}
-display table.
+ Each window can specify a display table, and so can each buffer.
+The window's display table, if there is one, takes precedence over the
+buffer's display table. If neither exists, Emacs tries to use the
+standard display table; if that is @code{nil}, Emacs uses the usual
+character display conventions (@pxref{Usual Display}).
+
+ Note that display tables affect how the mode line is displayed, so
+if you want to force redisplay of the mode line using a new display
+table, call @code{force-mode-line-update} (@pxref{Mode Line Format}).
@defun window-display-table &optional window
-This function returns @var{window}'s display table, or @code{nil}
-if @var{window} does not have an assigned display table. The default
-for @var{window} is the selected window.
+This function returns @var{window}'s display table, or @code{nil} if
+there is none. The default for @var{window} is the selected window.
@end defun
@defun set-window-display-table window table
@@ -5890,39 +5889,29 @@
@end defun
@defvar buffer-display-table
-This variable is automatically buffer-local in all buffers; its value in
-a particular buffer specifies the display table for that buffer. If it
-is @code{nil}, that means the buffer does not have an assigned display
-table.
+This variable is automatically buffer-local in all buffers; its value
+specifies the buffer's display table. If it is @code{nil}, there is
+no buffer display table.
@end defvar
@defvar standard-display-table
-This variable's value is the default display table, used whenever a
-window has no display table and neither does the buffer displayed in
-that window. This variable is @code{nil} by default.
+The value of this variable is the standard display table, which is
+used when Emacs is displaying a buffer in a window with neither a
+window display table nor a buffer display table defined. Its default
+is @code{nil}.
@end defvar
- If there is no display table to use for a particular window---that is,
-if the window specifies none, its buffer specifies none, and
address@hidden is @code{nil}---then Emacs uses the usual
-display conventions for all character codes in that window. @xref{Usual
-Display}.
-
-A number of functions for changing the standard display table
-are defined in the library @file{disp-table}.
+The @file{disp-table} library defines several functions for changing
+the standard display table.
@node Glyphs
@subsection Glyphs
address@hidden glyph
- A @dfn{glyph} is a generalization of a character; it stands for an
-image that takes up a single character position on the screen. Normally
-glyphs come from vectors in the display table (@pxref{Display Tables}).
-
- A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code
-can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A
-simple glyph code is just a way of specifying a character and a face
-to output it in. @xref{Faces}.
+ A @dfn{glyph} is a graphical symbol which occupies a single
+character position on the screen. Each glyph is represented in Lisp
+as a @dfn{glyph code}. A glyph code can be @dfn{simple}, or it can be
+defined by the @dfn{glyph table}. A simple glyph code is just a way
+of specifying a character and a face to output it in. @xref{Faces}.
The following functions are used to manipulate simple glyph codes:
@@ -6015,6 +6004,99 @@
variable.
@end defvar
address@hidden Glyphless Chars
address@hidden Glyphless Character Display
address@hidden glyphless characters
+
+ @dfn{Glyphless characters} are not displayed in the usual way when
+they appear in a buffer, but in some special way (e.g. as a box
+containing a hexadecimal code). These include characters that cannot
+be displayed with any available font (on a graphical display), or that
+cannot be encoded by the terminal's coding system (on a text
+terminal). Specific characters can also be defined to be glyphless.
+
address@hidden glyphless-char-display
+The value of this variable is a char-table that defines glyphless
+characters and how they are displayed. If an entry is @code{nil}, the
+corresponding character is displayed in its usual way. Otherwise, an
+entry should be one of the following display methods:
+
address@hidden @asis
address@hidden @code{zero-width}
+Don't display the character.
+
address@hidden @code{thin-space}
+Display a thin space, 1-pixel wide on graphical displays, or
+1-character wide on text terminals.
+
address@hidden @code{empty-box}
+Display an empty box.
+
address@hidden @code{hex-code}
+Display a box containing the Unicode codepoint of the character, in
+hexadecimal notation.
+
address@hidden an @acronym{ASCII} string
+Display a box containing that string.
address@hidden table
+
address@hidden
+Except for @code{zero-width}, these methods display using the
address@hidden face.
+
+An entry can also be a cons cell @code{(@var{graphical}
+. @var{text})}, where @var{graphical} and @var{text} are the display
+methods on graphical displays and text terminals respectively.
+
+The char-table has one extra slot, which determines how to display any
+character that cannot be displayed with any available font, or cannot
+be encoded by the terminal's coding system. Its value should be one
+of the above display methods, except @code{zero-width} or a cons cell.
address@hidden defvar
+
address@hidden glyphless-char-display-control
+This user option provides a convenient way to set
address@hidden for groups of similar characters. It
+takes effect via a custom @code{:set} function (@pxref{Variable
+Definitions}), which update @code{glyphless-char-display}.
+
+Its value should be an alist of elements @code{(@var{group}
+. @var{method})}, where @var{group} is a symbol specifying a group of
+characters, and @var{method} is a symbol specifying how to display
+them.
+
address@hidden should be one of the following:
+
address@hidden @code
address@hidden c0-control
address@hidden control characters @code{U+0000} to @code{U+001F},
+excluding the newline and tab characters (normally displayed as escape
+sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed,
+emacs, The GNU Emacs Manual}).
+
address@hidden c1-control
address@hidden, non-printing characters @code{U+0080} to
address@hidden (normally displayed as octal escape sequences like
address@hidden).
+
address@hidden format-control
+Characters of Unicode General Category `Cf', such as @samp{U+200E}
+(Left-to-Right Mark), but excluding characters that have graphic
+images, such as @samp{U+00AD} (Soft Hyphen).
+
address@hidden no-font
+Characters for there is no suitable font, or which cannot be encoded
+by the terminal's coding system.
address@hidden table
+
address@hidden FIXME: this can also be `acronym', but that's not currently
address@hidden completely implemented; it applies only to the format-control
address@hidden group, and only works if the acronym is in `char-acronym-table'.
+The @var{method} symbol should be one of @code{zero-width},
address@hidden, @code{empty-box}, or @code{hex-code}. These have
+the same meanings as in @code{glyphless-char-display}, above.
address@hidden defopt
+
@node Window Systems
@section Window Systems
@@ -6290,96 +6372,3 @@
appropriate mirrored character in the reordered text. Lisp programs
can affect the mirrored display by changing this property. Again, any
such changes affect all of Emacs display.
-
address@hidden Glyphless Chars
address@hidden Glyphless Character Display
address@hidden glyphless characters
-
- @dfn{Glyphless characters} are not displayed in the usual way when
-they appear in a buffer, but in some special way (e.g. as a box
-containing a hexadecimal code). These include characters that cannot
-be displayed with any available font (on a graphical display), or that
-cannot be encoded by the terminal's coding system (on a text
-terminal). Specific characters can also be defined to be glyphless.
-
address@hidden glyphless-char-display
-The value of this variable is a char-table that defines glyphless
-characters and how they are displayed. If an entry is @code{nil}, the
-corresponding character is displayed in its usual way. Otherwise, an
-entry should be one of the following display methods:
-
address@hidden @asis
address@hidden @code{zero-width}
-Don't display the character.
-
address@hidden @code{thin-space}
-Display a thin space, 1-pixel wide on graphical displays, or
-1-character wide on text terminals.
-
address@hidden @code{empty-box}
-Display an empty box.
-
address@hidden @code{hex-code}
-Display a box containing the Unicode codepoint of the character, in
-hexadecimal notation.
-
address@hidden an @acronym{ASCII} string
-Display a box containing that string.
address@hidden table
-
address@hidden
-Except for @code{zero-width}, these methods display using the
address@hidden face.
-
-An entry can also be a cons cell @code{(@var{graphical}
-. @var{text})}, where @var{graphical} and @var{text} are the display
-methods on graphical displays and text terminals respectively.
-
-The char-table has one extra slot, which determines how to display any
-character that cannot be displayed with any available font, or cannot
-be encoded by the terminal's coding system. Its value should be one
-of the above display methods, except @code{zero-width} or a cons cell.
address@hidden defvar
-
address@hidden glyphless-char-display-control
-This user option provides a convenient way to set
address@hidden for groups of similar characters. It
-takes effect via a custom @code{:set} function (@pxref{Variable
-Definitions}), which update @code{glyphless-char-display}.
-
-Its value should be an alist of elements @code{(@var{group}
-. @var{method})}, where @var{group} is a symbol specifying a group of
-characters, and @var{method} is a symbol specifying how to display
-them.
-
address@hidden should be one of the following:
-
address@hidden @code
address@hidden c0-control
address@hidden control characters @code{U+0000} to @code{U+001F},
-excluding the newline and tab characters (normally displayed as escape
-sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed,
-emacs, The GNU Emacs Manual}).
-
address@hidden c1-control
address@hidden, non-printing characters @code{U+0080} to
address@hidden (normally displayed as octal escape sequences like
address@hidden).
-
address@hidden format-control
-Characters of Unicode General Category `Cf', such as @samp{U+200E}
-(Left-to-Right Mark), but excluding characters that have graphic
-images, such as @samp{U+00AD} (Soft Hyphen).
-
address@hidden no-font
-Characters for there is no suitable font, or which cannot be encoded
-by the terminal's coding system.
address@hidden table
-
address@hidden FIXME: this can also be `acronym', but that's not currently
address@hidden completely implemented; it applies only to the format-control
address@hidden group, and only works if the acronym is in `char-acronym-table'.
-The @var{method} symbol should be one of @code{zero-width},
address@hidden, @code{empty-box}, or @code{hex-code}. These have
-the same meanings as in @code{glyphless-char-display}, above.
address@hidden defopt
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2012-03-08 05:27:03 +0000
+++ b/doc/lispref/elisp.texi 2012-03-25 07:58:59 +0000
@@ -1265,14 +1265,11 @@
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
-* Usual Display:: The usual conventions for displaying
- nonprinting chars.
-* Display Tables:: How to specify other conventions.
+* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
-* Glyphless Chars:: How glyphless characters are drawn.
The Echo Area
@@ -1361,11 +1358,13 @@
* Abstract Display Functions:: Functions in the Ewoc package.
* Abstract Display Example:: Example of using Ewoc.
-Display Tables
+Character Display
-* 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.
+* Usual Display:: The usual conventions for displaying characters.
+* Display Tables:: 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.
+* Glyphless Chars:: How glyphless characters are drawn.
Operating System Interface
=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi 2012-03-08 05:27:03 +0000
+++ b/doc/lispref/vol1.texi 2012-03-25 07:58:59 +0000
@@ -1287,14 +1287,11 @@
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
-* Usual Display:: The usual conventions for displaying
- nonprinting chars.
-* Display Tables:: How to specify other conventions.
+* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
-* Glyphless Chars:: How glyphless characters are drawn.
The Echo Area
@@ -1383,11 +1380,13 @@
* Abstract Display Functions:: Functions in the Ewoc package.
* Abstract Display Example:: Example of using Ewoc.
-Display Tables
+Character Display
-* 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.
+* Usual Display:: The usual conventions for displaying characters.
+* Display Tables:: 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.
+* Glyphless Chars:: How glyphless characters are drawn.
Operating System Interface
=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi 2012-03-08 05:27:03 +0000
+++ b/doc/lispref/vol2.texi 2012-03-25 07:58:59 +0000
@@ -1286,14 +1286,11 @@
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
-* Usual Display:: The usual conventions for displaying
- nonprinting chars.
-* Display Tables:: How to specify other conventions.
+* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
-* Glyphless Chars:: How glyphless characters are drawn.
The Echo Area
@@ -1382,11 +1379,13 @@
* Abstract Display Functions:: Functions in the Ewoc package.
* Abstract Display Example:: Example of using Ewoc.
-Display Tables
+Character Display
-* 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.
+* Usual Display:: The usual conventions for displaying characters.
+* Display Tables:: 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.
+* Glyphless Chars:: How glyphless characters are drawn.
Operating System Interface
=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog 2012-03-24 13:23:23 +0000
+++ b/lisp/ChangeLog 2012-03-25 07:58:59 +0000
@@ -1,3 +1,7 @@
+2012-03-25 Chong Yidong <address@hidden>
+
+ * button.el (button-at): Minor addition to docstring.
+
2012-03-24 Simon Leinen <address@hidden>
* vc/vc.el (vc-merge): Fix a prompt.
=== modified file 'lisp/button.el'
--- a/lisp/button.el 2012-01-19 07:21:25 +0000
+++ b/lisp/button.el 2012-03-25 07:58:59 +0000
@@ -349,7 +349,9 @@
;; Finding buttons in a buffer
(defun button-at (pos)
- "Return the button at position POS in the current buffer, or nil."
+ "Return the button at position POS in the current buffer, or nil.
+If the button at POS is a text property button, the return value
+is a marker pointing to POS."
(let ((button (get-char-property pos 'button)))
(if (or (overlayp button) (null button))
button
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r107671: Updates to Display chapter of Lisp manual.,
Chong Yidong <=