Merge from origin/emacs-30

477335a10b ; Fix documentation of 'find-file-noselect'
9e3720bbb1 * doc/misc/gnus.texi (Category Syntax): Update gnus-agent...
456f44a7b3 ; Improve documentation of change hooks
f20d5e63bc ; * lisp/image.el (image-supported-file-p): Doc fix (bug#...
8ec2ddebdd ; Update documentation of GC in ELisp manual
57a9798c22 Prefer "tls" to "ssl" in documentation

doc/lispref/files.texi

@@ -149,9 +149,10 @@ The function returns an existing buffer if there is one; otherwise it
 creates a new buffer and reads the file into it.  When
 @code{find-file-noselect} uses an existing buffer, it first verifies
 that the file has not changed since it was last visited or saved in
-that buffer.  If the file has changed, this function asks the user
-whether to reread the changed file.  If the user says @samp{yes}, any
-edits previously made in the buffer are lost.
+that buffer (unless @var{nowarn} is non-@code{nil}, see below).  If the
+file has changed, this function asks the user whether to reread the
+changed file.  If the user says @samp{yes}, any edits previously made in
+the buffer are lost.
 
 Reading the file involves decoding the file's contents (@pxref{Coding
 Systems}), including end-of-line conversion, and format conversion
@@ -163,7 +164,8 @@ This function displays warning or advisory messages in various peculiar
 cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
 example, if it needs to create a buffer, and there is no file named
 @var{filename}, it displays the message @samp{(New file)} in the echo
