From 57a9798c22a6d8a75883dfcc1c4430be428d20bb Mon Sep 17 00:00:00 2001 From: Robert Pluim Date: Mon, 28 Jul 2025 14:11:50 +0200 Subject: [PATCH 1/6] Prefer "tls" to "ssl" in documentation * doc/misc/gnus.texi (NNTP): Refer to 'nntp-open-tls-stream'. (Direct Functions, Customizing the IMAP Connection): Add commentary about desirability of STARTTLS. Correct documentation about use of GnuTLS. Use 'tls in example. * lisp/gnus/nnimap.el (nnimap-server-port): Mention 'tls in preference to 'ssl. * lisp/gnus/nntp.el (nntp-open-connection-function) (nntp-never-echoes-commands): Document 'nntp-open-tls-stream' as preferred to 'nntp-open-ssl-stream'. --- doc/misc/gnus.texi | 53 ++++++++++++++++++++------------------------- lisp/gnus/nnimap.el | 6 ++--- lisp/gnus/nntp.el | 7 +++--- 3 files changed, 30 insertions(+), 36 deletions(-) diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 13b4a339987..662f2f21301 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -14089,7 +14089,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. @@ -14145,18 +14145,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}} @@ -14168,26 +14176,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 @@ -14529,7 +14521,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 @@ -14555,11 +14547,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 diff --git a/lisp/gnus/nnimap.el b/lisp/gnus/nnimap.el index 215e8ac4cbf..f813d513180 100644 --- a/lisp/gnus/nnimap.el +++ b/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) diff --git a/lisp/gnus/nntp.el b/lisp/gnus/nntp.el index a086421b049..0d0a0e679fa 100644 --- a/lisp/gnus/nntp.el +++ b/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.") From 8ec2ddebdd4ff92aa07a9a7a0881bd3e762acee3 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 28 Jul 2025 16:14:44 +0300 Subject: [PATCH 2/6] ; Update documentation of GC in ELisp manual * doc/lispref/internals.texi (Garbage Collection): Update default values for GC-related thresholds. (Bug#79074) --- doc/lispref/internals.texi | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index cc82a03db98..939cd489241 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -555,16 +555,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. @@ -585,6 +586,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 From f20d5e63bc052985c5681e583ca48309f44ff515 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 29 Jul 2025 14:08:29 +0300 Subject: [PATCH 3/6] ; * lisp/image.el (image-supported-file-p): Doc fix (bug#79117). --- lisp/image.el | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lisp/image.el b/lisp/image.el index 0be57cadb2b..2432b5727ce 100644 --- a/lisp/image.el +++ b/lisp/image.el @@ -414,10 +414,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 From 456f44a7b3cee7ac6dd3b13dc6690d14f5dd3603 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Wed, 30 Jul 2025 19:48:07 +0300 Subject: [PATCH 4/6] ; Improve documentation of change hooks * doc/lispref/text.texi (Change Hooks): Warn against buffer changes in the hook functions. (Bug#79115) --- doc/lispref/text.texi | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 8329a67d6c2..dc35e93f2da 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -6291,7 +6291,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 From 9e3720bbb116193c7866ae04d35afa34f5451fa6 Mon Sep 17 00:00:00 2001 From: James Thomas Date: Wed, 30 Jul 2025 01:54:43 +0530 Subject: [PATCH 5/6] * doc/misc/gnus.texi (Category Syntax): Update gnus-agent-predicate. This updates the Gnus manual due to recent code change (bug#79123). --- doc/misc/gnus.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 662f2f21301..dfeecb079c7 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -18864,7 +18864,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 From 477335a10ba6d91dc1600b2a05ea202d4b851417 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 2 Aug 2025 17:33:15 +0300 Subject: [PATCH 6/6] ; Fix documentation of 'find-file-noselect' * doc/lispref/files.texi (Visiting Functions): * lisp/files.el (find-file-noselect): Document that NOWARN non-nil also bypasses the file's last change verification. (Bug#79127) --- doc/lispref/files.texi | 10 ++++++---- lisp/files.el | 4 +++- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index c285cd1c683..d69bc46cd2c 100644 --- a/doc/lispref/files.texi +++ b/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 diff --git a/lisp/files.el b/lisp/files.el index c288a5a8b26..6544ee54ee4 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -2502,7 +2502,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