More small edits for doc/lispref/processes.texi

* doc/lispref/processes.texi (Asynchronous Processes, Deleting Processes):
Copyedits.
(Asynchronous Processes): Update some example output.

2 files changed, 35 insertions, 25 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index fd531721553..74c32ccb7bb 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,9 +1,11 @@
 2012-04-15  Glenn Morris  <rgm@gnu.org>
 
         * processes.texi (Processes, Subprocess Creation, Shell Arguments):
-        (Synchronous Processes): Copyedits.
+        (Synchronous Processes, Asynchronous Processes, Deleting Processes):
+        Copyedits.
         (Subprocess Creation): Discourage modifying exec-path directly.
-        (Synchronous Processes): Update some example output.
+        (Synchronous Processes, Asynchronous Processes):
+        Update some example output.
         (Process Information): Fix typo.
         (Bindat Spec): Use Texinfo-recommended form of quote+punctuation.
 
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 0f1c291bdcd..509b3a1c2c6 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -496,6 +496,7 @@ inputinput@point{}
  "-c" command)        ; @r{arguments for the shell}
 @end group
 @end smallexample
+@c It actually uses shell-command-switch, but no need to mention that here.
 @end defun
 
 @defun call-process-shell-command command &optional infile destination display &rest args
@@ -562,7 +563,8 @@ The remaining arguments, @var{args}, are strings that specify command
 line arguments for the program.
 
 In the example below, the first process is started and runs (rather,
-sleeps) for 100 seconds.  Meanwhile, the second process is started, and
+sleeps) for 100 seconds (the output buffer @samp{foo} is created
+immediately).  Meanwhile, the second process is started, and
 given the name @samp{my-process<1>} for the sake of uniqueness.  It
 inserts the directory listing at the end of the buffer @samp{foo},
 before the first process finishes.  Then it finishes, and a message to
@@ -576,13 +578,15 @@ finishes, and another message is inserted in the buffer for it.
 @end group
 
 @group
-(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+(start-process "my-process" "foo" "ls" "-l" "/bin")
      @result{} #<process my-process<1>>
 
 ---------- Buffer: foo ----------
-total 2
-lrwxrwxrwx  1 lewis     14 Jul 22 10:12 gnuemacs --> /emacs
--rwxrwxrwx  1 lewis     19 Jul 30 21:02 lemon
+total 8336
+-rwxr-xr-x 1 root root 971384 Mar 30 10:14 bash
+-rwxr-xr-x 1 root root 146920 Jul  5  2011 bsd-csh
+@dots{}
+-rwxr-xr-x 1 root root 696880 Feb 28 15:55 zsh4
 
 Process my-process<1> finished
 
@@ -595,45 +599,49 @@ 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, and returns its process
-object---when @code{default-directory} is not a magic file name.
+object.
 
-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.
+The difference from @code{start-process} is that this function may
+invoked a file handler based on the value of @code{default-directory}.
+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.
 
 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}).
+the resulting process object.  @xref{Filter Functions}, and @ref{Sentinels}.
 
+@c FIXME  Can we find a better example (i.e. a more modern function
+@c that is actually documented).
 Some file handlers may not support @code{start-file-process} (for
-example @code{ange-ftp-hook-function}).  In such cases, the function
-does nothing and returns @code{nil}.
+example the function @code{ange-ftp-hook-function}).  In such cases,
+this function does nothing and returns @code{nil}.
 @end defun
 
 @defun start-process-shell-command name buffer-or-name command
-This function is like @code{start-process} except that it uses a shell
+This function is like @code{start-process}, except that it uses a shell
 to execute the specified command.  The argument @var{command} is a shell
 command name.  The variable @code{shell-file-name} specifies which shell to
 use.
 
 The point of running a program through the shell, rather than directly
 with @code{start-process}, is so that you can employ shell features such
-as wildcards in the arguments.  It follows that if you include an
-arbitrary user-specified arguments in the command, you should quote it
+as wildcards in the arguments.  It follows that if you include any
+arbitrary user-specified arguments in the command, you should quote them
 with @code{shell-quote-argument} first, so that any special shell
 characters do @emph{not} have their special shell meanings.  @xref{Shell
-Arguments}.
+Arguments}.  Of course, when executing commands based on user input
+you should also consider the security implications.
 @end defun
 
 @defun start-file-process-shell-command name buffer-or-name command
 This function is like @code{start-process-shell-command}, but uses
-@code{start-file-process} internally.  By this, @var{command} can be
-executed also on remote hosts, depending on @code{default-directory}.
+@code{start-file-process} internally.  Because of this, @var{command}
+can also be executed on remote hosts, depending on @code{default-directory}.
 @end defun
 
 @defvar process-connection-type
@@ -658,7 +666,7 @@ with one subprocess by binding the variable around the call to
 
 @smallexample
 @group
-(let ((process-connection-type nil))  ; @r{Use a pipe.}
+(let ((process-connection-type nil))  ; @r{use a pipe}
   (start-process @dots{}))
 @end group
 @end smallexample
@@ -675,9 +683,9 @@ Information}).
   @dfn{Deleting a process} disconnects Emacs immediately from the
 subprocess.  Processes are deleted automatically after they terminate,
 but not necessarily right away.  You can delete a process explicitly
-at any time.  If you delete a terminated process explicitly before it
+at any time.  If you explicitly delete a terminated process before it
 is deleted automatically, no harm results.  Deleting a running
-process sends a signal to terminate it (and its child processes if
+process sends a signal to terminate it (and its child processes, if
 any), and calls the process sentinel if it has one.  @xref{Sentinels}.
 
   When a process is deleted, the process object itself continues to