(Overlays): Overlays don't scale well. See

http://lists.gnu.org/archive/html/emacs-devel/2009-04/msg00243.html.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 503212097d69a35e6e3c3935a367fbffd5f5acea..58349355a0be1493b0c100267e377fb9b0114fdf 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2009-04-11  Eli Zaretskii  <eliz@gnu.org>
+
+       * display.texi (Overlays): Overlays don't scale well.  See
+       http://lists.gnu.org/archive/html/emacs-devel/2009-04/msg00243.html.
+
 2009-04-10  Chong Yidong  <cyd@stupidchicken.com>
 
        * syntax.texi (Syntax Table Functions): Document cons cell

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index b017ce707048ac33607128e0019a93b1a8992d80..a6c09cd0e30fc601500dccb24c64ed2f90a7735f 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1148,6 +1148,14 @@ object that belongs to a particular buffer, and has a specified
 beginning and end.  It also has properties that you can examine and set;
 these affect the display of the text within the overlay.
 
+@cindex scalability of overlays
+The visual effect of an overlay is the same as of the corresponding
+text property (@pxref{Text Properties}).  However, due to a different
+implementation, overlays generally don't scale well (many operations
+take a time that is proportional to the number of overlays in the
+buffer).  If you need to affect the visual appearance of many portions
+in the buffer, we recommend to use text properties.
+
 An overlay uses markers to record its beginning and end; thus,
 editing the text of the buffer adjusts the beginning and end of each
 overlay so that it stays with the text.  When you create the overlay,