Minor improvements of recent documentation changes

* src/editfns.c (Fwiden):
* doc/lispref/display.texi (Auto Faces):
* src/xdisp.c (syms_of_xdisp) <fontification-functions>:
* etc/NEWS: Clarify and improve wording of documentation changes.

4 files changed, 31 insertions, 19 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 08bf7441df0..f5fb0aaee70 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3479,6 +3479,12 @@ function finishes are the ones that really matter.
 
 For efficiency, we recommend writing these functions so that they
 usually assign faces to around 400 to 600 characters at each call.
+
+When the buffer text includes very long lines, these functions are
+called with the buffer narrowed to a relatively small region around
+@var{pos}, and with narrowing locked, so the functions cannot use
+@code{widen} to gain access to the rest of the buffer.
+@xref{Narrowing}.
 @end defvar
 
 @node Basic Faces
diff --git a/etc/NEWS b/etc/NEWS
index 8d958c66cd8..2259c0e766f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -334,16 +334,21 @@ Use something like 'M-x shell RET ssh <host> RET' instead.
 * Changes in Emacs 29.1
 
 ---
-** Emacs is now capable of editing files with arbitrarily long lines.
-The display of long lines has been optimized, and Emacs no longer
-chokes when a buffer on display contains long lines.  If you still
-experience slowdowns while editing files with long lines, this is due
-either to the current major mode or one of the enabled minor modes, in
-which case you should open the the file with M-x find-file-literally
-instead of C-x C-f, or to truncation of long lines, which you can
-disable with C-x x t.  The buffer may also be occasionally
-mis-fontified.  The variable 'long-line-threshold' controls whether
-and when these display optimizations are used.
+** Emacs is now capable of editing files with very long lines.
+The display of long lines has been optimized, and Emacs should no
+longer choke when a buffer on display contains long lines.  The
+variable 'long-line-threshold' controls whether and when these display
+optimizations are in effect.
+
+If you still experience slowdowns while editing files with long lines,
+this is due either to the current major mode or to one of the enabled
+minor modes.  Try disabling the minor modes, or turn on 'so-long-mode'
+or 'so-long-minor-mode', or visit the file with find-file-literally'
+instead of the usual 'C-x C-f'.  Another reason for slowdown could be
+line truncation, which you can turn off with 'C-x x t'.
+
+Note that the display optimizations in these cases may cause the
+buffer to be occasionally mis-fontified.
 
 +++
 ** New command to change the font size globally.
@@ -2458,10 +2463,10 @@ be saved.
 
 +++
 ** New argument LOCK of 'narrow-to-region'.
-When 'narrow-to-region' is called from Lisp with the optional third
-argument LOCK non-nil, calls to 'widen', or to 'narrow-to-region' with
-an optional argument LOCK nil, do not produce any effect until the end
-of the current body form.
+If 'narrow-to-region' is called from Lisp with the new optional
+argument LOCK non-nil, then calls to 'widen' and calls to
+'narrow-to-region' with the optional argument LOCK nil or omitted do
+not produce any effect until the end of the current body form.
 
 ** Themes
 
diff --git a/src/editfns.c b/src/editfns.c
index 40e65dda0c9..d15d4dc68b9 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -2661,8 +2661,8 @@ DEFUN ("widen", Fwiden, Swiden, 0, 0, "",
 This allows the buffer's full text to be seen and edited.
 
 When called from Lisp inside a body form in which `narrow-to-region'
-was called with an optional argument LOCK non-nil, this does not
-produce any effect.  */)
+was called with an optional argument LOCK non-nil, this function does
+not produce any effect.  */)
   (void)
 {
   if (! NILP (Vrestrictions_locked))
diff --git a/src/xdisp.c b/src/xdisp.c
index 8867406c4e2..3ef3c0d3796 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -36653,12 +36653,13 @@ The tool bar style must also show labels for this to have any effect, see
     doc: /* List of functions to call to fontify regions of text.
 Each function is called with one argument POS.  Functions must
 fontify a region starting at POS in the current buffer, and give
-fontified regions the property `fontified'.
+fontified regions the property `fontified' with a non-nil value.
 
 Note that, when the buffer contains one or more lines whose length is
-above `long-line-threshold', the restrictions of the buffer are locked
+above `long-line-threshold', the narrowing of the buffer is locked
 (see `narrow-to-region'), and these functions only have access to a
-small portion of the buffer around POS.  */);
+small portion of the buffer around POS and cannot use `widen' to gain
+access to other portions of buffer text.  */);
   Vfontification_functions = Qnil;
   Fmake_variable_buffer_local (Qfontification_functions);