procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Minor docs copyedits

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

* doc/lispref/positions.texi (Narrowing): Improve documentation of
labeled narrowing.
This commit is contained in:
Eli Zaretskii 2023-02-13 20:37:15 +02:00
parent 13bcff3da5
commit 4bb27a5ca9
2 changed files with 20 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

18
doc/lispref/positions.texi
View file

@ -1153,9 +1153,10 @@ saved bounds. In that case it is equivalent to
body) body)
@end example @end example
When the optional @var{label} symbol argument is present however, the @cindex labeled narrowing
narrowing is labeled. A labeled narrowing differs from a non-labeled When the optional argument @var{label}, a symbol, is present, the
one in several ways: narrowing is @dfn{labeled}. A labeled narrowing differs from a
non-labeled one in several ways:
@itemize @bullet @itemize @bullet
@item @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 visible on display, and never interfere with narrowings set by the
user. user.
@end itemize @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 @end defspec
@defspec without-restriction [:label label] body @defspec without-restriction [:label label] body
@ -1191,7 +1197,7 @@ restores the saved bounds. In that case it is equivalent to
body) body)
@end example @end example
When the optional @var{label} argument is present however, the When the optional argument @var{label} is present, the narrowing set
narrowing set by @code{with-restriction} with the same @var{label} by @code{with-restriction} with the same @var{label} argument is
argument is lifted. lifted.
@end defspec @end defspec

10
etc/NEWS
View file

@ -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 hooks are executed on a narrowed portion of the buffer, whose size is
controlled by the variables 'long-line-optimizations-region-size' and controlled by the variables 'long-line-optimizations-region-size' and
'long-line-optimizations-bol-search-limit', as if they were in a 'long-line-optimizations-bol-search-limit', as if they were in a
'with-restriction form. This may, in particular, cause occasional 'with-restriction' form. This may, in particular, cause occasional
mis-fontifications in these buffers. 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 The new function 'long-line-optimizations-p' returns non-nil when
these optimizations are in effect in the current buffer. these optimizations are in effect in the current buffer.