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, 5 insertions, 5 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index c5374e1481a..1b7ef006634 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3501,11 +3501,11 @@ 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}.
+Note that, when the buffer text includes very long lines, these
+functions are called as if they were in a @code{with-narrowing} form
+(see @ref{Narrowing}), with a
+@code{long-line-optimizations-in-fontification-functions} label and
+with the buffer narrowed to a portion around @var{pos}.
 @end defvar
 
 @node Basic Faces