; Clarify documentation of "locked narrowing"

* src/editfns.c (Fwiden, Fnarrow_to_region):
* doc/lispref/positions.texi (Narrowing): Explain when
'narrow-to-region' and 'widen' might have no effect.

diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index e08ee76ed9ad12885a8c5b577be67a8e5f4728d5..333c8e19a0e39836c8b25128c41a5fc06d7e0fcf 100644 (file)
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -1005,7 +1005,9 @@ of the current region (point and the mark, with the smallest first).
 
 Note that, in rare circumstances, Emacs may decide to leave, for
 performance reasons, the accessible portion of the buffer unchanged
-after a call to @code{narrow-to-region}.
+after a call to @code{narrow-to-region}.  This can happen when a Lisp
+program is called via low-level hooks, such as
+@code{jit-lock-functions}, @code{post-command-hook}, etc.
 @end deffn
 
 @deffn Command narrow-to-page &optional move-count
@@ -1033,7 +1035,9 @@ It is equivalent to the following expression:
 
 Note that, in rare circumstances, Emacs may decide to leave, for
 performance reasons, the accessible portion of the buffer unchanged
-after a call to @code{widen}.
+after a call to @code{widen}.  This can happen when a Lisp program is
+called via low-level hooks, such as @code{jit-lock-functions},
+@code{post-command-hook}, etc.
 
 @defun buffer-narrowed-p
 This function returns non-@code{nil} if the buffer is narrowed, and

diff --git a/src/editfns.c b/src/editfns.c
index 35b2415e8b10d2dafc82348256d7f32ec501799c..07f5c0bbef7ef37cd3cb07c6424c234c6afa53fd 100644 (file)
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -2663,7 +2663,8 @@ This allows the buffer's full text to be seen and edited.
 Note that, when the current buffer contains one or more lines whose
 length is above `long-line-threshold', Emacs may decide to leave, for
 performance reasons, the accessible portion of the buffer unchanged
-after this function is called.  */)
+after this function is called from low-level hooks, such as
+`jit-lock-functions' or `post-command-hook'.  */)
   (void)
 {
   if (! NILP (Vrestrictions_locked))
@@ -2756,7 +2757,8 @@ remain visible.
 Note that, when the current buffer contains one or more lines whose
 length is above `long-line-threshold', Emacs may decide to leave, for
 performance reasons, the accessible portion of the buffer unchanged
-after this function is called.  */)
+after this function is called from low-level hooks, such as
+`jit-lock-functions' or `post-command-hook'.  */)
   (Lisp_Object start, Lisp_Object end)
 {
   return narrow_to_region_internal (start, end, false);