master 7f59cadf6f: ; Clarify documentation of "locked narrowing"

[Eli Zaretskii]

branch: master
commit 7f59cadf6f7ddead4c350cfe9582d2d1607c73d4
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; 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.
---
 doc/lispref/positions.texi | 8 ++++++--
 src/editfns.c              | 6 ++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index e08ee76ed9..333c8e19a0 100644
--- 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 35b2415e8b..07f5c0bbef 100644
--- 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);