Update the documentation about labeled (locked) narrowing

* src/xdisp.c (syms_of_xdisp) <fontification-functions>: Update
docstring.

* src/keyboard.c (syms_of_keyboard) <pre-command-hook>:
(syms_of_keyboard) <post-command-hook>: Update docstring.

* src/editfns.c:
(narrowing_locks): Explain why an alist is used instead of a
buffer-local variable.
(reset_outermost_narrowings): Point to recipes that demonstrate
why it is necessary to restore the user narrowing bounds when
redisplay starts.
(Fwiden): Update docstring.
(Fnarrow_to_region): Update docstring.
(Finternal__lock_narrowing): Update docstring.
(Finternal__unlock_narrowing): Update docstring.
(Fsave_restriction): Update docstring.

* src/buffer.c (syms_of_buffer)
<long-line-optimizations-region-size>: Update docstring.
(syms_of_buffer) <long-line-optimizations-bol-search-limit>:
Update docstring.

* lisp/subr.el (with-narrowing): Update docstring.
(without-narrowing): Update docstring.

* etc/NEWS: Mention the 'long-line-optimizations-region-size' and
'long-line-optimizations-bol-search-limit' options.
Announce the 'with-narrowing' and 'without-narrowing' forms.

* doc/lispref/positions.texi (Narrowing): Update the documentation
of 'narrow-to-region', 'widen' and 'save-restriction'.  Document
the 'with-narrowing' and 'without-narrowing' special forms.

* doc/lispref/display.texi (Auto Faces): Update the documentation.

* doc/lispref/commands.texi (Command Overview): Document the fact
that the buffer is narrowed around 'pre-command-hook' and
'post-command-hook' when the buffer text includes very long lines.

1 files changed, 18 insertions, 17 deletions

diff --git a/src/buffer.c b/src/buffer.c
index 07723a7c6ff..755061d0dee 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -5918,18 +5918,18 @@ There is no reason to change that value except for debugging purposes.  */);
 
   DEFVAR_INT ("long-line-optimizations-region-size",
               long_line_optimizations_region_size,
-              doc: /* Region size for locked narrowing in buffers with long lines.
+              doc: /* Region size for narrowing in buffers with long lines.
 
-This variable has effect only in buffers which contain one or more
-lines whose length is above `long-line-threshold', which see.  For
-performance reasons, in such buffers, low-level hooks such as
-`fontification-functions' or `post-command-hook' are executed on a
-narrowed buffer, with a narrowing locked with `narrowing-lock'.  This
-variable specifies the size of the narrowed region around point.
+This variable has effect only in buffers in which
+`long-line-optimizations-p' is non-nil.  For performance reasons, in
+such buffers, the `fontification-functions', `pre-command-hook' and
+`post-command-hook' hooks are executed on a narrowed buffer around
+point, as if they were called in a `with-narrowing' form with a label.
+This variable specifies the size of the narrowed region around point.
 
 To disable that narrowing, set this variable to 0.
 
-See also `long-line-locked-narrowing-bol-search-limit'.
+See also `long-line-optimizations-bol-search-limit'.
 
 There is no reason to change that value except for debugging purposes.  */);
   long_line_optimizations_region_size = 500000;
@@ -5938,15 +5938,16 @@ There is no reason to change that value except for debugging purposes.  */);
               long_line_optimizations_bol_search_limit,
               doc: /* Limit for beginning of line search in buffers with long lines.
 
-This variable has effect only in buffers which contain one or more
-lines whose length is above `long-line-threshold', which see.  For
-performance reasons, in such buffers, low-level hooks such as
-`fontification-functions' or `post-command-hook' are executed on a
-narrowed buffer, with a narrowing locked with `narrowing-lock'.  The
-variable `long-line-locked-narrowing-region-size' specifies the size
-of the narrowed region around point.  This variable, which should be a
-small integer, specifies the number of characters by which that region
-can be extended backwards to make it start at the beginning of a line.
+This variable has effect only in buffers in which
+`long-line-optimizations-p' is non-nil.  For performance reasons, in
+such buffers, the `fontification-functions', `pre-command-hook' and
+`post-command-hook' hooks are executed on a narrowed buffer around
+point, as if they were called in a `with-narrowing' form with a label.
+The variable `long-line-optimizations-region-size' specifies the
+size of the narrowed region around point.  This variable, which should
+be a small integer, specifies the number of characters by which that
+region can be extended backwards to make it start at the beginning of
+a line.
 
 There is no reason to change that value except for debugging purposes.  */);
   long_line_optimizations_bol_search_limit = 128;