From: Eli Zaretskii <eliz@gnu.org>
Date: Mon, 13 Feb 2023 18:37:15 +0000 (+0200)
Subject: ; Minor docs copyedits
X-Git-Tag: emacs-29.0.90~426^2~26
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=4bb27a5ca93f8269d9cd4b85fd948176304236eb;p=emacs.git

; Minor docs copyedits

* etc/NEWS: Add text about adapting to long-line optimizations.

* doc/lispref/positions.texi (Narrowing): Improve documentation of
labeled narrowing.
---

diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index f6a0cf14476..1b32f18922c 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -1153,9 +1153,10 @@ saved bounds.  In that case it is equivalent to
   body)
 @end example
 
-When the optional @var{label} symbol argument is present however, the
-narrowing is labeled.  A labeled narrowing differs from a non-labeled
-one in several ways:
+@cindex labeled narrowing
+When the optional argument @var{label}, a symbol, is present, the
+narrowing is @dfn{labeled}.  A labeled narrowing differs from a
+non-labeled one in several ways:
 
 @itemize @bullet
 @item
@@ -1178,6 +1179,11 @@ Labeled narrowings can only be used in Lisp programs: they are never
 visible on display, and never interfere with narrowings set by the
 user.
 @end itemize
+
+If you use @code{with-restriction} with the optional @var{label}
+argument, we recommend documenting the @var{label} in the doc strings
+of the functions which use it, so that other Lisp programs your code
+calls could lift the labeled narrowing if and when it needs.
 @end defspec
 
 @defspec without-restriction [:label label] body
@@ -1191,7 +1197,7 @@ restores the saved bounds.  In that case it is equivalent to
   body)
 @end example
 
-When the optional @var{label} argument is present however, the
-narrowing set by @code{with-restriction} with the same @var{label}
-argument is lifted.
+When the optional argument @var{label} is present, the narrowing set
+by @code{with-restriction} with the same @var{label} argument is
+lifted.
 @end defspec
diff --git a/etc/NEWS b/etc/NEWS
index db77fdfbb42..35063678f58 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -620,8 +620,14 @@ In buffers in which these display optimizations are in effect, the
 hooks are executed on a narrowed portion of the buffer, whose size is
 controlled by the variables 'long-line-optimizations-region-size' and
 'long-line-optimizations-bol-search-limit', as if they were in a
-'with-restriction form.  This may, in particular, cause occasional
-mis-fontifications in these buffers.
+'with-restriction' form.  This may, in particular, cause occasional
+mis-fontifications in these buffers.  Modes which are affected by
+these optimizations and by the fact that the buffer is narrowed,
+should adapt and either modify their algorithm so as not to expect the
+entire buffer to be accessible, or, if accessing outside of the
+narrowed region doesn't hurt performance, use the
+'without-restriction' form to temporarily lift the restriction and
+access portions of the buffer outside of the narrowed region.
 
 The new function 'long-line-optimizations-p' returns non-nil when
 these optimizations are in effect in the current buffer.