Merge from origin/emacs-30

3231af3727b Improve 'open-network-stream' documentation.
fb55431c44e ; Fix typos in case-conversion descriptions
83f095d1fd4 ; Fix typo and indexing in the ELisp manual
37b1799c9e5 ; Instrument proced-tests.el further
03fa832b4dc Improve Tramp documentation on direct async processes

# Conflicts:
#	etc/NEWS

8 files changed, 57 insertions, 28 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 91f6f3b0d97..2d90f22e087 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6024,8 +6024,9 @@ is platform dependent, but should be equivalent to bilinear
 filtering.  Disabling smoothing will use the nearest neighbor
 algorithm.
 
+@vindex image-transform-smoothing
 If this property is not specified, @code{create-image} will use the
-@code{image-transform-smoothing} user option to say whether scaling
+@code{image-transform-smoothing} user option to say whether smoothing
 should be done or not.  This option can be @code{nil} (no smoothing),
 @code{t} (use smoothing) or a predicate function that's called with
 the image object as the only parameter, and should return either
@@ -7026,12 +7027,13 @@ Here is an example of using @code{image-load-path-for-library}:
 @end example
 @end defun
 
-@vindex image-scaling-factor
+@vindex image-scaling-factor, and automatic image scaling
 Images are automatically scaled when created based on the
 @code{image-scaling-factor} variable.  The value is either a floating
 point number (where numbers higher than 1 means to increase the size
 and lower means to shrink the size), or the symbol @code{auto}, which
-will compute a scaling factor based on the font pixel size.
+will compute a scaling factor based on the font pixel size.  @xref{Image
+Descriptors}.
 
 @node Showing Images
 @subsection Showing Images
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index cb32c7671e7..87503a45075 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -631,30 +631,30 @@ is @code{nil}, which means the character itself.
 @item special-uppercase
 Corresponds to Unicode language- and context-independent special upper-casing
 rules.  The value of this property is a string (which may be empty).  For
-example mapping for U+00DF @sc{latin small letter sharp s} is
+example for U+00DF @sc{latin small letter sharp s} the value is
 @code{"SS"}.  This mapping overrides the @code{uppercase} property, and
 thus the current case table.  For characters with no special mapping,
-the value is @code{nil}, which means @code{uppercase} property needs to
+the value is @code{nil}, which means the @code{uppercase} property needs to
 be consulted instead.
 
 @item special-lowercase
 Corresponds to Unicode language- and context-independent special
 lower-casing rules.  The value of this property is a string (which may
-be empty).  For example mapping for U+0130 @sc{latin capital letter i
-with dot above} the value is @code{"i\u0307"} (i.e. 2-character string
+be empty).  For example for U+0130 @sc{latin capital letter i
+with dot above} the value is @code{"i\u0307"} (i.e. a 2-character string
 consisting of @sc{latin small letter i} followed by U+0307
 @sc{combining dot above}).  This mapping overrides the @code{lowercase}
 property, and thus the current case table.  For characters with no
-special mapping, the value is @code{nil}, which means @code{lowercase}
+special mapping, the value is @code{nil}, which means the @code{lowercase}
 property needs to be consulted instead.
 
 @item special-titlecase
 Corresponds to Unicode unconditional special title-casing rules.  The value of
-this property is a string (which may be empty).  For example mapping for
+this property is a string (which may be empty).  For example for
 U+FB01 @sc{latin small ligature fi} the value is @code{"Fi"}.  This
 mapping overrides the @code{titlecase} property, and thus the current
 case table.  For characters with no special mapping, the value is
-@code{nil}, which means @code{titlecase} property needs to be consulted
+@code{nil}, which means the @code{titlecase} property needs to be consulted
 instead.
 @end table
 
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 53468e0d252..2c19275f946 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -2686,10 +2686,12 @@ If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs
 doesn't have built-in @acronym{TLS} support.
 
 @item :warn-unless-encrypted @var{boolean}
-If non-@code{nil}, and @code{:return-value} is also non-@code{nil},
-Emacs will warn if the connection isn't encrypted.  This is useful for
-protocols like @acronym{IMAP} and the like, where most users would
-expect the network traffic to be encrypted.
+If non-@code{nil}, warn the user if the final connection type is not
+encrypted.  This is useful for protocols like @acronym{IMAP} and the
+like, where most users would expect the network traffic to be encrypted.
+This may be due to @acronym{STARTTLS} upgrade failure, specifying
+@code{:return-list} non-@code{nil} allows you to capture any error
+encountered.
 
 @vindex network-stream-use-client-certificates
 @item :client-certificate @var{list-or-t}
@@ -2715,6 +2717,9 @@ If non-@code{nil}, the greeting string returned by the host.
 If non-@code{nil}, the host's capability string.
 @item :type @var{symbol}
 The connection type: @samp{plain} or @samp{tls}.
+@item :error @var{symbol}
+A string describing any error encountered when perfoming
+@acronym{STARTTLS} upgrade.
 @end table
 
 @item :shell-command @var{string-or-nil}
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index c2b18387ad5..efeddf1a20c 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -1593,7 +1593,7 @@ be made.
 
   Other characters can also have special case-conversion rules.  They
 all have non-@code{nil} character properties @code{special-uppercase},
