Merge from origin/emacs-30

afb34a3b239 ; Improve documentation of ':box' face attribute
b38eb6da1d1 Fix docstring of c-ts-mode-indent-style
9fdb764898d Support PHP 8.4 and more reliable indentation (bug#74525)
bda0bce9e43 Don't inadvertently reset frame scroll bar sizes (Bug#74435)
3f99cdaf26d Mention special variables in lexical binding documentation
0ef0f18f163 Allow to go back to using 'ruby-mode' after loading 'ruby...
fc17e8727d4 Delete obsolete section in admin/notes/repo
3e396b2c5bb Improve documentation for 'while-let'
50b91ed458d Remove mention of treesit-defun-prefer-top-level (bug#74474)
03ae07291e8 Fix NS non-native fullscreen on initial frame load (bug#5...
8261d7224d3 Fix user options for listing and marking diary files

# Conflicts:
#	lisp/progmodes/c-ts-mode.el

3 files changed, 65 insertions, 13 deletions

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 80ed2ce899b..27ce932433d 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -322,25 +322,46 @@ There's a number of variations on this theme, and they're briefly
 described below.
 
 @defmac if-let* varlist then-form else-forms...
-Evaluate each binding in @var{varlist} in turn, like in @code{let*}
-(@pxref{Local Variables}), stopping if a binding value is @code{nil}.
-If all are non-@code{nil}, return the value of @var{then-form},
-otherwise the last form in @var{else-forms}.
+Evaluate each binding in @var{varlist}, stopping if a binding value is
+@code{nil}.  If all are non-@code{nil}, return the value of
+@var{then-form}, otherwise the last form in @var{else-forms}.
+
+Each element of @code{varlist} has the form @w{@code{(@var{symbol}
+@var{value-form})}}: @var{value-form} is evaluated and @var{symbol} is
+locally bound to the result.  Bindings are sequential, as in @code{let*}
+(@pxref{Local Variables}).  As a special case, @var{symbol} can be
+omitted if only the test result of @var{value-form} is of interest:
+@var{value-form} is evaluated and checked for @code{nil}, but its value
+is not bound.
 @end defmac
 
 @defmac when-let* varlist then-forms...
-Like @code{if-let*}, but without @var{else-forms}.
+Evaluate each binding in @var{varlist}, stopping if a binding value is
+@code{nil}.  If all are non-@code{nil}, return the value of the last
+form in @var{then-forms}.
+
+@var{varlist} has the same form as in @code{if-let*}: Each element of
+@code{varlist} has the form @w{@code{(@var{symbol} @var{value-form})}},
+in which @var{value-form} is evaluated and @var{symbol} is locally bound
+to the result.  Bindings are sequential, as in @code{let*} (@pxref{Local
+Variables}).  As a special case, @var{symbol} can be omitted if only the
+test result of @var{value-form} is of interest: @var{value-form} is
+evaluated and checked for @code{nil}, but its value is not bound.
 @end defmac
 
 @defmac and-let* varlist then-forms...
-Like @code{when-let*}, but in addition, if there are no
-@var{then-forms} and all the bindings evaluate to non-@code{nil}, return
+Evaluate each binding in @var{varlist}, stopping if a binding value is
+@code{nil}.  If all are non-@code{nil}, return the value of the last
+form in @var{then-forms}, or, if there are no @var{then-forms}, return
 the value of the last binding.
-@end defmac
 
-@defmac while-let spec then-forms...
-Like @code{when-let*}, but repeat until a binding in @var{spec} is
-@code{nil}.  The return value is always @code{nil}.
+@var{varlist} has the same form as in @code{if-let*}: Each element of
+@code{varlist} has the form @w{@code{(@var{symbol} @var{value-form})}},
+in which @var{value-form} is evaluated and @var{symbol} is locally bound
+to the result.  Bindings are sequential, as in @code{let*} (@pxref{Local
+Variables}).  As a special case, @var{symbol} can be omitted if only the
+test result of @var{value-form} is of interest: @var{value-form} is
+evaluated and checked for @code{nil}, but its value is not bound.
 @end defmac
 
 Some Lisp programmers follow the convention that @code{and} and
@@ -348,6 +369,27 @@ Some Lisp programmers follow the convention that @code{and} and
 @code{when} and @code{when-let*} are for forms evaluated for side-effect
 with returned values ignored.
 
+A similar macro exists to run a loop until one binding evaluates to
+@code{nil}:
+
+@defmac while-let spec then-forms...
+Evaluate each binding in @var{spec} in turn, stopping if a binding value
+is @code{nil}.  If all are non-@code{nil}, execute @var{then-forms},
+then repeat the loop.  Note that when the loop is repeated, the
+@var{value-forms} in @var{spec} are re-evaluated and the bindings are
+established anew.
+
+@var{varlist} has the same form as in @code{if-let*}: Each element of
+@code{varlist} has the form @w{@code{(@var{symbol} @var{value-form})}},
+in which @var{value-form} is evaluated and @var{symbol} is locally bound
+to the result.  Bindings are sequential, as in @code{let*} (@pxref{Local
+Variables}).  As a special case, @var{symbol} can be omitted if only the
+test result of @var{value-form} is of interest: @var{value-form} is
+evaluated and checked for @code{nil}, but its value is not bound.
+
+The return value of @code{while-let} is always @code{nil}.
+@end defmac
+
 @node Combining Conditions
 @section Constructs for Combining Conditions
 @cindex combining conditions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 7ada57d3d9c..a7c5ae561be 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2805,7 +2805,11 @@ being pressed.  If it is @code{pressed-button}, the box looks like a
 If you use the @code{:box} face attribute on strings displayed instead
 of buffer text via the @code{display} text property, special
 considerations might apply if the surrounding buffer text also has the
-@code{:box} face attribute.  @xref{Replacing Specs}.
+@code{:box} face attribute.  @xref{Replacing Specs}.  Also note that the
+vertical lines of the box are only drawn when @code{:box} attribute
+changes from @code{nil} to non-@code{nil} or vice versa; two consecutive
+face properties with a non-@code{nil} @code{:box} attribute will be
+displayed without the vertical line between them.
 
 @item :inverse-video
 Whether or not characters should be displayed in inverse video.  The
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index af11e498d86..0e9124920d1 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1096,7 +1096,7 @@ x                        ; @r{Note that @code{x} has no global value.}
 @end example
 
 @noindent
-The @code{let} binding defines a lexical environment in which the
+Here, the @code{let} binding defines a lexical environment in which the
 variable @code{x} is locally bound to 0.  Within this binding
 construct, we define a lambda expression which increments @code{x} by
 one and returns the incremented value.  This lambda expression is
@@ -1113,6 +1113,12 @@ functions which take a symbol argument (like @code{symbol-value},
 variable's dynamic binding (i.e., the contents of its symbol's value
 cell).
 
+  Note also that variables may be declared special, in which case they
+will use dynamic binding, even for new bindings such as a @code{let}
+binding.  Depending on how the variable is declared, it can be
+special globally, for a single file, or for a portion of a file.
+@xref{Dynamic Binding} for details.
+
 @node Dynamic Binding
 @subsection Dynamic Binding