Document cache-long-line-scans in @node Text Lines.

Cross-reference it in @node Screen Lines.

lispref/positions.texi

@@ -422,6 +422,36 @@ to use and more reliable (no dependence on goal column, etc.).
 @c ================
 @end ignore
 
+@defvar cache-long-line-scans
+This variable determines whether Emacs should use caches to handle long
+lines more quickly.  This variable is buffer-local, in all buffers.
+
+  Normally, the line-motion functions work by scanning the buffer for
+newlines.  Columnar operations (like @code{move-to-column} and
+@code{compute-motion}) also work by scanning the buffer, summing
+character widths as they go.  This works well for ordinary text, but if
+the buffer's lines are very long (say, more than 500 characters), these
+motion functions will take longer to execute.  Emacs may also take
+longer to update the display.
+
+  If @code{cache-long-line-scans} is non-@code{nil}, these motion
+functions cache the results of their scans, and consult the cache to
+avoid rescanning regions of the buffer until the text is modified.  The
+caches are most beneficial when they prevent the most searching---that
+is, when the buffer contains long lines and large regions of characters
+with the same, fixed screen width.
+
+  When @code{cache-long-line-scans} is non-@code{nil}, processing short
+lines will become slightly slower (because of the overhead of consulting
+the cache), and the caches will use memory roughly proportional to the
+number of newlines and characters whose screen width varies.
+
+  The caches require no explicit maintenance; their accuracy is
+maintained internally by the Emacs primitives.  Enabling or disabling
+the cache should not affect the behavior of any of the motion functions;
+it should only affect their performance.
+@end defvar
+
   Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
 These functions do not move point, but test whether it is already at the
 beginning or end of a line.
@@ -448,6 +478,12 @@ in, and even on the selected window (because the width, the truncation
 flag, and display table may vary between windows).  @xref{Usual
 Display}.
 
+  These functions scan text to determine where screen lines break, and
+thus take time proportional to the distance scanned.  If you intend to
+use them heavily, Emacs provides caches which may improve the
+performance of your code.  @xref{Text Lines, cache-long-line-scans}.
+
+
 @defun vertical-motion count &optional window
 This function moves point to the start of the screen line @var{count}
 screen lines down from the screen line containing point.  If @var{count}