From fb33e6a9a6bf86ac11c0a0c0eba8317f8dace874 Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Tue, 9 Oct 2007 01:24:28 +0000 Subject: [PATCH] (Display Margins): Correct the description of margin display specifications. (Replacing Specs): New subnode broken out of Display Property. --- lispref/display.texi | 105 +++++++++++++++++++++++++------------------ 1 file changed, 61 insertions(+), 44 deletions(-) diff --git a/lispref/display.texi b/lispref/display.texi index a5379847741..58b2ef11e72 100644 --- a/lispref/display.texi +++ b/lispref/display.texi @@ -3237,21 +3237,47 @@ to use the value specified by the frame. 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. + +@menu +* 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. +@end menu + +@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. 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 -@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: +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. + + 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 () @@ -3291,18 +3317,6 @@ object as the @code{display} property value, it's irrelevant 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. - -@menu -* 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. -@end menu - @node Specified Space @subsection Specified Spaces @cindex spaces, specified height or width @@ -3541,25 +3555,28 @@ string. @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 -@code{(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 +@code{display} 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 -- 2.39.2