(Asynchronous Processes): Clarify doc of start-file-process.

2 files changed, 16 insertions, 9 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 75d40dbd19c..ea3e18da52b 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2007-08-16  Richard Stallman  <rms@gnu.org>
+
+	* processes.texi (Asynchronous Processes): Clarify
+	doc of start-file-process.
+
 2007-08-08  Martin Rudalics  <rudalics@gmx.at>
 
 	* modes.texi (Example Major Modes): Fix typo.
diff --git a/lispref/processes.texi b/lispref/processes.texi
index 535c8c3f256..f7be990b85e 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -503,23 +503,25 @@ Process my-process finished
 
 @defun start-file-process name buffer-or-name program &rest args
 Like @code{start-process}, this function starts a new asynchronous
-subprocess running @var{program} in it.  The corresponding process
-object is returned.
+subprocess running @var{program} in it, and returns its process
+object---when @code{default-directory} is not a magic file name.
 
-If @code{default-directory} corresponds to a file handler, that
-handler is invoked.  @var{program} runs then on a remote host which is
-identified by @code{default-directory}.  The local part of
-@code{default-directory} is the working directory of the subprocess.
+If @code{default-directory} is magic, the function invokes its file
+handler instead.  This handler ought to run @var{program}, perhaps on
+the local host, perhaps on a remote host that corresponds to
+@code{default-directory}.  In the latter case, the local part of
+@code{default-directory} becomes the working directory of the process.
 
-@var{program} and @var{program-args} might be file names.  They are not
-objects of file handler invocation.
+This function does not try to invoke file name handlers for
+@var{program} or for the @var{program-args}.
 
 Depending on the implementation of the file handler, it might not be
 possible to apply @code{process-filter} or @code{process-sentinel} to
 the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}).
 
 Some file handlers may not support @code{start-file-process} (for
-example @code{ange-ftp-hook-function}).  It returns then @code{nil}.
+example @code{ange-ftp-hook-function}).  In such cases, the function
+does nothing and returns @code{nil}.
 @end defun
 
 @defun start-process-shell-command name buffer-or-name command &rest command-args