From 03fa832b4dcc47276894d90f3323bca31eb0633e Mon Sep 17 00:00:00 2001
From: Michael Albinus <michael.albinus@gmx.de>
Date: Sun, 3 Nov 2024 15:48:19 +0100
Subject: [PATCH] Improve Tramp documentation on direct async processes

* doc/misc/tramp.texi (Remote processes): Add another example
enabling direct async processes based on method name.  (Bug#74105)

* etc/NEWS: Rephrase Tramp entry on direct async processes.
---
 doc/misc/tramp.texi | 12 ++++++++++++
 etc/NEWS            | 10 ++++++----
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 69572a139ff..9895b3c6fce 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -4549,6 +4549,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 b/etc/NEWS
index ebb9d49d560..fbc29206039 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -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'.