-@code{special-lowercase} or @code{special-titlecase} (@pxref{Character
+@code{special-lowercase}, or @code{special-titlecase} (@pxref{Character
 Properties}) defined by the Unicode Standard.  These properties define
 special case-conversion rules which override the current case table
 (@pxref{Case Tables}).
@@ -1640,11 +1640,11 @@ maps for both lower case and upper case.
   Some characters have special case-conversion rules defined for them,
 which by default override the current case table.  These characters have
 non-@code{nil} character properties @code{special-uppercase},
-@code{special-lowercase} or @code{special-titlecase} (@pxref{Character
+@code{special-lowercase}, or @code{special-titlecase} (@pxref{Character
 Properties}) defined by the Unicode Standard.  An example is U+00DF
 LATIN SMALL LETTER SHARP S, @ss{}, which by default up-cases to the
 string @code{"SS"}, not to U+1E9E LATIN CAPITAL LETTER SHARP S@.  To
-force these characters follow the case-table conversions, set the
+force these characters to follow the case-table conversions, set the
 corresponding Unicode property to @code{nil}:
 
 @example
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index a014319c02c..5afc41b3a4b 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -4631,6 +4631,18 @@ which must be set to a non-@code{nil} value.  Example:
 @end group
 @end lisp
 
+This enables direct async processes for the host @samp{remotehost}.
+If you want to enable direct async processes for all remote hosts
+connected via the same method (e.g., @option{ssh}), use instead
+
+@lisp
+@group
+(connection-local-set-profiles
+ '(:application tramp :protocol "ssh")
+ 'remote-direct-async-process)
+@end group
+@end lisp
+
 Using direct asynchronous processes in @value{tramp} is not possible,
 if the remote host is connected via multiple hops
 (@pxref{Multi-hops}).  In this case, @value{tramp} falls back to its
diff --git a/etc/NEWS.30 b/etc/NEWS.30
index c72a87787f3..3c765b97542 100644
--- a/etc/NEWS.30
+++ b/etc/NEWS.30
@@ -1413,10 +1413,12 @@ method but "sudo" can be configured with user option
 +++
 *** Direct asynchronous processes are indicated by a connection-local variable.
 If direct asynchronous processes shall be used, set the connection-local
-variable 'tramp-direct-async-process' to a non-nil value.  This has been
-changed, in previous Emacs versions this was indicated by the now
-deprecated connection property "direct-async-process".  See the Tramp
-manual "(tramp) Improving performance of asynchronous remote processes".
+variable 'tramp-direct-async-process' to a non-nil value.  In previous
+Emacs versions this was indicated by the connection property
+"direct-async-process".  That connection property (though not connection
+properties and 'tramp-connection-properties' in general) is now
+deprecated.  See the Tramp manual "(tramp) Improving performance of
+asynchronous remote processes".
 
 ---
 *** Direct asynchronous processes use 'tramp-remote-path'.
diff --git a/lisp/net/network-stream.el b/lisp/net/network-stream.el
index dcb3ad61f6d..89d3e4f19c1 100644
--- a/lisp/net/network-stream.el
+++ b/lisp/net/network-stream.el
@@ -117,15 +117,18 @@ values:
 used to decode and encode the data which the process reads and
 writes.  See `make-network-process' for details.
 
-:return-list specifies this function's return value.
-  If omitted or nil, return a process object.  A non-nil means to
-  return (PROC . PROPS), where PROC is a process object and PROPS
-  is a plist of connection properties, with these keywords:
+:return-list controls the form of the function's return value.
+  If omitted or nil, return a process object.  Anything else means to
+  return (PROC . PROPS), where PROC is a process object, and PROPS is a
+  plist of connection properties, which may include the following
+  keywords:
    :greeting -- the greeting returned by HOST (a string), or nil.
    :capabilities -- a string representing HOST's capabilities,
                     or nil if none could be found.
    :type -- the resulting connection type; `plain' (unencrypted)
             or `tls' (TLS-encrypted).
+   :error -- A string describing any error when attempting
+             to negotiate STARTTLS.
 
 :end-of-command specifies a regexp matching the end of a command.
 
@@ -164,8 +167,9 @@ writes.  See `make-network-process' for details.
 :use-starttls-if-possible is a boolean that says to do opportunistic
 STARTTLS upgrades even if Emacs doesn't have built-in TLS functionality.
 
-:warn-unless-encrypted is a boolean which, if :return-list is
-non-nil, is used warn the user if the connection isn't encrypted.
+:warn-unless-encrypted, if non-nil, warn the user if the connection
+isn't encrypted (i.e. STARTTLS failed).  Additionally, setting
+:return-list non-nil allows capturing any error response.
 
 :nogreeting is a boolean that can be used to inhibit waiting for
 a greeting from the server.
diff --git a/test/lisp/proced-tests.el b/test/lisp/proced-tests.el
index 9036c15271c..3dc7e065afa 100644
--- a/test/lisp/proced-tests.el
+++ b/test/lisp/proced-tests.el
@@ -50,7 +50,11 @@
 (defun proced--assert-process-valid-cpu-refinement (cpu)
   "Fail unless the process at point could be present after a refinement using CPU."
   (proced--move-to-column "%CPU")
-  (>= (thing-at-point 'number) cpu))
+  (condition-case err
+      (>= (thing-at-point 'number) cpu)
+    (error
+     (ert-fail
+      (list err (proced--assert-process-valid-cpu-refinement-explainer cpu))))))
 
 (defun proced--assert-process-valid-cpu-refinement-explainer (cpu)
   "Explain the result of `proced--assert-process-valid-cpu-refinement'.