[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/doc/lispref/display.texi,v
From: |
Miles Bader |
Subject: |
[Emacs-diffs] Changes to emacs/doc/lispref/display.texi,v |
Date: |
Mon, 15 Oct 2007 02:07:58 +0000 |
CVSROOT: /cvsroot/emacs
Module name: emacs
Changes by: Miles Bader <miles> 07/10/15 02:07:53
Index: doc/lispref/display.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/lispref/display.texi,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- doc/lispref/display.texi 9 Oct 2007 08:52:55 -0000 1.5
+++ doc/lispref/display.texi 15 Oct 2007 02:07:52 -0000 1.6
@@ -3245,21 +3245,47 @@
insert images into text, and also 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 generally apply in parallel to
-the text they cover.
+specifications. Display specifications in the same @code{display}
+property value generally apply in parallel to the text they cover.
+
+ If several sources (overlays and/or a text property) specify values
+for the @code{display} property, only one of the values takes effect,
+following the rules of @code{get-char-property}. @xref{Examining
+Properties}.
+
+ The rest of this section describes several kinds of
+display specifications and what they mean.
+
address@hidden
+* Replacing Specs:: Display specs that replace the text.
+* 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.
address@hidden menu
+
address@hidden Replacing Specs
address@hidden Display Specs That Replace The Text
Some kinds of @code{display} specifications specify something to
-display instead of the text that has the property. If a list of
-display specifications includes more than one of this kind, the first
-is effective and the rest are ignored. You cannot interactively move
-point into the middle of the text that is thus replaced.
-
- For these specifications, ``the text that has the property'' means
-all the consecutive characters that have the same Lisp object as their
address@hidden 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:
+display instead of the text that has the property. These are called
address@hidden display specifications. Emacs does not allow the user
+to interactively move point into the middle of buffer text that is
+replaced in this way.
+
+ If a list of display specifications includes more than one replacing
+display specification, the first overrides the rest. Replacing
+display specifications make most other display specifications
+irrelevant, since those don't apply to the replacement.
+
+ 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:
@smallexample
(defun foo ()
@@ -3299,18 +3325,6 @@
whether they got this property from a single call to
@code{put-text-property} or from two different calls.
- The rest of this section describes several kinds of
-display specifications and what they mean.
-
address@hidden
-* 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.
address@hidden menu
-
@node Specified Space
@subsection Specified Spaces
@cindex spaces, specified height or width
@@ -3549,25 +3563,28 @@
@cindex display margins
@cindex margins, display
- A buffer can have blank areas called @dfn{display margins} on the left
-and on the right. Ordinary text never appears in these areas, but you
-can put things into the display margins using the @code{display}
-property.
-
- To put text in the left or right display margin of the window, use a
-display specification of the form @code{(margin right-margin)} or
address@hidden(margin left-margin)} on it. To put an image in a display margin,
-use that display specification along with the display specification for
-the image. Unfortunately, there is currently no way to make
-text or images in the margin mouse-sensitive.
-
- If you put such a display specification directly on text in the
-buffer, the specified margin display appears @emph{instead of} that
-buffer text itself. To put something in the margin @emph{in
-association with} certain buffer text without preventing or altering
-the display of that text, put a @code{before-string} property on the
-text and put the display specification on the contents of the
-before-string.
+ A buffer can have blank areas called @dfn{display margins} on the
+left and on the right. Ordinary text never appears in these areas,
+but you can put things into the display margins using the
address@hidden property. There is currently no way to make text or
+images in the margin mouse-sensitive.
+
+ The way to display something in the margins is to specify it in a
+margin display specification in the @code{display} property of some
+text. This is a replacing display specification, meaning that the
+text you put it on does not get displayed; the margin display appears,
+but that text does not.
+
+ A margin display specification looks like @code{((margin
+right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}.
+Here, @var{spec} is another display specification that says what to
+display in the margin. Typically it is a string of text to display,
+or an image descriptor.
+
+ To display something in the margin @emph{in association with}
+certain buffer text, without altering or preventing the display of
+that text, put a @code{before-string} property on the text and put the
+margin display specification on the contents of the before-string.
Before the display margins can display anything, you must give
them a nonzero width. The usual way to do that is to set these