(Managing Overlays): Document overlay-recenter.

1 files changed, 15 insertions, 0 deletions

diff --git a/lispref/display.texi b/lispref/display.texi
index e7fab3ac7a8..a60cb9ab69d 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -1259,6 +1259,21 @@ foo
      @result{} t
 @end example
 
+  Emacs stores the overlays of each buffer in two lists, divided
+around an arbitrary ``center position.''  One list extends backwards
+through the buffer from that center position, and the other extends
+forwards from that center position.  The center position can be anywhere
+in the buffer.
+
+@defun overlay-recenter pos
+This function recenters the overlays of the current buffer around
+position @var{pos}.  That makes overlay lookup faster for positions
+near @var{pos}, but slower for positions far away from @var{pos}.
+@end defun
+
+  A loop that scans the buffer forwards, creating overlays, can run
+faster if you do @code{(overlay-recenter (point-max))} first.
+
 @node Overlay Properties
 @subsection Overlay Properties