Merge from origin/emacs-29

a4828155d8 ; * doc/lispintro/emacs-lisp-intro.texi (nthcdr): Whitesp...
df1a9e42ba Document :box attribute caveats when used on display strings
ca17bc8dd0 Improve documentation of 'movemail'
d47aa33bcd Replace incorrect link in Rmail chapter of Emacs manual
35138b90dd ; * doc/lispref/parsing.texi (Parsing Program Source): Im...
3dd09516c9 ; Improve documentation of 'set-fontset-font'
042b58b5ff ; * doc/emacs/search.texi (Word Search): Add index entry.
60b1768dc5 ; * src/window.c (Fwindow_scroll_bars): Doc fix.

doc/emacs/rmail.texi

@@ -1428,7 +1428,7 @@ encrypted/decrypted text.
 your Rmail file (@pxref{Rmail Inbox}).  When loaded for the first time,
 Rmail attempts to locate the @command{movemail} program and determine its
 version.  There are two versions of the @command{movemail} program: the
-GNU Mailutils version (@pxref{movemail,,,mailutils,GNU mailutils}),
+GNU Mailutils version (@pxref{movemail,,,mailutils,GNU Mailutils Manual}),
 and an Emacs-specific version that is built and installed unless Emacs
 was configured @option{--with-mailutils} in effect.
 The two @command{movemail} versions support the same
@@ -1446,8 +1446,7 @@ mailboxes, etc.  It is able to access remote mailboxes using the POP3
 or IMAP4 protocol, and can retrieve mail from them using a TLS
 encrypted channel.  It also accepts mailbox arguments in @acronym{URL}
 form.  The detailed description of mailbox @acronym{URL}s can be found
-@c Note this node seems to be missing in some versions of mailutils.info?
-in @ref{URL,,,mailutils,Mailbox URL Formats}.  In short, a
+in @ref{Mailbox,,,mailutils,GNU Mailutils Manual}.  In short, a
 @acronym{URL} is:
 
 @smallexample
@@ -1458,6 +1457,8 @@ in @ref{URL,,,mailutils,Mailbox URL Formats}.  In short, a
 where square brackets denote optional elements.
 
 @table @var
+@cindex mailbox protocol, @command{movemail}
+@cindex format, of @command{movemail} mailbox
 @item proto
 Specifies the @dfn{mailbox protocol}, or @dfn{format} to
 use.  The exact semantics of the rest of @acronym{URL} elements depends
@@ -1503,23 +1504,13 @@ automatically by @command{movemail}.
 
 @item pop
 @itemx pops