-area, and leaves the buffer empty.
+area, and leaves the buffer empty.  The verification of the file's last
+change is also bypassed if @var{nowarn} is non-@code{nil}.
 
 The @code{find-file-noselect} function normally calls
 @code{after-find-file} after reading the file (@pxref{Subroutines of

doc/lispref/internals.texi

@@ -445,16 +445,17 @@ object type; space allocated to the contents of buffers does not count.
 
 The initial threshold value is @code{GC_DEFAULT_THRESHOLD}, defined in
 @file{alloc.c}.  Since it's defined in @code{word_size} units, the
-value is 400,000 for the default 32-bit configuration and 800,000 for
-the 64-bit one.  If you specify a larger value, garbage collection
-will happen less often.  This reduces the amount of time spent garbage
-collecting (so Lisp programs will run faster between cycles of garbage
-collection that happen more rarely), but increases total memory use.
-You may want to do this when running a program that creates lots of
-Lisp data, especially if you need it to run faster.  However, we
-recommend against increasing the threshold for prolonged periods of
-time, and advise that you never set it higher than needed for the
-program to run in reasonable time.  Using thresholds higher than
+value is 400,000 for the default 32-bit configuration, and 800,000 for
+the 64-bit one and for 32-bit builds configured with the
+@option{--with-wide-int} option.  If you specify a larger value, garbage
+collection will happen less often.  This reduces the amount of time
+spent garbage collecting (so Lisp programs will run faster between
+cycles of garbage collection that happen more rarely), but increases
+total memory use.  You may want to do this when running a program that
+creates lots of Lisp data, especially if you need it to run faster.
+However, we recommend against increasing the threshold for prolonged
+periods of time, and advise that you never set it higher than needed for
+the program to run in reasonable time.  Using thresholds higher than
 necessary could potentially cause higher system-wide memory pressure,
 and also make each garbage-collection cycle take much more time, and
 should therefore be avoided.
@@ -475,6 +476,10 @@ As the heap size increases, the time to perform a garbage collection
 increases.  Thus, it can be desirable to do them less frequently in
 proportion.
 
+The initial percentage value is 0.1 in interactive sessions and while
+dumping Emacs (@pxref{Building Emacs}), and 1.0 in non-interactive
+(a.k.a.@: ``batch'') sessions.
+
 As with @code{gc-cons-threshold}, do not enlarge this more than
 necessary, and never for prolonged periods of time.
 @end defopt

doc/lispref/text.texi

@@ -6311,7 +6311,11 @@ specific parts of the text.
   The functions you use in these hooks should save and restore the match
 data if they do anything that uses regular expressions; otherwise, they
 will interfere in bizarre ways with the editing operations that call
-them.
+them.  In addition, the functions in these hooks should avoid changing
+buffer text, faces, properties, overlays, and other aspects of the
+buffer-specific state except those that the hook functions themselves
+create and manage, because other parts of Emacs might become confused by
+such changes behind their back.
 
 @defvar before-change-functions
 This variable holds a list of functions to call when Emacs is about to

doc/misc/gnus.texi

@@ -14088,7 +14088,7 @@ indirect ones (three pre-made).
 Non-@code{nil} means the nntp server never echoes commands.  It is
 reported that some nntps server doesn't echo commands.  So, you may want
 to set this to non-@code{nil} in the method for such a server setting
-@code{nntp-open-connection-function} to @code{nntp-open-ssl-stream} for
+@code{nntp-open-connection-function} to @code{nntp-open-tls-stream} for
 example.  The default value is @code{nil}.  Note that the
 @code{nntp-open-connection-functions-never-echo-commands} variable
 overrides the @code{nil} value of this variable.
@@ -14144,18 +14144,26 @@ functions is also affected by commonly understood variables
 @findex nntp-open-network-stream
 @item nntp-open-network-stream
 This is the default, and simply connects to some port or other on the
-remote system.  If both Emacs and the server supports it, the
-connection will be upgraded to an encrypted @acronym{STARTTLS}
-connection automatically.
+remote system.  If both Emacs and the server supports it, the connection
+will be upgraded to an encrypted @acronym{STARTTLS} connection
+automatically.  If you want to avoid the possibility of a malicious
+intermediary blocking the use of @acronym{STARTTLS}, use
+@code{nntp-open-tls-stream} instead.
 
-@item network-only
-The same as the above, but don't do automatic @acronym{STARTTLS} upgrades.
+@item nntp-open-plain-stream
+@itemx network-only
+The same as the above, but don't do automatic @acronym{STARTTLS}
+upgrades.  Only use this if you want anyone to be able to read your
+traffic.
 
 @findex nntp-open-tls-stream
 @item nntp-open-tls-stream
 Opens a connection to a server over a @dfn{secure} channel.  To use
-this you must have @uref{https://www.gnu.org/software/gnutls/, GnuTLS}
-installed.  You then define a server as follows:
+this, your Emacs must have been compiled with GnuTLS support
+@uref{https://www.gnu.org/software/gnutls/, GnuTLS}.  You can check this
+using the @code{gnutls-available-p} command.
+
+You then define a server as follows:
 
 @lisp
 ;; @r{"nntps" is port 563 and is predefined in our @file{/etc/services}}
@@ -14167,26 +14175,10 @@ installed.  You then define a server as follows:
       (nntp-address "snews.bar.com"))
 @end lisp
 
-@c FIXME openssl s_client should be deprecated in favor of gnutls.
 @findex nntp-open-ssl-stream
 @item nntp-open-ssl-stream
-Opens a connection to a server over a @dfn{secure} channel.  To use
-this you must have @uref{https://www.openssl.org/, OpenSSL}
-@ignore
-@c Defunct URL, ancient package, so don't mention it.
-or @uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay}
-@end ignore
-installed.  You then define a server as follows:
-
-@lisp
-;; @r{"snews" is port 563 and is predefined in our @file{/etc/services}}
-;; @r{however, @samp{openssl s_client -port} doesn't like named ports.}
-;;
-(nntp "snews.bar.com"
-      (nntp-open-connection-function nntp-open-ssl-stream)
-      (nntp-port-number 563)
-      (nntp-address "snews.bar.com"))
-@end lisp
+This is the old name for @code{nntp-open-tls-stream}, and is
+completely equivalent.
 
 @findex nntp-open-netcat-stream
 @item nntp-open-netcat-stream
@@ -14528,7 +14520,7 @@ Here's an example method that's more complex:
         (nnimap-inbox "INBOX")
         (nnimap-split-methods default)
         (nnimap-expunge t)
-        (nnimap-stream ssl))
+        (nnimap-stream tls))
 @end example
 
 @table @code
@@ -14554,11 +14546,12 @@ How @code{nnimap} should connect to the server.  Possible values are:
 
 @table @code
 @item undecided
-This is the default, and this first tries the @code{ssl} setting, and
+This is the default, and this first tries the @code{tls} setting, and
 then tries the @code{network} setting.
 
-@item ssl
-This uses standard @acronym{TLS}/@acronym{SSL} connections.
+@item tls
+This uses standard @acronym{TLS}/@acronym{SSL} connections.  @code{ssl}
+is an equivalent but deprecated way to specify this.
 
 @item network
 Non-encrypted and unsafe straight socket connection, but will upgrade
@@ -18870,7 +18863,7 @@ operators sprinkled in between.
 
 Perhaps some examples are in order.
 
-Here's a simple predicate.  (It's the default predicate, in fact, used
+Here's a simple predicate.  (The default predicate is @code{false}, used
 for all groups that don't belong to any other category.)
 
 @lisp

lisp/files.el

@@ -2532,7 +2532,9 @@ be visible in the echo area."
 If a buffer exists visiting FILENAME, return that one, but
 verify that the file has not changed since visited or saved.
 The buffer is not selected, just returned to the caller.
-Optional second arg NOWARN non-nil means suppress any warning messages.
+Optional second arg NOWARN non-nil means suppress any warning messages,
+and also don't verify the that the file has not been changed since
+last visited or saved.
 Optional third arg RAWFILE non-nil means the file is read literally.
 Optional fourth arg WILDCARDS non-nil means do wildcard processing
 and visit all the matching files.  When wildcards are actually

lisp/gnus/nnimap.el

@@ -51,7 +51,7 @@
 
 (defvoo nnimap-server-port nil
   "The IMAP port used.
-If `nnimap-stream' is `ssl', this will default to `imaps'.  If not,
+If `nnimap-stream' is `tls', this will default to `imaps'.  If not,
 it will default to `imap'.")
 
 (defvoo nnimap-use-namespaces nil
@@ -63,10 +63,10 @@ names of your nnimap groups.")
 
 (defvoo nnimap-stream 'undecided
   "How nnimap talks to the IMAP server.
-The value should be either `undecided', `ssl' or `tls',
+The value should be either `undecided', `tls' or `ssl' (deprecated),
 `network', `starttls', `plain', or `shell'.
 
-If the value is `undecided', nnimap tries `ssl' first, then falls
+If the value is `undecided', nnimap tries `tls' first, then falls
 back on `network'.")
 
 (defvoo nnimap-shell-program (if (boundp 'imap-shell-program)

lisp/gnus/nntp.el

@@ -82,8 +82,9 @@ as its single argument, or one of the following special values:
   upgrading to a TLS connection via STARTTLS if possible.
 - `nntp-open-plain-stream' specifies an unencrypted network
   connection (no STARTTLS upgrade is attempted).
-- `nntp-open-ssl-stream' or `nntp-open-tls-stream' specify a TLS
-  network connection.
+- `nntp-open-tls-stream' specifies a TLS network connection (the
+  equivalent value `nntp-open-ssl-stream' is accepted for backwards
+  compatibility).
 
 Apart from the above special values, valid functions are as
 follows; please refer to their respective doc string for more
@@ -100,7 +101,7 @@ For indirect connections:
   "Non-nil means the nntp server never echoes commands.
 It is reported that some nntps server doesn't echo commands.  So, you
 may want to set this to non-nil in the method for such a server setting
-`nntp-open-connection-function' to `nntp-open-ssl-stream' for example.
+`nntp-open-connection-function' to `nntp-open-tls-stream' for example.
 Note that the `nntp-open-connection-functions-never-echo-commands'
 variable overrides the nil value of this variable.")
 

lisp/image.el

@@ -419,10 +419,10 @@ be determined."
 
  ;;;###autoload
 (defun image-supported-file-p (file)
-  "Say whether Emacs has native support for displaying TYPE.
-The value is a symbol specifying the image type, or nil if type
-cannot be determined (or if Emacs doesn't have built-in support
-for the image type)."
+  "Return non-nil if Emacs can display the specified image FILE.
+The returned value is a symbol specifying the image type of FILE,
+or nil if Emacs cannot display that image type or if the type
+cannot be determined."
   (let ((case-fold-search t)
         type)
     (catch 'found