From d735cf50f7d8af52b44a5b45a8254b221ac73cef Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Wed, 5 Jul 2006 17:09:30 +0000 Subject: [PATCH] (Buffer Contents): Add example of text props in result of buffer-substring. (Text Properties): Explain better about use of specific property names. (Property Search): Some cleanups; reorder some functions. --- lispref/text.texi | 55 ++++++++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 20 deletions(-) diff --git a/lispref/text.texi b/lispref/text.texi index 802c69145c5..6c295627ced 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -176,10 +176,7 @@ It is not necessary for @var{start} to be less than @var{end}; the arguments can be given in either order. But most often the smaller argument is written first. -If the text being copied has any text properties, these are copied into -the string along with the characters they belong to. @xref{Text -Properties}. However, overlays (@pxref{Overlays}) in the buffer and -their properties are ignored, not copied. +Here's an example which assumes Font-Lock mode is not enabled: @example @group @@ -198,6 +195,21 @@ This is the contents of buffer foo @result{} "he contents of buffer foo\n" @end group @end example + +If the text being copied has any text properties, these are copied into +the string along with the characters they belong to. @xref{Text +Properties}. However, overlays (@pxref{Overlays}) in the buffer and +their properties are ignored, not copied. + +For example, if Font-Lock mode is enabled, you might get results like +these: + +@example +@group +(buffer-substring 1 10) + @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t)) +@end group +@end example @end defun @defun buffer-substring-no-properties start end @@ -2530,12 +2542,15 @@ property list}, much like the property list of a symbol (@pxref{Property Lists}). The properties belong to a particular character at a particular place, such as, the letter @samp{T} at the beginning of this sentence or the first @samp{o} in @samp{foo}---if the same character -occurs in two different places, the two occurrences generally have +occurs in two different places, the two occurrences in general have different properties. Each property has a name and a value. Both of these can be any Lisp -object, but the name is normally a symbol. The usual way to access the -property list is to specify a name and ask what value corresponds to it. +object, but the name is normally a symbol. Typically each property +name symbol is used for a particular purpose; for instance, the text +property @code{face} specifies the faces for displaying the character +(@pxref{Special Properties}). The usual way to access the property +list is to specify a name and ask what value corresponds to it. If a character has a @code{category} property, we call it the @dfn{category} of the character. It should be a symbol. The properties @@ -2838,13 +2853,20 @@ which all properties are constant: @end smallexample @end defun +@defun previous-property-change pos &optional object limit +This is like @code{next-property-change}, but scans back from @var{pos} +instead of forward. If the value is non-@code{nil}, it is a position +less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} +equals @var{pos}. +@end defun + @defun next-single-property-change pos prop &optional object limit -The function scans the text forward from position @var{pos} in the -string or buffer @var{object} till it finds a change in the @var{prop} -property, then returns the position of the change. In other words, it -returns the position of the first character beyond @var{pos} whose -@var{prop} property differs from that of the character just after -@var{pos}. +The function scans text for a change in the @var{prop} property, then +returns the position of the change. The scan goes forward from +position @var{pos} in the string or buffer @var{object}. In other +words, this function returns the position of the first character +beyond @var{pos} whose @var{prop} property differs from that of the +character just after @var{pos}. If @var{limit} is non-@code{nil}, then the scan ends at position @var{limit}. If there is no property change before that point, @@ -2856,13 +2878,6 @@ non-@code{nil}, it is a position greater than or equal to @var{pos}; it equals @var{pos} only if @var{limit} equals @var{pos}. @end defun -@defun previous-property-change pos &optional object limit -This is like @code{next-property-change}, but scans back from @var{pos} -instead of forward. If the value is non-@code{nil}, it is a position -less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} -equals @var{pos}. -@end defun - @defun previous-single-property-change pos prop &optional object limit This is like @code{next-single-property-change}, but scans back from @var{pos} instead of forward. If the value is non-@code{nil}, it is a -- 2.39.2