-A remote mailbox to be accessed via POP3 protocol.  @var{user}
-specifies the remote user name to use, @var{pass} may be used to
-specify the user password, @var{host-or-file-name} is the name or IP
-address of the remote mail server to connect to, and @var{port} is the
-port number; e.g., @code{pop://smith:guessme@@remote.server.net:995}.
-If the server supports it, @command{movemail} tries to use an
-encrypted connection---use the @samp{pops} form to require one.
+A remote mailbox to be accessed via POP3 protocol.  @xref{Remote
+Mailboxes}, for details.
 
 @item imap
 @itemx imaps
-A remote mailbox to be accessed via IMAP4 protocol.  @var{user}
-specifies the remote user name to use, @var{pass} may be used to
-specify the user password, @var{host-or-file-name} is the name or IP
-address of the remote mail server to connect to, and @var{port} is the
-port number; e.g., @code{imap://smith:guessme@@remote.server.net:993}.
-If the server supports it, @command{movemail} tries to use an
-encrypted connection---use the @samp{imaps} form to require one.
+A remote mailbox to be accessed via IMAP4 protocol.  @xref{Remote
+Mailboxes}, for details.
 @end table
 
   Alternatively, you can specify the file name of the mailbox to use.
@@ -1541,6 +1532,7 @@ listed in @code{rmail-movemail-search-path}, then in @code{exec-path}
 @node Remote Mailboxes
 @section Retrieving Mail from Remote Mailboxes
 @pindex movemail
+@cindex remote mailboxes, accessing by @command{movemail}
 
   Some sites use a method called POP3 for accessing users' inbox data
 instead of storing the data in inbox files.  The Mailutils
@@ -1565,8 +1557,9 @@ Additionally, you may specify the password in the mailbox @acronym{URL}:
 case, @var{password} takes preference over the one set by
 @code{rmail-remote-password} (see below).  This is especially useful
 if you have several remote mailboxes with different passwords.
-If using Mailutils @command{movemail}, you may wish to use
-@samp{pops} in place of @samp{pop}.
+If using Mailutils @command{movemail} and the server supports
+encrypted connections, @command{movemail} tries to use it; specify
+@samp{pops:} instead of @samp{pop:} to require such a connection.
 
   For backward compatibility, Rmail also supports an alternative way of
 specifying remote POP3 mailboxes.  Specifying an inbox name in the form
@@ -1576,12 +1569,14 @@ specifying remote POP3 mailboxes.  Specifying an inbox name in the form
 the machine on which to look for the POP3 server.
 
 @cindex IMAP mailboxes
-  Another method for accessing remote mailboxes is IMAP@.  This method is
-supported only by the Mailutils @command{movemail}.  To specify an IMAP
-mailbox in the inbox list, use the following mailbox @acronym{URL}:
-@samp{imap://@var{username}[:@var{password}]@@@var{hostname}:@var{port}}.  The
-@var{password} part is optional, as described above.  You may wish to
-use @samp{imaps} in place of @samp{imap}.
+  Another method for accessing remote mailboxes is IMAP@.  This method
+is supported only by the Mailutils @command{movemail}, and uses the
+IMAP4 protocol.  To specify an IMAP mailbox in the inbox list, use the
+following mailbox @acronym{URL}:
+@samp{imap://@var{username}[:@var{password}]@@@var{hostname}:@var{port}}.
+The @var{password} part is optional, as described above.  If the
+server supports it, @command{movemail} tries to use an encrypted
+connection---use the @samp{imaps:} form to require one.
 
 @vindex rmail-remote-password
 @vindex rmail-remote-password-required

doc/emacs/search.texi

@@ -784,6 +784,7 @@ matching}) has no effect on them.
 @vindex eww-search-prefix
 @cindex Internet search
 @cindex search Internet for keywords
+@cindex web search
   To search the Web for the text in region, type @kbd{M-s M-w}.  This
 command performs an Internet search for the words in region using the
 search engine whose @acronym{URL} is specified by the variable

doc/lispintro/emacs-lisp-intro.texi

@@ -7193,7 +7193,7 @@ the @samp{@result{}} shows what is returned.
 @smallexample
 @group
 (cdr '(pine fir oak maple))
-     @result{}(fir oak maple)
+     @result{} (fir oak maple)
 @end group
 
 @group
@@ -7203,7 +7203,7 @@ the @samp{@result{}} shows what is returned.
 
 @group
 (cdr '(oak maple))
-     @result{}(maple)
+     @result{} (maple)
 @end group
 
 @group

doc/lispref/display.texi

@@ -2752,6 +2752,11 @@ being pressed.  If it is @code{pressed-button}, the box looks like a
 @code{flat-button} or omitted, a plain 2D box is used.
 @end table
 
+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}.
+
 @item :inverse-video
 Whether or not characters should be displayed in inverse video.  The
 value should be @code{t} (yes) or @code{nil} (no).
@@ -4023,6 +4028,14 @@ the charset @code{japanese-jisx0208}:
 (set-fontset-font t 'japanese-jisx0208
                   (font-spec :family "Kochi Gothic"))
 @end smallexample
+
+Note that this function should generally be called from the user's
+init files, and more generally before any of @var{characters} were
+displayed in the current Emacs session.  That's because for some
+scripts, Emacs caches the way they are displayed, and the cached
+information includes the font used for them -- once these characters
+are displayed once, the cached font will continue to be used
+regardless of changes in the fontsets.
 @end defun
 
 @defun char-displayable-p char
@@ -5272,6 +5285,34 @@ characters get a second string (@code{concat} creates a new string
 object), so they are replaced with one @samp{A}; and so on.  Thus, the
 ten characters appear as five A's.
 
+@cindex box face attribute, and @code{display} properties
+Note: Using @code{:box} face attribute (@pxref{Face Attributes}) on a
+replacing @code{display} string that is adjacent to normal text with
+the same @code{:box} style can lead to display artifacts when moving
+the cursor across the text with this face attribute.  These can be
+avoided by applying the @code{:box} attribute directly to the text
+being replaced, rather than (or in addition to) the @code{display}
+string itself.  Here's an example:
+
+@smallexample
+@group
+;; Causes display artifacts when moving the cursor across text
+(progn
+  (put-text-property 1 2 'display (propertize "  [" 'face '(:box t)))
+  (put-text-property 2 3 'face '(:box t))
+  (put-text-property 3 4 'display (propertize "]  " 'face '(:box t))))
+@end group
+
+@group
+;; No display artifacts due to `:box'
+(progn
+  (add-text-properties 1 2 '(face (:box t) display "  ["))
+  (put-text-property 2 3 'face '(:box t))
+  (add-text-properties 3 4 '(face (:box t) display "]  ")))
+@end group
+@end smallexample
+
+
 @node Specified Space
 @subsection Specified Spaces
 @cindex spaces, specified height or width

doc/lispref/parsing.texi

@@ -4,6 +4,7 @@
 @c See the file elisp.texi for copying conditions.
 @node Parsing Program Source
 @chapter Parsing Program Source
+@cindex parsing program source
 
 @cindex syntax tree, from parsing program source
 Emacs provides various ways to parse program source text and produce a

src/fontset.c

@@ -1528,7 +1528,16 @@ Optional 5th argument ADD, if non-nil, specifies how to add FONT-SPEC
 to the previously set font specifications for CHARACTERS.  If it is
 `prepend', FONT-SPEC is prepended to the existing font specifications.
 If it is `append', FONT-SPEC is appended.  By default, FONT-SPEC
-overwrites the previous settings.  */)
+overwrites the previous settings.
+
+For reliable results, this function should be called before any
+of CHARACTERS were displayed in the current Emacs session.  In
+particular, if some of CHARACTERS are displayed using character
+compositions, those compositions will be cached after they are first
+produced, and the cached values include the font used for displaying
+the composed characters -- calling this function will not affect the
+font recorded in the cache of compositions, thus they will continue
+to be shown using the fonts from before the call.  */)
   (Lisp_Object fontset, Lisp_Object characters, Lisp_Object font_spec,
    Lisp_Object frame, Lisp_Object add)
 {

src/window.c

@@ -8191,9 +8191,18 @@ DEFUN ("window-scroll-bars", Fwindow_scroll_bars, Swindow_scroll_bars,
 WINDOW must be a live window and defaults to the selected one.
 
 Value is a list of the form (WIDTH COLUMNS VERTICAL-TYPE HEIGHT LINES
-HORIZONTAL-TYPE PERSISTENT), see `set-window-scroll-bars'.  If WIDTH
-or HEIGHT is nil or VERTICAL-TYPE or HORIZONTAL-TYPE is t, WINDOW is
-using the frame's corresponding value.  */)
+HORIZONTAL-TYPE PERSISTENT).  WIDTH reports the pixel width of the
+vertical scroll bar; COLUMNS is the equivalent number of columns.
+Similarly, HEIGHT and LINES are the height of the horizontal scroll
+bar in pixels and the equivalent number of lines.  VERTICAL-TYPE
+reports the type of the vertical scroll bar, either left, right, nil,
+or t.  HORIZONTAL-TYPE reports the type of the horizontal scroll bar,
+either bottom, nil or t.  PERSISTENT reports the value specified by
+the last successful call to `set-window-scroll-bars', or nil if there
+was none.
+
+If WIDTH or HEIGHT is nil or VERTICAL-TYPE or HORIZONTAL-TYPE is t,
+WINDOW is using the corresponding value specified for the frame.  */)
   (Lisp_Object window)
 {
   struct window *w = decode_live_window (window);