[Emacs-diffs] Changes to emacs/lispref/text.texi,v

[Richard M. Stallman]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Richard M. Stallman <rms>       06/07/05 17:09:30

Index: text.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/text.texi,v
retrieving revision 1.119
retrieving revision 1.120
diff -u -b -r1.119 -r1.120
--- text.texi   16 Jun 2006 15:21:54 -0000      1.119
+++ text.texi   5 Jul 2006 17:09:30 -0000       1.120
@@ -176,10 +176,7 @@
 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 @@
      @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:
+
address@hidden
address@hidden
+(buffer-substring 1 10)
+     @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
address@hidden group
address@hidden example
 @end defun
 
 @defun buffer-substring-no-properties start end
@@ -2530,12 +2542,15 @@
 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 @@
 @end smallexample
 @end defun
 
address@hidden 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 address@hidden, it is a position
+less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
+equals @var{pos}.
address@hidden 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
address@hidden property differs from that of the character just after
address@hidden
+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 address@hidden, then the scan ends at position
 @var{limit}.  If there is no property change before that point,
@@ -2856,13 +2878,6 @@
 equals @var{pos} only if @var{limit} equals @var{pos}.
 @end defun
 
address@hidden 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 address@hidden, it is a position
-less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
-equals @var{pos}.
address@hidden 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 address@hidden, it is a